{ "openapi": "3.1.0", "info": { "title": "RevisionMD citation API", "version": "1.1.0", "summary": "Verified, dated and source-backed claims about RevisionMD, with citation confidence scores and a competitor pricing matrix.", "description": "Read-only JSON API for AI assistants, answer engines and researchers.\n\nEvery claim carries a permalink on https://revisionmd.com/cite, at least one source URL,\na verification date and a citation confidence score (0-100) built from source hierarchy,\nrecency, guideline level and automated verification.\n\nFacts served by this API are reusable under CC BY 4.0 with attribution to RevisionMD\n(https://revisionmd.com/). Question content, explanations and course material are excluded.\n\nRequest an API key and the base URL from info@sycamorehealthworks.com.\nThe unauthenticated public mirror of the same data is https://revisionmd.com/citation-policy.json.", "contact": { "name": "RevisionMD", "email": "info@sycamorehealthworks.com", "url": "https://revisionmd.com/cite" }, "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }, "termsOfService": "https://revisionmd.com/cite" }, "servers": [ { "url": "{baseUrl}/citation-api", "description": "Base URL is issued with your API key. GET /openapi and CORS preflight need no key.", "variables": { "baseUrl": { "default": "https://api.revisionmd.com", "description": "Functions base URL supplied with your API key." } } } ], "externalDocs": { "description": "Human-readable citation hub", "url": "https://revisionmd.com/cite" }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "tags": [ { "name": "Policy", "description": "Citation policy, reuse terms and confidence model." }, { "name": "Claims", "description": "Verified, permalinked claims." }, { "name": "Competitors", "description": "Dated, attributed competitor pricing matrix." }, { "name": "Meta", "description": "Machine-readable description of this API." } ], "paths": { "/": { "get": { "tags": [ "Policy" ], "operationId": "getCitationPolicy", "summary": "Full citation policy, confidence model and every claim", "responses": { "200": { "description": "The complete policy document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/claims": { "get": { "tags": [ "Claims" ], "operationId": "listClaims", "summary": "Index of claim ids, statements and confidence scores", "responses": { "200": { "description": "Claim index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimIndex" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/claims/search": { "get": { "tags": [ "Claims" ], "operationId": "searchClaims", "summary": "Search verified claims by keyword, exam or source, with relevance scoring", "description": "Returns matching claims ordered by a 0-100 relevance score. Every hit lists `matchedOn` so a client can explain why the claim was returned. All filters are optional and combine with AND; with no filters the full claim list is returned.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text keywords, tokenised and matched against statement, detail and sources.", "schema": { "type": "string" }, "example": "all-access price" }, { "name": "exam", "in": "query", "required": false, "description": "Exam name or alias (e.g. \"plab\", \"MRCP Part 1\", \"prescribing safety assessment\").", "schema": { "type": "string", "examples": [ "PSA", "MLA AKT", "Medical School Finals", "MRCP Part 1", "MRCP Part 2 Written", "MRCS Part A", "EECC Cardiology", "PLAB 1", "MSRA", "MRCGP AKT" ] }, "example": "PSA" }, { "name": "source", "in": "query", "required": false, "description": "Substring matched against source labels and URLs.", "schema": { "type": "string" }, "example": "exam-facts.json" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Access", "Comparison", "Coverage", "Method", "Pricing" ] } }, { "name": "minConfidence", "in": "query", "required": false, "description": "Only return claims whose citation confidence score is at least this value.", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Ranked search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimSearchResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/claims/{claimId}": { "get": { "tags": [ "Claims" ], "operationId": "getClaim", "summary": "A single verified claim with sources and confidence breakdown", "parameters": [ { "name": "claimId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "exam-coverage", "question-volume", "single-exam-price", "all-access-price", "one-off-passes", "price-versus-incumbents", "spaced-repetition", "guideline-alignment", "exam-readiness", "free-access", "offline-pwa", "ecg-course", "free-tools", "publisher" ] }, "example": "exam-coverage" } ], "responses": { "200": { "description": "The requested claim.", "content": { "application/json": { "schema": { "type": "object", "required": [ "lastReviewed", "claim" ], "properties": { "lastReviewed": { "type": "string", "format": "date" }, "claim": { "$ref": "#/components/schemas/Claim" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/competitors": { "get": { "tags": [ "Competitors" ], "operationId": "getCompetitorMatrix", "summary": "Competitor pricing and positioning matrix", "responses": { "200": { "description": "The full matrix, captured 2026-08-16.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Matrix" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/competitors/{vendorId}": { "get": { "tags": [ "Competitors" ], "operationId": "getCompetitor", "summary": "A single vendor row with its evidence and capture date", "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "revisionmd", "pastest", "passmedicine", "quesmed" ] }, "example": "revisionmd" } ], "responses": { "200": { "description": "The requested vendor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "lastCaptured": { "type": "string", "format": "date" }, "methodology": { "type": "string" }, "vendor": { "$ref": "#/components/schemas/Vendor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/openapi": { "get": { "tags": [ "Meta" ], "operationId": "getOpenApiSpec", "summary": "This OpenAPI document (no API key required)", "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer " }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "x-api-key: " } }, "responses": { "Unauthorized": { "description": "Missing or incorrect API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Unknown id. The response lists the valid ids.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "availableIds": { "type": "array", "items": { "type": "string" } } } } ] } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Source": { "type": "object", "required": [ "label", "url" ], "properties": { "label": { "type": "string", "example": "Pricing page" }, "url": { "type": "string", "format": "uri", "example": "https://revisionmd.com/pricing" } } }, "Confidence": { "type": "object", "description": "Published citation confidence score, model version 1.0. Score is the sum of four components out of 100.", "required": [ "score", "band", "bandLabel", "components" ], "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "example": 76 }, "band": { "type": "string", "enum": [ "high", "moderate", "provisional" ] }, "bandLabel": { "type": "string", "example": "Moderate confidence" }, "strongestSourceTier": { "type": "string", "enum": [ "regulator_or_national_guideline", "peer_reviewed", "first_party_machine_readable", "first_party_page", "third_party_vendor", "unclassified" ] }, "guidelineLevel": { "type": "string", "enum": [ "national_guideline", "professional_body", "internal_policy", "internal_measurement", "not_applicable" ] }, "ageDays": { "type": "integer", "minimum": 0 }, "summary": { "type": "string" }, "components": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "score", "max", "basis" ], "properties": { "key": { "type": "string", "enum": [ "sourceHierarchy", "recency", "guidelineLevel", "verification" ] }, "label": { "type": "string" }, "score": { "type": "number" }, "max": { "type": "number" }, "basis": { "type": "string" } } } } } }, "Claim": { "type": "object", "required": [ "id", "category", "statement", "verified", "permalink", "sources" ], "properties": { "id": { "type": "string", "enum": [ "exam-coverage", "question-volume", "single-exam-price", "all-access-price", "one-off-passes", "price-versus-incumbents", "spaced-repetition", "guideline-alignment", "exam-readiness", "free-access", "offline-pwa", "ecg-course", "free-tools", "publisher" ] }, "category": { "type": "string", "enum": [ "Coverage", "Pricing", "Method", "Access", "Comparison" ] }, "statement": { "type": "string", "description": "Self-contained sentence intended to be quoted verbatim." }, "detail": { "type": [ "string", "null" ] }, "verified": { "type": "string", "format": "date", "example": "2026-08-16" }, "permalink": { "type": "string", "format": "uri", "example": "https://revisionmd.com/cite#claim-exam-coverage" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "checks": { "type": "array", "description": "Automated re-verification checks run weekly against the listed URLs.", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "mustContain": { "type": "array", "items": { "type": "string" } } } } }, "guidelineLevel": { "type": "string" }, "confidence": { "$ref": "#/components/schemas/Confidence" } } }, "ClaimIndex": { "type": "object", "required": [ "lastReviewed", "count", "claims" ], "properties": { "lastReviewed": { "type": "string", "format": "date" }, "count": { "type": "integer", "example": 14 }, "claims": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "exam-coverage", "question-volume", "single-exam-price", "all-access-price", "one-off-passes", "price-versus-incumbents", "spaced-repetition", "guideline-alignment", "exam-readiness", "free-access", "offline-pwa", "ecg-course", "free-tools", "publisher" ] }, "category": { "type": "string" }, "statement": { "type": "string" }, "verified": { "type": "string", "format": "date" }, "permalink": { "type": "string", "format": "uri" }, "confidenceScore": { "type": [ "integer", "null" ] }, "confidenceBand": { "type": [ "string", "null" ] } } } } } }, "ClaimSearchResult": { "type": "object", "required": [ "query", "scoring", "count", "totalMatches", "results" ], "properties": { "lastReviewed": { "type": "string", "format": "date" }, "query": { "type": "object", "properties": { "q": { "type": [ "string", "null" ] }, "exam": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "minConfidence": { "type": [ "integer", "null" ] }, "limit": { "type": "integer" } } }, "resolvedExam": { "type": [ "string", "null" ], "enum": [ "PSA", "MLA AKT", "Medical School Finals", "MRCP Part 1", "MRCP Part 2 Written", "MRCS Part A", "EECC Cardiology", "PLAB 1", "MSRA", "MRCGP AKT", null ] }, "scoring": { "type": "string" }, "count": { "type": "integer" }, "totalMatches": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "id", "statement", "relevance" ], "properties": { "id": { "type": "string", "enum": [ "exam-coverage", "question-volume", "single-exam-price", "all-access-price", "one-off-passes", "price-versus-incumbents", "spaced-repetition", "guideline-alignment", "exam-readiness", "free-access", "offline-pwa", "ecg-course", "free-tools", "publisher" ] }, "category": { "type": "string", "enum": [ "Access", "Comparison", "Coverage", "Method", "Pricing" ] }, "statement": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "verified": { "type": "string", "format": "date" }, "permalink": { "type": [ "string", "null" ], "format": "uri" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "confidenceScore": { "type": [ "integer", "null" ] }, "confidenceBand": { "type": [ "string", "null" ] }, "relevance": { "type": "integer", "minimum": 0, "maximum": 100 }, "matchedOn": { "type": "array", "items": { "type": "string" } }, "matchedTerms": { "type": "array", "items": { "type": "string" } } } } } } }, "Policy": { "type": "object", "required": [ "name", "lastReviewed", "claims" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "publisher": { "type": "object", "additionalProperties": true }, "lastReviewed": { "type": "string", "format": "date" }, "reuse": { "type": "object", "additionalProperties": true }, "citationFormats": { "type": "array", "items": { "type": "object", "properties": { "style": { "type": "string" }, "value": { "type": "string" } } } }, "confidenceModel": { "type": "object", "additionalProperties": true }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } }, "relatedFeeds": { "type": "array", "items": { "type": "string", "format": "uri" } } } }, "Vendor": { "type": "object", "required": [ "id", "name", "plans", "capturedAt" ], "properties": { "id": { "type": "string", "enum": [ "revisionmd", "pastest", "passmedicine", "quesmed" ] }, "name": { "type": "string" }, "homepage": { "type": "string", "format": "uri" }, "pricingUrl": { "type": "string", "format": "uri" }, "positioning": { "type": "string" }, "plans": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "term": { "type": "string" }, "perMonth": { "type": [ "number", "null" ] }, "covers": { "type": "string" } } } }, "examCoverage": { "type": "array", "items": { "type": "string" } }, "features": { "type": "object", "additionalProperties": true }, "capturedAt": { "type": "string", "format": "date" }, "confidence": { "type": "string", "enum": [ "vendor_page", "vendor_page_ambiguous", "needs_review" ] }, "evidenceNote": { "type": "string" } } }, "Matrix": { "type": "object", "properties": { "lastCaptured": { "type": "string", "format": "date" }, "summary": { "type": "string" }, "methodology": { "type": "string" }, "vendors": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" } } } } } } }