{ "openapi": "3.1.0", "info": { "title": "xCures API", "version": "3" }, "servers": [ { "url": "https://api.xcures.com/v3" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Identity", "description": "Who the API takes you to be. Confirm that a credential carries the identity, organization, projects and permissions you expect before making real calls." }, { "name": "Documents", "description": "Documents on a patient's record: their metadata and their files, read one at a time within a project your credential spans." }, { "name": "Checklists", "description": "Clinical checklists evaluated against a patient's records: evaluate one patient at a time, or run a job that evaluates one checklist for many patients and page through its results." }, { "name": "Patients", "description": "The patients in a project: find them by who they are, read one, and add one under an id you choose." }, { "name": "Queries", "description": "Queries across the health information networks for a patient's records from care sites outside xCures: start one for a patient, then read it to see how far it has reached." }, { "name": "Webhooks", "description": "Subscriptions that deliver events to HTTPS endpoints of yours, signed with your organization's key: manage them, and read the public keys you verify deliveries with." } ], "paths": { "/checklists": { "get": { "operationId": "listChecklists", "summary": "List Checklists", "description": "List the checklists for the given project.", "tags": [ "Checklists" ], "parameters": [ { "$ref": "#/components/parameters/ChecklistProjectId" } ], "responses": { "200": { "description": "The project's checklists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistList" }, "examples": { "one": { "value": { "checklists": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "Pre-operative clearance", "sortOrder": 1, "items": [ { "id": "1f3c5b2a-8d4e-4f6a-9b0c-2d7e8f9a1b3c", "libraryItemId": "recent-echocardiogram", "name": "Echocardiogram within the last 12 months", "sortOrder": 1 } ] } ] } } } } } }, "403": { "$ref": "#/components/responses/ChecklistForbidden" }, "404": { "$ref": "#/components/responses/ChecklistNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Fhir_Read" ] }, { "bearer": [ "Summary_Checklist" ] } ] } }, "/checklists/{checklistId}/evaluations": { "post": { "operationId": "evaluateChecklist", "summary": "Evaluate a Checklist", "description": "Evaluate one checklist for one patient. An evaluation can take up to 150 seconds; a request cut off before it answers is answered 503 with `Retry-After`. To evaluate without waiting, start an evaluation job instead.", "tags": [ "Checklists" ], "parameters": [ { "$ref": "#/components/parameters/ChecklistProjectId" }, { "$ref": "#/components/parameters/ChecklistId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistEvaluationRequest" }, "examples": { "one": { "value": { "patientId": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57" } } } } } }, "responses": { "201": { "description": "The patient's evaluation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistEvaluation" }, "examples": { "one": { "value": { "patientId": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "checklistId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "documentIds": [ "e3b0c442-98fc-4c14-9afb-f4c8996fb924" ], "items": [ { "checklistItem": { "id": "1f3c5b2a-8d4e-4f6a-9b0c-2d7e8f9a1b3c", "libraryItemId": "recent-echocardiogram", "name": "Echocardiogram within the last 12 months", "sortOrder": 1 }, "checklistItemDefinitionId": null, "checklistItemDefinitionVersionId": null, "documentIds": [ "e3b0c442-98fc-4c14-9afb-f4c8996fb924" ], "clinicalConcepts": [], "documentSections": [ { "documentId": "e3b0c442-98fc-4c14-9afb-f4c8996fb924", "sectionType": "ccda", "section": "51848-0", "sectionTitle": null, "documentName": "Cardiology consult note", "documentLocation": null, "documentContentType": "text/xml", "documentDate": "2025-10-06T14:30:00.000Z" } ], "result": { "answer": true } } ] } } } } } }, "403": { "$ref": "#/components/responses/ChecklistForbidden" }, "404": { "$ref": "#/components/responses/ChecklistNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Fhir_Read" ] }, { "bearer": [ "Summary_Checklist" ] } ] } }, "/checklists/{checklistId}/evaluation-jobs": { "post": { "operationId": "startChecklistEvaluationJob", "summary": "Create a Checklist Evaluation Job", "description": "Start a job that evaluates the checklist for each patient. You may read its status and retrieve the results by using the `jobId` it returns.", "tags": [ "Checklists" ], "parameters": [ { "$ref": "#/components/parameters/ChecklistProjectId" }, { "$ref": "#/components/parameters/ChecklistId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistEvaluationJobStart" }, "examples": { "one": { "value": { "jobName": "Pre-op clearance, week of October 6", "patients": [ { "id": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57" } ] } } } } } }, "responses": { "201": { "description": "The job, queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistEvaluationJob" }, "examples": { "queued": { "value": { "jobId": "4b8f2d61-3a9c-4e57-b1d8-6c0e9f2a7d45", "checklistId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "jobName": "Pre-op clearance, week of October 6", "status": "queued", "patientCount": 1, "succeededCount": 0, "failedCount": 0, "submittedAt": "2025-10-06T14:30:00.000Z" } } } } } }, "403": { "$ref": "#/components/responses/ChecklistForbidden" }, "404": { "$ref": "#/components/responses/ChecklistNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Fhir_Read" ] } ] } }, "/checklists/{checklistId}/evaluation-jobs/{jobId}": { "get": { "operationId": "getChecklistEvaluationJob", "summary": "Get a Checklist Evaluation Job", "description": "Read a job's status and progress.", "tags": [ "Checklists" ], "parameters": [ { "$ref": "#/components/parameters/ChecklistProjectId" }, { "$ref": "#/components/parameters/ChecklistId" }, { "$ref": "#/components/parameters/ChecklistEvaluationJobId" } ], "responses": { "200": { "description": "The job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistEvaluationJob" }, "examples": { "completed": { "value": { "jobId": "4b8f2d61-3a9c-4e57-b1d8-6c0e9f2a7d45", "checklistId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "jobName": "Pre-op clearance, week of October 6", "status": "completed", "patientCount": 1, "succeededCount": 1, "failedCount": 0, "submittedAt": "2025-10-06T14:30:00.000Z", "startedAt": "2025-10-06T14:30:02.000Z", "completedAt": "2025-10-06T14:41:37.000Z", "resultsExpiresAt": "2025-10-13T14:41:37.000Z" } } } } } }, "403": { "$ref": "#/components/responses/ChecklistForbidden" }, "404": { "$ref": "#/components/responses/ChecklistNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Fhir_Read" ] } ] } }, "/checklists/{checklistId}/evaluation-jobs/{jobId}/results": { "get": { "operationId": "listChecklistEvaluationJobResults", "summary": "Get a Checklist Evaluation Job's Results", "description": "Page through a finished job's results. A job's results can be read once its status is `completed`, `partially_completed`, `failed` or `cancelled`. Job results are available until its `resultsExpiresAt` is reached.", "tags": [ "Checklists" ], "parameters": [ { "$ref": "#/components/parameters/ChecklistProjectId" }, { "$ref": "#/components/parameters/ChecklistId" }, { "$ref": "#/components/parameters/ChecklistEvaluationJobId" }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's `cursor`; absent for the first page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of the job's results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistEvaluationJobResults" }, "examples": { "one": { "value": { "results": [ { "patientId": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "identifier": "MRN-4820193", "status": "succeeded", "evaluation": { "patientId": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "checklistId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "documentIds": [], "items": [] } }, { "patientId": "2a7c4e91-8f3b-4d06-9c5e-7b1a0d3f6e28", "status": "failed", "failureReason": "subject-not-found" } ] } } } } } }, "400": { "description": "The `cursor` is not one this job's results answered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Your credential lacks the permission this operation requires, or the cohort access to a patient on this page of the job's results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such checklist or job in the project the request names, a job read under a checklist it was not started for, or a job whose `resultsExpiresAt` has passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The job has not finished; its results can be read once it has.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Fhir_Read" ] } ] } }, "/checklists/{checklistId}/evaluation-jobs/{jobId}/cancel": { "post": { "operationId": "cancelChecklistEvaluationJob", "summary": "Cancel a Checklist Evaluation Job", "description": "Cancel a job. Results that finished before the job is cancelled can still be retrieved.", "tags": [ "Checklists" ], "parameters": [ { "$ref": "#/components/parameters/ChecklistProjectId" }, { "$ref": "#/components/parameters/ChecklistId" }, { "$ref": "#/components/parameters/ChecklistEvaluationJobId" } ], "responses": { "200": { "description": "The job, as the cancel leaves it: `cancelling`; unchanged if it had already ended; or `running`, unchanged, if it had finished evaluating and is compiling its results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistEvaluationJob" }, "examples": { "cancelling": { "value": { "jobId": "4b8f2d61-3a9c-4e57-b1d8-6c0e9f2a7d45", "checklistId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "jobName": "Pre-op clearance, week of October 6", "status": "cancelling", "patientCount": 1, "succeededCount": 0, "failedCount": 0, "submittedAt": "2025-10-06T14:30:00.000Z" } } } } } }, "403": { "$ref": "#/components/responses/ChecklistForbidden" }, "404": { "$ref": "#/components/responses/ChecklistNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Fhir_Read" ] } ] } }, "/documents/{documentId}": { "get": { "operationId": "getDocument", "summary": "Get a Document", "description": "Read a document's metadata. Fetch the document's contents via `/documents/{documentId}/content`.", "tags": [ "Documents" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "The document's id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "ProjectId", "in": "header", "required": true, "description": "The project the document belongs to.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document's metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "examples": { "uploaded": { "value": { "id": "e3b0c442-98fc-4c14-9afb-f4c8996fb924", "patientId": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "name": "Discharge summary", "fileName": "discharge-summary.pdf", "contentType": "application/pdf", "source": "userUpload", "documentDate": "2025-10-06T14:30:00.000Z", "createdAt": "2025-10-07T09:12:44.000Z", "updatedAt": "2025-10-07T09:12:44.000Z" } } } } } }, "403": { "description": "Your credential lacks the permission to read documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No document with that id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Document_Read" ] } ] } }, "/documents/{documentId}/content": { "get": { "operationId": "getDocumentContent", "summary": "Get a Document's Contents", "description": "Get a presigned URL valid for fifteen minutes. You can fetch the file from it directly.", "tags": [ "Documents" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "The document's id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "ProjectId", "in": "header", "required": true, "description": "The project the document belongs to.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Where to download the document's file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContent" }, "examples": { "pdf": { "value": { "url": "https://pres-igned/url/discharge-summary.pdf", "fileName": "discharge-summary.pdf", "contentType": "application/pdf" } } } } } }, "403": { "description": "Your credential lacks the permission to read documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No document with that id in the named project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Document_Read" ] } ] } }, "/documents/search": { "post": { "operationId": "searchDocuments", "summary": "Search a Patient's Documents", "description": "Find which of one patient's documents mention something, a page at a time. Send the criteria in the body; every one is optional. A document is found only once the search service has indexed it, so a document just added may not be found yet. Results arrive in the search service's order.", "tags": [ "Documents" ], "parameters": [ { "name": "patientId", "in": "query", "required": true, "description": "The patient whose documents to search.", "schema": { "type": "string", "format": "uuid" } }, { "name": "ProjectId", "in": "header", "required": true, "description": "The project the patient belongs to.", "schema": { "type": "string" } }, { "name": "pageNumber", "in": "query", "required": false, "description": "The page to answer, counting from 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "The most documents to answer on a page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSearch" }, "examples": { "echocardiogram": { "value": { "text": "echocardiogram", "documentDateFrom": "2024-10-01" } } } } } }, "responses": { "200": { "description": "One page of the patient's documents the search found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSearchPage" }, "examples": { "oneDocument": { "value": { "results": [ { "id": "e3b0c442-98fc-4c14-9afb-f4c8996fb924", "patientId": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "name": "Cardiology consult note", "fileName": "cardiology-consult-2025-10-06.xml", "contentType": "text/xml", "source": "ccda", "documentDate": "2025-10-06T14:30:00.000Z", "createdAt": "2025-10-07T09:12:44.000Z", "updatedAt": "2025-10-07T09:12:44.000Z", "classifications": [ "Consult Note" ], "matchingSection": { "sectionType": "ccda", "sectionTitle": "Results", "sectionText": "Left ventricular ejection fraction 55-60%; no wall motion abnormality." } } ], "pageNumber": 1, "pageSize": 20, "totalCount": 1 } } } } } }, "400": { "description": "The request is not a search the operation declares.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Your credential lacks the permission to read documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No patient with that id in the project, or none your credential may see.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Document_Read" ] } ] } }, "/patients/search": { "post": { "operationId": "searchPatients", "summary": "Search Patients", "description": "Find the project's patients by who they are, a page at a time. Send the criteria in the body; a search naming none answers every patient your credential may see. Pages are ordered by last name, then first name, then id, and a page past the last answers no results.", "tags": [ "Patients" ], "parameters": [ { "name": "ProjectId", "in": "header", "required": true, "description": "The project to search.", "schema": { "type": "string" } }, { "name": "pageNumber", "in": "query", "required": false, "description": "The page to answer, counting from 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "The most patients to answer on a page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientSearch" }, "examples": { "byName": { "value": { "lastName": "Rivera", "birthDate": "1968-04-12" } } } } } }, "responses": { "200": { "description": "One page of the patients the search matched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientPage" }, "examples": { "onePatient": { "value": { "results": [ { "id": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "identifier": "K7Q2MX", "firstName": "Elena", "middleName": null, "lastName": "Rivera", "birthDate": "1968-04-12", "sexAtBirth": "F", "externalIdentifiers": [ { "value": "MRN-448120", "system": "Northfield General" } ] } ], "pageNumber": 1, "pageSize": 50, "totalCount": 1 } } } } } }, "400": { "description": "The request is not a search the operation declares.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Your credential lacks the permission to read patients.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/patients/{patientId}": { "get": { "operationId": "getPatient", "summary": "Get a Patient", "description": "Read one patient in the project.", "tags": [ "Patients" ], "parameters": [ { "name": "patientId", "in": "path", "required": true, "description": "The patient's id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "ProjectId", "in": "header", "required": true, "description": "The project the patient belongs to.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The patient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" }, "examples": { "recorded": { "value": { "id": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "identifier": "K7Q2MX", "firstName": "Elena", "middleName": null, "lastName": "Rivera", "additionalNames": null, "birthDate": "1968-04-12", "deathDate": null, "sexAtBirth": "F", "email": "elena.rivera@example.com", "phoneNumber": null, "address": { "line1": "1200 Harbor Way", "line2": null, "city": "Duluth", "state": "MN", "postalCode": "55802" }, "additionalAddresses": [], "externalIdentifiers": [], "createdAt": "2025-09-02T15:20:11.000Z", "updatedAt": "2025-09-02T15:20:11.000Z" } } } } } }, "403": { "description": "Your credential lacks the permission to read patients.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No patient with that id in the project, or none your credential may see.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/patients": { "post": { "operationId": "createPatient", "summary": "Create a Patient", "description": "Add a patient to the project under an id you choose. Creating the same id again, or the same person under another id, answers 409, so a create is safe to repeat after a timeout. Creating a patient starts no records query; create one with `createQuery` when you want the patient's records.", "tags": [ "Patients" ], "parameters": [ { "name": "ProjectId", "in": "header", "required": true, "description": "The project to add the patient to.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientCreate" }, "examples": { "minimal": { "value": { "id": "3c41e8b2-7d05-4f9a-b6e3-8a2d0c5f7e19", "firstName": "Marcus", "lastName": "Okafor", "birthDate": "1951-11-30" } } } } } }, "responses": { "201": { "description": "The patient, as created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" }, "examples": { "created": { "value": { "id": "3c41e8b2-7d05-4f9a-b6e3-8a2d0c5f7e19", "identifier": "P4W9ZT", "firstName": "Marcus", "lastName": "Okafor", "birthDate": "1951-11-30", "address": {}, "createdAt": "2025-09-03T08:02:47.000Z", "updatedAt": "2025-09-03T08:02:47.000Z" } } } } } }, "400": { "description": "The request is not a patient the operation can create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Your credential lacks the permission to create patients.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The project already holds a patient under that id, or the same person under another id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Create" ] } ] } }, "/patients/{patientId}/queries": { "post": { "operationId": "createQuery", "summary": "Create a Query", "description": "Start a query across the health information networks for the patient's records. The query is queued and runs asynchronously; read it with `getQuery` to see how far it has reached. A person signed in needs a role code on file to start one.", "tags": [ "Queries" ], "parameters": [ { "name": "patientId", "in": "path", "required": true, "description": "The patient to retrieve records for.", "schema": { "type": "string", "format": "uuid" } }, { "name": "ProjectId", "in": "header", "required": true, "description": "The project the patient belongs to.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "The query, as queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Query" }, "examples": { "queued": { "value": { "id": "5a0f7c3e-91d2-4b68-a4e7-2c9b8d1f6e03", "patientId": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "createdAt": "2025-09-05T13:40:00.000Z", "status": "initiated" } } } } } }, "400": { "description": "You are signed in as a person with no role code on file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Your credential lacks the permission to create queries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No patient with that id in the project, or none your credential may see.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Query_Create" ] } ] } }, "/queries/{queryId}": { "get": { "operationId": "getQuery", "summary": "Get a Query", "description": "Read one query, to see how far the retrieval of the patient's clinical documents has reached.", "tags": [ "Queries" ], "parameters": [ { "name": "queryId", "in": "path", "required": true, "description": "The query's id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "ProjectId", "in": "header", "required": true, "description": "The project the query's patient belongs to.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Query" }, "examples": { "finished": { "value": { "id": "5a0f7c3e-91d2-4b68-a4e7-2c9b8d1f6e03", "patientId": "9d2e6f14-5b7a-4c83-a0e9-3f1d8c6b2a57", "createdAt": "2025-09-05T13:40:00.000Z", "status": "completed" } } } } } }, "403": { "description": "Your credential lacks the permission to read queries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No query with that id in the project, or none about a patient your credential may see.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Query_Read" ] } ] } }, "/webhooks/subscriptions": { "post": { "operationId": "createWebhookSubscription", "summary": "Create a Webhook Subscription", "description": "Subscribe an HTTPS endpoint of yours to event types. The endpoint must be `https` on port 443 at a public address. Name projects to receive only their events, or none to receive the events of every project of your organization you do not exclude. Name excluded projects to never receive their events, even a project you also name; an event that carries no project is not affected by them. Creating your organization's first subscription creates its signing key.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreate" }, "examples": { "jobs": { "value": { "name": "Checklist job completions", "url": "https://hooks.example.com/xcures", "eventTypes": [ "checklist.evaluation_job.completed" ] } }, "allButOneProject": { "summary": "Every project but one", "value": { "name": "Production job completions", "url": "https://hooks.example.com/xcures", "eventTypes": [ "checklist.evaluation_job.completed" ], "excludedProjectIds": [ "2f1d6b8e-9c47-4a35-8e0b-5d7a3c9f1e62" ] } } } } } }, "responses": { "201": { "description": "The subscription, enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" }, "examples": { "created": { "value": { "id": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "name": "Checklist job completions", "organizationId": "8d2c4e6a-1f3b-4c5d-9e7f-0a2b4c6d8e1f", "projectIds": [], "excludedProjectIds": [], "url": "https://hooks.example.com/xcures", "eventTypes": [ "checklist.evaluation_job.completed" ], "enabled": true, "createdBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "updatedBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "createdAt": "2025-10-06T14:30:00.000Z", "updatedAt": "2025-10-06T14:30:00.000Z", "lastAttemptAt": null } } } } } }, "400": { "$ref": "#/components/responses/WebhookBadRequest" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] }, "get": { "operationId": "listWebhookSubscriptions", "summary": "List Webhook Subscriptions", "description": "List your organization's subscriptions, a page at a time, oldest first, then by id; a page past the last answers no results.", "tags": [ "Webhooks" ], "parameters": [ { "name": "pageNumber", "in": "query", "required": false, "description": "The page to answer, counting from 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "The most subscriptions to answer on a page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "One page of your organization's subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionPage" }, "examples": { "one": { "value": { "results": [ { "id": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "name": "Checklist job completions", "organizationId": "8d2c4e6a-1f3b-4c5d-9e7f-0a2b4c6d8e1f", "projectIds": [], "excludedProjectIds": [], "url": "https://hooks.example.com/xcures", "eventTypes": [ "checklist.evaluation_job.completed" ], "enabled": true, "createdBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "updatedBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "createdAt": "2025-10-06T14:30:00.000Z", "updatedAt": "2025-10-06T14:30:00.000Z", "lastAttemptAt": "2025-10-07T08:55:03.000Z" } ], "pageNumber": 1, "pageSize": 50, "totalCount": 1 } } } } } }, "400": { "$ref": "#/components/responses/WebhookBadRequest" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/webhooks/subscriptions/{subscriptionId}": { "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "get": { "operationId": "getWebhookSubscription", "summary": "Get a Webhook Subscription", "description": "Read one of your organization's subscriptions.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "The subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" }, "examples": { "enabled": { "value": { "id": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "name": "Checklist job completions", "organizationId": "8d2c4e6a-1f3b-4c5d-9e7f-0a2b4c6d8e1f", "projectIds": [], "excludedProjectIds": [], "url": "https://hooks.example.com/xcures", "eventTypes": [ "checklist.evaluation_job.completed" ], "enabled": true, "createdBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "updatedBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "createdAt": "2025-10-06T14:30:00.000Z", "updatedAt": "2025-10-06T14:30:00.000Z", "lastAttemptAt": "2025-10-07T08:55:03.000Z" } } } } } }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] }, "patch": { "operationId": "updateWebhookSubscription", "summary": "Update a Webhook Subscription", "description": "Change a subscription's name, endpoint, event types or projects. A changed endpoint is held to the rules creating one is. Disable and enable a subscription with their own operations.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdate" }, "examples": { "rename": { "value": { "name": "Job completions, production" } } } } } }, "responses": { "200": { "description": "The subscription, changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" }, "examples": { "renamed": { "value": { "id": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "name": "Job completions, production", "organizationId": "8d2c4e6a-1f3b-4c5d-9e7f-0a2b4c6d8e1f", "projectIds": [], "excludedProjectIds": [], "url": "https://hooks.example.com/xcures", "eventTypes": [ "checklist.evaluation_job.completed" ], "enabled": true, "createdBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "updatedBy": { "clientId": "2a7c9e1b-4d6f-4a8c-b0e2-7f9d1b3c5e68", "clientType": "user" }, "createdAt": "2025-10-06T14:30:00.000Z", "updatedAt": "2025-10-07T09:12:44.000Z", "lastAttemptAt": "2025-10-07T08:55:03.000Z" } } } } } }, "400": { "$ref": "#/components/responses/WebhookBadRequest" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] }, "delete": { "operationId": "deleteWebhookSubscription", "summary": "Delete a Webhook Subscription", "description": "Delete a subscription; nothing is delivered to it from then on.", "tags": [ "Webhooks" ], "responses": { "204": { "description": "The subscription is gone." }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/webhooks/subscriptions/{subscriptionId}/disable": { "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "post": { "operationId": "disableWebhookSubscription", "summary": "Disable a Webhook Subscription", "description": "Stop deliveries to a subscription without deleting it.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "The subscription, disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" }, "examples": { "disabled": { "value": { "id": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "name": "Checklist job completions", "organizationId": "8d2c4e6a-1f3b-4c5d-9e7f-0a2b4c6d8e1f", "projectIds": [], "excludedProjectIds": [], "url": "https://hooks.example.com/xcures", "eventTypes": [ "checklist.evaluation_job.completed" ], "enabled": false, "createdBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "updatedBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "createdAt": "2025-10-06T14:30:00.000Z", "updatedAt": "2025-10-07T09:12:44.000Z", "lastAttemptAt": "2025-10-07T08:55:03.000Z" } } } } } }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/webhooks/subscriptions/{subscriptionId}/enable": { "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "post": { "operationId": "enableWebhookSubscription", "summary": "Enable a Webhook Subscription", "description": "Resume deliveries to a subscription, whether you disabled it or delivery did after its endpoint stopped accepting them.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "The subscription, enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" }, "examples": { "enabled": { "value": { "id": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "name": "Checklist job completions", "organizationId": "8d2c4e6a-1f3b-4c5d-9e7f-0a2b4c6d8e1f", "projectIds": [], "excludedProjectIds": [], "url": "https://hooks.example.com/xcures", "eventTypes": [ "checklist.evaluation_job.completed" ], "enabled": true, "createdBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "updatedBy": { "clientId": "5f1e9d3c-7b2a-4c8e-9f0d-2e4a6c8b0d13", "clientType": "api-key" }, "createdAt": "2025-10-06T14:30:00.000Z", "updatedAt": "2025-10-07T09:12:44.000Z", "lastAttemptAt": "2025-10-07T08:55:03.000Z" } } } } } }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/webhooks/signing-keys": { "post": { "operationId": "createWebhookSigningKey", "summary": "Create the Webhook Signing Key", "description": "Create your organization's signing key before its first subscription, so you can set up verification first. When your organization already has a key, it is answered unchanged and nothing is created.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Your organization already had a key; its public keys, unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningKeys" }, "examples": { "existing": { "value": { "keys": [ { "keyId": "1b9f3d5e-7a2c-4e6f-8d0b-3c5e7a9f1b24", "publicKey": "whpk_huLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3/IA=", "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "huLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3_IA" }, "pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAhuLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3/IA=\n-----END PUBLIC KEY-----\n", "createdAt": "2025-10-06T14:30:00.000Z" } ] } } } } } }, "201": { "description": "Your organization's key, created; its public keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningKeys" }, "examples": { "created": { "value": { "keys": [ { "keyId": "1b9f3d5e-7a2c-4e6f-8d0b-3c5e7a9f1b24", "publicKey": "whpk_huLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3/IA=", "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "huLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3_IA" }, "pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAhuLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3/IA=\n-----END PUBLIC KEY-----\n", "createdAt": "2025-10-06T14:30:00.000Z" } ] } } } } } }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] }, "get": { "operationId": "listWebhookSigningKeys", "summary": "List the Webhook Signing Keys", "description": "Read the public keys your organization's webhook deliveries are signed with: one, or two while a rotation runs, each in the Standard Webhooks `whpk_` form, as a JWK and as PEM. An organization with no key yet has none.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Your organization's public keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningKeys" }, "examples": { "none": { "summary": "An organization with no key yet", "value": { "keys": [] } }, "one": { "value": { "keys": [ { "keyId": "1b9f3d5e-7a2c-4e6f-8d0b-3c5e7a9f1b24", "publicKey": "whpk_huLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3/IA=", "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "huLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3_IA" }, "pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAhuLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3/IA=\n-----END PUBLIC KEY-----\n", "createdAt": "2025-10-06T14:30:00.000Z" } ] } } } } } }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/webhooks/subscriptions/{subscriptionId}/deliveries": { "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "get": { "operationId": "listWebhookDeliveries", "summary": "List a Subscription's Deliveries", "description": "Read a subscription's delivery log, newest entry first, a page at a time: every attempt, with whose side a failure was, the status your endpoint answered and the start of its response body, or which failure occurred when it answered none; a delivery's end; and a disablement, with its reason. Entries are kept for ninety days, and stay readable for that long after the subscription is deleted. A page past the last answers no results.", "tags": [ "Webhooks" ], "parameters": [ { "name": "pageNumber", "in": "query", "required": false, "description": "The page to answer, counting from 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "The most entries to answer on a page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "One page of the subscription's delivery log, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryLogPage" }, "examples": { "retried": { "value": { "results": [ { "kind": "attempt", "deliveryId": "msg_2f6c0e1a9b3d4c5e8f7a6b5c4d3e2f1a", "eventType": "checklist.evaluation_job.completed", "subscriptionId": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "endpoint": { "scheme": "https", "host": "hooks.example.com", "path": "/xcures" }, "at": "2025-10-06T14:41:43.000Z", "status": 200 }, { "kind": "attempt", "deliveryId": "msg_2f6c0e1a9b3d4c5e8f7a6b5c4d3e2f1a", "eventType": "checklist.evaluation_job.completed", "subscriptionId": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "endpoint": { "scheme": "https", "host": "hooks.example.com", "path": "/xcures" }, "at": "2025-10-06T14:41:38.000Z", "side": "endpoint", "status": 503, "responseBody": "Service Unavailable" } ], "pageNumber": 1, "pageSize": 50, "totalCount": 2 } }, "ended": { "value": { "results": [ { "kind": "disabled", "subscriptionId": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "at": "2025-10-13T14:41:38.000Z", "reason": "sustained-failure" }, { "kind": "attempt", "deliveryId": "msg_7a1e3c5b9d2f4a6c8e0b2d4f6a8c0e1b", "eventType": "checklist.evaluation_job.completed", "subscriptionId": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "endpoint": { "scheme": "https", "host": "hooks.example.com", "path": "/xcures" }, "at": "2025-10-13T14:41:38.000Z", "side": "endpoint", "failure": "connection-refused" }, { "kind": "end", "deliveryId": "msg_2f6c0e1a9b3d4c5e8f7a6b5c4d3e2f1a", "eventType": "checklist.evaluation_job.completed", "subscriptionId": "3c8e1f2a-6b4d-4e9a-8c7f-1a2b3c4d5e6f", "at": "2025-10-07T14:41:38.000Z", "outcome": "failed", "side": "endpoint" } ], "pageNumber": 1, "pageSize": 50, "totalCount": 3 } } } } } }, "400": { "$ref": "#/components/responses/WebhookBadRequest" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/webhooks/egress-addresses": { "get": { "operationId": "getWebhookEgressAddresses", "summary": "Get the Webhook Egress Addresses", "description": "Read the addresses webhook deliveries in this environment leave from, to allow them at your firewall. Every workload of the platform's network in this environment shares them, so an address on this list is not proof that a request came from webhook delivery; verify each delivery's signature. The list can change; read it again before you rely on it.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "The addresses deliveries leave from.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEgressAddresses" }, "examples": { "two": { "value": { "addresses": [ "203.0.113.10", "203.0.113.24" ] } } } } } }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/webhooks/signing-keys/rotate": { "post": { "operationId": "rotateWebhookSigningKey", "summary": "Rotate the Webhook Signing Key", "description": "Create a new signing key for your organization. It is published at once, beside the key it replaces, and for the next twenty-four hours every delivery carries a signature under each; then the old key is withdrawn. Read the keys, start verifying with the new one, and keep the old until it is withdrawn. A rotation while one is running, or before your organization has a key, is refused.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Your organization's public keys, the new one first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningKeys" }, "examples": { "rotated": { "value": { "keys": [ { "keyId": "6d2a8c4e-1f3b-4a5d-9e7f-0b2c4d6e8f13", "publicKey": "whpk_WBq7Omn71IvzQ/z/h6t4oeiKbzBtAYOk/oYV7AkhB9I=", "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "WBq7Omn71IvzQ_z_h6t4oeiKbzBtAYOk_oYV7AkhB9I" }, "pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAWBq7Omn71IvzQ/z/h6t4oeiKbzBtAYOk/oYV7AkhB9I=\n-----END PUBLIC KEY-----\n", "createdAt": "2025-10-09T09:00:00.000Z" }, { "keyId": "1b9f3d5e-7a2c-4e6f-8d0b-3c5e7a9f1b24", "publicKey": "whpk_huLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3/IA=", "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "huLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3_IA" }, "pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAhuLyIKTlHeDTmdAPCvgJJKHIco7lWVSk9uf7RuW3/IA=\n-----END PUBLIC KEY-----\n", "createdAt": "2025-10-06T14:30:00.000Z", "retiresAt": "2025-10-10T09:00:00.000Z" } ] } } } } } }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "409": { "description": "A rotation is already running, or your organization has no key to rotate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [ "Subject_Read" ] } ] } }, "/whoami": { "get": { "operationId": "whoAmI", "summary": "Who am I?", "description": "Read the identity the API resolved for your credential.", "tags": [ "Identity" ], "responses": { "200": { "description": "The identity the API resolved for the credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" }, "examples": { "user": { "value": { "clientId": "user-2f1c", "clientType": "user", "organizationId": "org-7a4e", "projectIds": [ "project-a", "project-b" ], "permissions": [ "Document_Read" ], "audience": "patient-registry-public-api", "requestedProjectId": null, "diagnostics": { "traceContextReceived": true, "forwardedHeaderNames": [] } } } } } } }, "429": { "$ref": "#/components/responses/QuotaSpent" } }, "security": [ { "bearer": [] } ] } } }, "webhooks": { "checklist.evaluation_job.completed": { "post": { "summary": "Checklist Evaluation Job Completed", "description": "Sent when a checklist evaluation job ends, whatever the outcome: its `status` says whether it completed, partially completed, failed or was cancelled. Read the job and its results through the API with its `jobId`.", "tags": [ "Checklists" ], "responses": { "2XX": { "description": "Any 2xx status acknowledges the delivery." } }, "requestBody": { "description": "The job that finished.", "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The body of every delivered webhook.", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "type": "string", "const": "checklist.evaluation_job.completed", "description": "The event type." }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event happened." }, "data": { "$ref": "#/components/schemas/ChecklistEvaluationJobCompleted" } } }, "examples": { "completed": { "summary": "A job that evaluated every patient", "value": { "type": "checklist.evaluation_job.completed", "timestamp": "2025-10-06T14:41:37.000Z", "data": { "jobId": "4b8f2d61-3a9c-4e57-b1d8-6c0e9f2a7d45", "checklistId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "projectId": "2f1d6b8e-9c47-4a35-8e0b-5d7a3c9f1e62", "status": "completed", "patientCount": 3, "succeededCount": 3, "failedCount": 0, "resultsExpiresAt": "2025-10-13T14:41:37.000Z" } } } } } } }, "security": [] } } }, "components": { "schemas": { "ChecklistEvaluationJobCompleted": { "type": "object", "description": "A checklist evaluation job that reached a terminal status.", "required": [ "jobId", "checklistId", "projectId", "status", "patientCount", "succeededCount", "failedCount", "resultsExpiresAt" ], "properties": { "jobId": { "type": "string", "format": "uuid", "description": "The job's id." }, "checklistId": { "type": "string", "format": "uuid", "description": "The checklist the job evaluated." }, "projectId": { "type": "string", "format": "uuid", "description": "The project the job ran in." }, "status": { "type": "string", "description": "How the job ended: `completed` when every patient's evaluation succeeded, `partially_completed` when some did, `failed` when none did, and `cancelled` when the job was cancelled.", "enum": [ "completed", "partially_completed", "failed", "cancelled" ] }, "patientCount": { "type": "integer", "description": "The number of patients the job evaluated." }, "succeededCount": { "type": "integer", "description": "The number of patients whose evaluation succeeded." }, "failedCount": { "type": "integer", "description": "The number of patients whose evaluation failed." }, "resultsExpiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the job's results will no longer be available; null when the job produced no results." } } }, "Identity": { "type": "object", "description": "The identity the API resolved for a credential, as every backend receives it.", "required": [ "clientId", "clientType", "organizationId", "projectIds", "permissions", "audience", "requestedProjectId", "diagnostics" ], "properties": { "clientId": { "type": "string", "description": "The credential's subject; a person's user id or an API key's id." }, "clientType": { "type": "string", "description": "The class of credential, `user` for a signed-in person or `api-key` for an exchanged key.", "enum": [ "user", "api-key" ] }, "organizationId": { "type": "string", "description": "The one organization the credential acts for." }, "projectIds": { "type": "array", "description": "The projects the credential spans.", "items": { "type": "string" } }, "permissions": { "type": "array", "description": "The permissions the credential's issuer granted, relayed as the token carried them; empty when it carried none.", "items": { "type": "string" } }, "audience": { "type": "string", "description": "The audience the credential was accepted for; the permissions are that audience's grants." }, "requestedProjectId": { "type": [ "string", "null" ], "description": "The project this request named with the `ProjectId` header; null when it named none." }, "diagnostics": { "type": "object", "description": "What the backend that answered observed of the request, for confirming the API's plumbing.", "required": [ "traceContextReceived", "forwardedHeaderNames" ], "properties": { "traceContextReceived": { "type": "boolean", "description": "Whether the request's trace context reached the backend." }, "forwardedHeaderNames": { "type": "array", "description": "The names of the request headers that reached the backend; identity headers are never among them.", "items": { "type": "string" } } } } } }, "WebhookEgressAddresses": { "type": "object", "description": "The addresses webhook deliveries in this environment leave from.", "required": [ "addresses" ], "additionalProperties": false, "properties": { "addresses": { "type": "array", "description": "Public IPv4 addresses.", "items": { "type": "string", "format": "ipv4" } } } }, "WebhookDeliveryLogPage": { "type": "object", "description": "One page of a subscription's delivery log, newest entry first.", "required": [ "results", "pageNumber", "pageSize", "totalCount" ], "additionalProperties": false, "properties": { "results": { "type": "array", "description": "The entries on this page.", "items": { "$ref": "#/components/schemas/WebhookDeliveryLogEntry" } }, "pageNumber": { "type": "integer", "description": "The page answered, counting from 1." }, "pageSize": { "type": "integer", "description": "The most entries a page answers." }, "totalCount": { "type": "integer", "description": "How many entries every page together answers." } } }, "WebhookDeliveryLogEntry": { "type": "object", "description": "One entry of a subscription's delivery log: an attempt, a delivery's end, or a disablement. An attempt names the endpoint's scheme, host and path, never its query string, and carries no delivery body. `responseBody` is the start of what your endpoint answered, as text, with control and bidirectional-formatting characters removed; it is your endpoint's own content, so treat it as untrusted.", "required": [ "kind", "at" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "description": "`attempt`, `end` (a delivery that will not be attempted again) or `disabled`.", "enum": [ "attempt", "end", "disabled" ] }, "deliveryId": { "type": "string", "description": "The delivery's `webhook-id`." }, "eventType": { "type": "string", "description": "The delivery's event type." }, "subscriptionId": { "type": "string", "format": "uuid", "description": "The subscription." }, "endpoint": { "type": "object", "description": "The endpoint attempted, without its query string.", "required": [ "scheme", "host", "path" ], "additionalProperties": false, "properties": { "scheme": { "type": "string", "description": "The URL's scheme." }, "host": { "type": "string", "description": "The URL's host." }, "path": { "type": "string", "description": "The URL's path." } } }, "at": { "type": "string", "format": "date-time", "description": "When the attempt was made, the delivery ended or the subscription was disabled." }, "side": { "type": "string", "description": "Whose side a failure is attributed to: `endpoint`, your endpoint's, or `platform`, ours, which carries no further detail.", "enum": [ "endpoint", "platform" ] }, "status": { "type": "integer", "description": "The status your endpoint answered." }, "responseBody": { "type": "string", "description": "At most the first 256 bytes of a response body other than a 2xx's, as text." }, "failure": { "type": "string", "description": "When your endpoint answered no status, which failure occurred.", "enum": [ "malformed-response", "timeout", "connection-refused", "connection-reset", "connection-failed", "unresolvable", "tls", "refused-address" ] }, "outcome": { "type": "string", "description": "`failed` on a delivery's end; `unknown` on an attempt we began and could not finish.", "enum": [ "failed", "unknown" ] }, "reason": { "type": "string", "description": "Why the subscription was disabled: `endpoint-gone`, an answer of 410, or `sustained-failure`, every attempt failing at your endpoint for seven days.", "enum": [ "endpoint-gone", "sustained-failure" ] } } }, "WebhookSigningKeys": { "type": "object", "description": "An organization's public signing keys.", "required": [ "keys" ], "properties": { "keys": { "type": "array", "description": "One key, two while a rotation runs, or none before the organization has one.", "items": { "$ref": "#/components/schemas/WebhookSigningKey" } } } }, "WebhookSigningKey": { "type": "object", "description": "A public key webhook deliveries are signed with, in three forms that are the same Ed25519 key: the Standard Webhooks `whpk_` form, a JWK and PEM.", "required": [ "keyId", "publicKey", "jwk", "pem", "createdAt" ], "properties": { "keyId": { "type": "string", "format": "uuid", "description": "The key's id." }, "publicKey": { "type": "string", "description": "The key in the Standard Webhooks form, `whpk_` then the raw 32-byte key in base64." }, "jwk": { "type": "object", "description": "The key as a JSON Web Key.", "required": [ "kty", "crv", "x" ], "properties": { "kty": { "type": "string", "description": "The key type, always `OKP`.", "enum": [ "OKP" ] }, "crv": { "type": "string", "description": "The curve, always `Ed25519`.", "enum": [ "Ed25519" ] }, "x": { "type": "string", "description": "The raw 32-byte key, base64url-encoded." } } }, "pem": { "type": "string", "description": "The key as a PEM-encoded SubjectPublicKeyInfo." }, "createdAt": { "type": "string", "format": "date-time", "description": "When it was created." }, "retiresAt": { "type": "string", "format": "date-time", "description": "When the key stops verifying deliveries and is withdrawn. Present only on the key a rotation is retiring, while the rotation's overlap runs." } } }, "WebhookSubscriptionUpdate": { "type": "object", "description": "The fields of a subscription to change; every other field is left as it is.", "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A new name." }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "A new endpoint, held to the rules a created one is." }, "eventTypes": { "type": "array", "description": "The event types to receive instead.", "uniqueItems": true, "minItems": 1, "items": { "type": "string" } }, "projectIds": { "type": "array", "description": "The projects whose events to receive instead, replacing the list; empty for the events of every project it does not exclude.", "uniqueItems": true, "maxItems": 100, "items": { "type": "string", "format": "uuid" } }, "excludedProjectIds": { "type": "array", "description": "The projects whose events never to receive instead, even a project `projectIds` names, replacing the list; empty to exclude none. An event that carries no project is not affected.", "uniqueItems": true, "maxItems": 100, "items": { "type": "string", "format": "uuid" } } } }, "WebhookSubscriptionPage": { "type": "object", "description": "One page of an organization's subscriptions.", "required": [ "results", "pageNumber", "pageSize", "totalCount" ], "properties": { "results": { "type": "array", "description": "The subscriptions on this page.", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "pageNumber": { "type": "integer", "description": "The page answered, counting from 1." }, "pageSize": { "type": "integer", "description": "The most subscriptions a page answers." }, "totalCount": { "type": "integer", "description": "How many subscriptions every page together answers." } } }, "WebhookSubscription": { "type": "object", "description": "A standing request to deliver events of chosen types to an HTTPS endpoint.", "required": [ "id", "name", "organizationId", "projectIds", "excludedProjectIds", "url", "eventTypes", "enabled", "createdBy", "updatedBy", "createdAt", "updatedAt", "lastAttemptAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The subscription's id." }, "name": { "type": "string", "description": "The name you gave it." }, "organizationId": { "type": "string", "format": "uuid", "description": "The organization it belongs to, the one whose credential created it." }, "projectIds": { "type": "array", "description": "The projects whose events it receives; empty for the events of every project of the organization it does not exclude.", "uniqueItems": true, "maxItems": 100, "items": { "type": "string", "format": "uuid" } }, "excludedProjectIds": { "type": "array", "description": "The projects whose events it never receives, even a project `projectIds` names; empty for none. An event that carries no project is not affected.", "uniqueItems": true, "maxItems": 100, "items": { "type": "string", "format": "uuid" } }, "url": { "type": "string", "description": "The endpoint deliveries are sent to, as you wrote it." }, "eventTypes": { "type": "array", "description": "The event types it receives.", "uniqueItems": true, "minItems": 1, "items": { "type": "string" } }, "enabled": { "type": "boolean", "description": "Whether deliveries are made to it; false once you or delivery disabled it." }, "createdBy": { "$ref": "#/components/schemas/WebhookClient" }, "updatedBy": { "$ref": "#/components/schemas/WebhookClient" }, "createdAt": { "type": "string", "format": "date-time", "description": "When it was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When a client last changed it." }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When delivery last attempted to send to its endpoint, whatever the outcome; null before the first attempt." } } }, "WebhookClient": { "type": "object", "description": "A client of the API, as its credential names it.", "required": [ "clientId", "clientType" ], "properties": { "clientId": { "type": "string", "description": "The client's id, a user's or an API key's." }, "clientType": { "type": "string", "description": "Whether the client is a person signed in or an API key.", "enum": [ "user", "api-key" ] } } }, "WebhookSubscriptionCreate": { "type": "object", "description": "A subscription to create.", "required": [ "name", "url", "eventTypes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A name for it." }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "The HTTPS endpoint to deliver to, on port 443, with no user name or password. Its host is a host name; an IP address or localhost is refused." }, "eventTypes": { "type": "array", "description": "The event types to receive, each one the API publishes.", "uniqueItems": true, "minItems": 1, "items": { "type": "string" } }, "projectIds": { "type": "array", "description": "The projects whose events to receive; omit or leave empty for the events of every project you do not exclude.", "uniqueItems": true, "maxItems": 100, "items": { "type": "string", "format": "uuid" } }, "excludedProjectIds": { "type": "array", "description": "The projects whose events never to receive, even a project `projectIds` names; omit or leave empty to exclude none. An event that carries no project is not affected.", "uniqueItems": true, "maxItems": 100, "items": { "type": "string", "format": "uuid" } } } }, "Query": { "type": "object", "description": "A query across the health information networks xCures belongs to for one patient's records. It runs asynchronously; read it again to see how far the retrieval of the patient's clinical documents has reached.", "required": [ "id", "patientId", "createdAt", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The query's id." }, "patientId": { "type": "string", "format": "uuid", "description": "The patient the query retrieves records for." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the query was created." }, "status": { "type": "string", "description": "How far the retrieval of the patient's clinical documents has reached. `completed`, `exhausted` and `error` are terminal; the others mean the query is still running or waiting to run.", "enum": [ "delayed", "initiated", "pending", "inProgress", "completed", "exhausted", "error" ] } } }, "PatientCreate": { "type": "object", "description": "A patient to create. You choose the patient's id; creating the same id again, or the same person under another id, answers 409. Creating a patient starts no records query.", "required": [ "id", "firstName", "lastName" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The id to create the patient under, which you choose." }, "firstName": { "type": "string", "description": "The patient's first name." }, "middleName": { "type": "string", "description": "The patient's middle name or initial." }, "lastName": { "type": "string", "description": "The patient's last name." }, "additionalNames": { "type": "array", "description": "Other names the patient is known by.", "items": { "$ref": "#/components/schemas/PatientNameInput" } }, "birthDate": { "type": "string", "format": "date", "description": "The patient's date of birth, as `yyyy-mm-dd`." }, "deathDate": { "type": "string", "format": "date", "description": "The patient's date of death, as `yyyy-mm-dd`." }, "sexAtBirth": { "type": "string", "description": "The patient's sex at birth, as patient-registry holds it." }, "email": { "type": "string", "description": "The patient's email address." }, "phoneNumber": { "type": "string", "description": "The patient's phone number." }, "address": { "$ref": "#/components/schemas/PatientAddressInput" }, "additionalAddresses": { "type": "array", "description": "Other addresses for the patient.", "items": { "$ref": "#/components/schemas/PatientAddressInput" } }, "externalIdentifiers": { "type": "array", "description": "The identifiers other systems hold for the patient.", "items": { "$ref": "#/components/schemas/PatientExternalIdentifier" } }, "labels": { "type": "array", "description": "Free-text tags to put on the patient.", "items": { "type": "string" } } } }, "PatientExternalIdentifier": { "type": "object", "description": "An identifier another system holds for a patient.", "required": [ "value", "system" ], "properties": { "value": { "type": "string", "description": "The identifier, as that system holds it." }, "system": { "type": "string", "description": "The name of the system that holds the identifier." } } }, "PatientAddressInput": { "type": "object", "description": "A postal address for a patient.", "properties": { "line1": { "type": "string", "description": "The first line of the street address." }, "line2": { "type": "string", "description": "The second line of the street address." }, "city": { "type": "string", "description": "The city." }, "state": { "type": "string", "description": "The state's two-letter code." }, "postalCode": { "type": "string", "description": "The postal code." } } }, "PatientNameInput": { "type": "object", "description": "One other name a patient is known by.", "properties": { "firstName": { "type": "string", "description": "The first name." }, "middleName": { "type": "string", "description": "The middle name or initial." }, "lastName": { "type": "string", "description": "The last name." } } }, "Patient": { "type": "object", "description": "A patient in the project, as patient-registry holds them.", "required": [ "id", "identifier", "firstName", "lastName", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The patient's id, which every other operation about the patient takes." }, "identifier": { "type": "string", "description": "patient-registry's six-character code for the patient." }, "firstName": { "type": "string", "description": "The patient's first name." }, "middleName": { "type": [ "string", "null" ], "description": "The patient's middle name or initial; null when none was recorded." }, "lastName": { "type": "string", "description": "The patient's last name." }, "additionalNames": { "type": [ "array", "null" ], "description": "Other names the patient is known by; null when none was recorded.", "items": { "$ref": "#/components/schemas/PatientName" } }, "birthDate": { "type": [ "string", "null" ], "format": "date", "description": "The patient's date of birth, as `yyyy-mm-dd`; null when none was recorded." }, "deathDate": { "type": [ "string", "null" ], "format": "date", "description": "The patient's date of death, as `yyyy-mm-dd`; null when none was recorded." }, "sexAtBirth": { "type": [ "string", "null" ], "description": "The patient's sex at birth, as patient-registry holds it; null when none was recorded." }, "email": { "type": [ "string", "null" ], "description": "The patient's email address; null when none was recorded." }, "phoneNumber": { "type": [ "string", "null" ], "description": "The patient's phone number; null when none was recorded." }, "address": { "$ref": "#/components/schemas/PatientAddress" }, "additionalAddresses": { "type": "array", "description": "Other addresses recorded for the patient.", "items": { "$ref": "#/components/schemas/PatientAddress" } }, "externalIdentifiers": { "type": "array", "description": "The identifiers other systems hold for the patient, such as a medical record number.", "items": { "$ref": "#/components/schemas/PatientExternalIdentifier" } }, "labels": { "type": "array", "description": "The free-text tags the project's users put on the patient.", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the patient's record was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the patient's record was last updated." } } }, "PatientAddress": { "type": "object", "description": "A postal address recorded for a patient.", "properties": { "line1": { "type": [ "string", "null" ], "description": "The first line of the street address; null when none was recorded." }, "line2": { "type": [ "string", "null" ], "description": "The second line of the street address; null when none was recorded." }, "city": { "type": [ "string", "null" ], "description": "The city; null when none was recorded." }, "state": { "type": [ "string", "null" ], "description": "The state's two-letter code; null when none was recorded." }, "postalCode": { "type": [ "string", "null" ], "description": "The postal code; null when none was recorded." } } }, "PatientName": { "type": "object", "description": "One other name a patient is known by.", "properties": { "firstName": { "type": [ "string", "null" ], "description": "The first name; null when none was recorded." }, "middleName": { "type": [ "string", "null" ], "description": "The middle name or initial; null when none was recorded." }, "lastName": { "type": [ "string", "null" ], "description": "The last name; null when none was recorded." } } }, "PatientPage": { "type": "object", "description": "One page of the patients a search matched, ordered by last name, then first name, then id.", "required": [ "results", "pageNumber", "pageSize", "totalCount" ], "properties": { "results": { "type": "array", "description": "The patients on this page.", "items": { "$ref": "#/components/schemas/PatientSummary" } }, "pageNumber": { "type": "integer", "description": "The page this is, counting from 1." }, "pageSize": { "type": "integer", "description": "The most patients a page holds." }, "totalCount": { "type": "integer", "description": "How many patients the search matched across every page." } } }, "PatientSummary": { "type": "object", "description": "A patient, as a search answers them.", "required": [ "id", "identifier", "firstName", "lastName" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The patient's id, which every other operation about the patient takes." }, "identifier": { "type": "string", "description": "patient-registry's six-character code for the patient." }, "firstName": { "type": "string", "description": "The patient's first name." }, "middleName": { "type": [ "string", "null" ], "description": "The patient's middle name or initial; null when none was recorded." }, "lastName": { "type": "string", "description": "The patient's last name." }, "birthDate": { "type": [ "string", "null" ], "format": "date", "description": "The patient's date of birth, as `yyyy-mm-dd`; null when none was recorded." }, "sexAtBirth": { "type": [ "string", "null" ], "description": "The patient's sex at birth, as patient-registry holds it; null when none was recorded." }, "externalIdentifiers": { "type": "array", "description": "The identifiers other systems hold for the patient.", "items": { "$ref": "#/components/schemas/PatientExternalIdentifier" } } } }, "PatientSearch": { "type": "object", "description": "What to search the project's patients by. Every criterion is optional, and a search naming none answers every patient your credential may see. How each criterion matches is patient-registry's.", "properties": { "firstName": { "type": "string", "description": "The patient's first name." }, "lastName": { "type": "string", "description": "The patient's last name." }, "birthDate": { "type": "string", "format": "date", "description": "The patient's date of birth, as `yyyy-mm-dd`." }, "externalIdentifier": { "$ref": "#/components/schemas/PatientSearchExternalIdentifier" }, "identifier": { "type": "string", "description": "patient-registry's six-character code for the patient." }, "postalCode": { "type": "string", "description": "The postal code of the patient's address." }, "patientIds": { "type": "array", "description": "Patient ids, each matched exactly; at least 1 and at most 100.", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" } } } }, "PatientSearchExternalIdentifier": { "type": "object", "description": "An identifier another system holds for the patient, and optionally that system's name.", "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1, "description": "The identifier." }, "system": { "type": "string", "description": "The name of the system that holds it." } } }, "DocumentSearchPage": { "type": "object", "description": "One page of the documents a search found, in the search service's order.", "required": [ "results", "pageNumber", "pageSize", "totalCount" ], "properties": { "results": { "type": "array", "description": "The documents on this page.", "items": { "$ref": "#/components/schemas/DocumentSearchResult" } }, "pageNumber": { "type": "integer", "description": "The page this is, counting from 1." }, "pageSize": { "type": "integer", "description": "The most documents a page holds." }, "totalCount": { "type": "integer", "description": "How many documents the search counted across every page, as the search service counts them." } } }, "DocumentSearchResult": { "type": "object", "description": "A document a search found, and the section of it that matched when the search reports one.", "required": [ "id", "patientId", "fileName", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The document's id." }, "patientId": { "type": "string", "format": "uuid", "description": "The id of the patient the document is about." }, "name": { "type": [ "string", "null" ], "description": "The document's display name; null when none was recorded." }, "fileName": { "type": "string", "description": "The file's name." }, "contentType": { "type": [ "string", "null" ], "description": "The file's media type; null when none was recorded." }, "source": { "type": [ "string", "null" ], "description": "How the document arrived; null when none was recorded." }, "documentDate": { "type": [ "string", "null" ], "format": "date-time", "description": "The clinical date of the document; null when none was recorded." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the record was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record was last updated." }, "classifications": { "type": "array", "description": "The classifications the search service assigned the document.", "items": { "type": "string" } }, "matchingSection": { "$ref": "#/components/schemas/DocumentMatchingSection" } } }, "DocumentMatchingSection": { "type": "object", "description": "The section of a document the search service reports as matching.", "required": [ "sectionType" ], "properties": { "sectionType": { "type": "string", "description": "The kind of section, as the search service names it." }, "sectionTitle": { "type": [ "string", "null" ], "description": "The section's title; null when it has none." }, "sectionText": { "type": [ "string", "null" ], "description": "The section's text, as the search service indexed it; null when it holds none." } } }, "DocumentSearch": { "type": "object", "description": "What to search one patient's documents for. Every criterion is optional; which documents a criterion matches is the search service's.", "properties": { "text": { "type": "string", "maxLength": 256, "description": "Words to look for in the documents." }, "documentDateFrom": { "type": "string", "format": "date", "description": "The earliest clinical date of a document to answer, as `yyyy-mm-dd`, inclusive." }, "documentDateTo": { "type": "string", "format": "date", "description": "The latest clinical date of a document to answer, as `yyyy-mm-dd`, inclusive." }, "sources": { "type": "array", "maxItems": 5, "description": "How the documents arrived, as the search service names the sources; at most 5.", "items": { "type": "string", "maxLength": 256 } }, "classifications": { "type": "array", "maxItems": 20, "description": "The classifications the search service assigns documents; at most 20.", "items": { "type": "string", "maxLength": 256 } } } }, "DocumentContent": { "type": "object", "description": "Where to download a document's file.", "required": [ "url", "fileName" ], "properties": { "url": { "type": "string", "description": "A presigned download address, valid for fifteen minutes from when it was issued." }, "fileName": { "type": "string", "description": "The file's name." }, "contentType": { "type": [ "string", "null" ], "description": "The file's media type; null when none was recorded." } } }, "Document": { "type": "object", "description": "One document's metadata. Fetch the file itself through `getDocumentContent`.", "required": [ "id", "patientId", "fileName", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The document's id." }, "patientId": { "type": "string", "format": "uuid", "description": "The id of the patient the document is about." }, "name": { "type": [ "string", "null" ], "description": "The document's display name; null when none was recorded." }, "fileName": { "type": "string", "description": "The file's name." }, "contentType": { "type": [ "string", "null" ], "description": "The file's media type; null when none was recorded." }, "source": { "type": [ "string", "null" ], "description": "How the document arrived; today one of `fhir`, `ccda`, `box`, `userUpload` or `patientFhir`, or null when none was recorded." }, "sourceId": { "type": [ "string", "null" ], "description": "The source system's own id for the document; null when the source gave none." }, "documentDate": { "type": [ "string", "null" ], "format": "date-time", "description": "The clinical date of the document; null when none was recorded." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the record was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record was last updated." } } }, "ChecklistEvaluationJobResults": { "type": "object", "description": "One page of a job's results, one per patient.", "required": [ "results" ], "properties": { "results": { "type": "array", "description": "Up to 25 results, each for one patient.", "items": { "$ref": "#/components/schemas/ChecklistEvaluationJobResult" } }, "cursor": { "type": "string", "description": "Present when there is a next page; pass it as the `cursor` query parameter to read it." } } }, "ChecklistEvaluationJobResult": { "type": "object", "description": "One patient's result in a job.", "required": [ "patientId", "status" ], "properties": { "patientId": { "type": "string", "format": "uuid", "description": "The patient." }, "identifier": { "type": "string", "description": "The patient's `identifier`, patient-registry's six-character code for the patient, when the record carries one." }, "status": { "type": "string", "description": "Whether the patient's evaluation succeeded, failed or was cancelled with the job.", "enum": [ "succeeded", "failed", "cancelled" ] }, "failureReason": { "type": "string", "description": "Why the evaluation failed, when it did; `subject-not-found` for a patient not in the project." }, "evaluation": { "$ref": "#/components/schemas/ChecklistEvaluation" } } }, "ChecklistEvaluationJob": { "type": "object", "description": "A checklist evaluation job and its progress.", "required": [ "jobId", "checklistId", "jobName", "status", "patientCount", "succeededCount", "failedCount", "submittedAt" ], "properties": { "jobId": { "type": "string", "format": "uuid", "description": "The job's id; read its status and results with it." }, "checklistId": { "type": "string", "format": "uuid", "description": "The checklist the job evaluates." }, "jobName": { "type": "string", "description": "The job's name." }, "status": { "type": "string", "description": "Where the job is; `completed`, `partially_completed`, `failed` and `cancelled` are terminal.", "enum": [ "queued", "running", "cancelling", "completed", "partially_completed", "failed", "cancelled" ] }, "patientCount": { "type": "integer", "description": "The number of patients the job evaluates." }, "succeededCount": { "type": "integer", "description": "The number of patients whose evaluation succeeded so far." }, "failedCount": { "type": "integer", "description": "The number of patients whose evaluation failed so far." }, "submittedAt": { "type": "string", "format": "date-time", "description": "When the job was started." }, "startedAt": { "type": "string", "format": "date-time", "description": "When evaluation began; absent before it has." }, "completedAt": { "type": "string", "format": "date-time", "description": "When the job reached a terminal status; absent before it has." }, "resultsExpiresAt": { "type": "string", "format": "date-time", "description": "Until when the job's results can be read; absent before the job completes." } } }, "ChecklistEvaluationJobStart": { "type": "object", "description": "The patients to evaluate a checklist for in one job.", "required": [ "patients" ], "properties": { "jobName": { "type": "string", "maxLength": 200, "description": "A name of your choosing for the job; a default naming the checklist and the patient count when absent." }, "patients": { "type": "array", "description": "The patients to evaluate, from 1 to 25,000; a patient not in the project is not evaluated and its result fails with `subject-not-found`.", "minItems": 1, "maxItems": 25000, "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The patient's id." } } } } } }, "ChecklistEvaluation": { "type": "object", "description": "One checklist evaluated for one patient.", "required": [ "patientId", "checklistId", "items", "documentIds" ], "properties": { "patientId": { "type": "string", "format": "uuid", "description": "The patient evaluated." }, "checklistId": { "type": "string", "format": "uuid", "description": "The checklist evaluated." }, "documentIds": { "type": "array", "description": "The documents behind every satisfied item; fetch one through `getDocument` or `getDocumentContent`.", "items": { "type": "string", "format": "uuid" } }, "items": { "type": "array", "description": "The evaluation of each item of the checklist.", "items": { "$ref": "#/components/schemas/ChecklistItemEvaluation" } } } }, "ChecklistItemEvaluation": { "type": "object", "description": "One checklist item evaluated for one patient.", "required": [ "checklistItem", "documentIds", "clinicalConcepts", "documentSections" ], "properties": { "checklistItem": { "$ref": "#/components/schemas/ChecklistItem" }, "checklistItemDefinitionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The item definition the answer was produced from, stable across evaluations of the item; null when none was recorded." }, "checklistItemDefinitionVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The version of the item definition the answer was produced against; answers from different versions are not directly comparable. Null when none was recorded." }, "documentIds": { "type": "array", "description": "The documents that support the answer.", "items": { "type": "string", "format": "uuid" } }, "clinicalConcepts": { "type": "array", "description": "The clinical concepts that support the answer.", "items": { "$ref": "#/components/schemas/ClinicalConcept" } }, "documentSections": { "type": "array", "description": "The sections of documents that support the answer.", "items": { "$ref": "#/components/schemas/DocumentSection" } }, "result": { "description": "The item's answer in the shape the item's definition gives it." } } }, "DocumentSection": { "type": "object", "description": "A section of a document that supports an answer.", "required": [ "documentId", "sectionType", "section", "documentContentType" ], "properties": { "documentId": { "type": "string", "format": "uuid", "description": "The document the section belongs to." }, "sectionType": { "type": "string", "description": "How the section is addressed; `ccda` for a CCDA section code, `page` for a page number." }, "section": { "type": "string", "description": "The section code or page number." }, "sectionTitle": { "type": [ "string", "null" ], "description": "The section's title; absent or null when the section has none." }, "documentName": { "type": [ "string", "null" ], "description": "The document's display name; null when none was recorded." }, "documentLocation": { "type": [ "string", "null" ], "description": "Where the document came from; null when none was recorded." }, "documentContentType": { "type": "string", "description": "The document's media type." }, "documentDate": { "type": [ "string", "null" ], "format": "date-time", "description": "The clinical date of the document; null when none was recorded." }, "documentFileSizeBytes": { "type": [ "integer", "null" ], "description": "The document's size in bytes; null when unknown." } } }, "ClinicalConcept": { "type": "object", "description": "A clinical concept extracted from the patient's records.", "required": [ "clinicalConceptId", "entityType" ], "properties": { "clinicalConceptId": { "type": "string", "description": "The concept's id." }, "entityType": { "type": "string", "description": "The kind of concept, such as a medication, condition or lab result." } } }, "ChecklistItem": { "type": "object", "description": "One item of a checklist.", "required": [ "id", "libraryItemId", "name", "sortOrder" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The item's id." }, "libraryItemId": { "type": "string", "description": "The library item the checklist item is built from." }, "name": { "type": "string", "description": "The item's display name." }, "sortOrder": { "type": "number", "description": "The order in which the item is displayed." } } }, "ChecklistEvaluationRequest": { "type": "object", "description": "The patient to evaluate a checklist for.", "required": [ "patientId" ], "properties": { "patientId": { "type": "string", "format": "uuid", "description": "The patient's id." } } }, "ChecklistList": { "type": "object", "description": "The checklists of the project the request names.", "required": [ "checklists" ], "properties": { "checklists": { "type": "array", "description": "The project's checklists.", "items": { "$ref": "#/components/schemas/Checklist" } } } }, "Checklist": { "type": "object", "description": "A checklist the project can evaluate a patient against.", "required": [ "id", "name", "sortOrder", "items" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The checklist's id." }, "name": { "type": "string", "description": "The checklist's display name." }, "sortOrder": { "type": "number", "description": "The order in which the checklist is displayed." }, "items": { "type": "array", "description": "The checklist's items, each a criterion an evaluation answers.", "items": { "$ref": "#/components/schemas/ChecklistItem" } } } }, "Error": { "title": "The one error format", "description": "The body of every error response the door renders (contract#one-error-shape); a backend never has to.", "type": "object", "additionalProperties": false, "required": [ "status", "statusCode", "errors", "requestId" ], "properties": { "status": { "type": "string", "description": "The HTTP reason phrase for statusCode, as text.", "minLength": 1, "examples": [ "Not Found" ] }, "statusCode": { "type": "integer", "description": "The HTTP status code of the response, repeated in the body.", "minimum": 400, "maximum": 599 }, "errors": { "type": "array", "description": "One entry per fault. A validation failure lists every fault it found up to the ceiling, then one entry saying how many more; every other failure lists one.", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable prose for a developer, naming the rule broken and never the value that broke it (contract#error-names-the-rule-not-the-value).", "minLength": 1, "maxLength": 1024, "pattern": "^[^\\r\\n\\u0000]*$" }, "field": { "type": "string", "maxLength": 256, "pattern": "^(/[^/\\r\\n\\u0000]*)*$", "description": "Where in the request the fault is, as a JSON pointer, when the fault is in the request.", "examples": [ "/body/kind", "/query/limit" ] } } } }, "requestId": { "type": "string", "description": "The request id the door minted for this request, equal to the x-request-id response header (contract#error-carries-request-id).", "minLength": 1 } } } }, "parameters": { "WebhookSubscriptionId": { "name": "subscriptionId", "in": "path", "required": true, "description": "The subscription's id, as creating it answered it.", "schema": { "type": "string", "format": "uuid" } }, "ChecklistEvaluationJobId": { "name": "jobId", "in": "path", "required": true, "description": "The job's id, as starting the job answered it.", "schema": { "type": "string", "format": "uuid" } }, "ChecklistId": { "name": "checklistId", "in": "path", "required": true, "description": "The checklist's id.", "schema": { "type": "string", "format": "uuid" } }, "ChecklistProjectId": { "name": "ProjectId", "in": "header", "required": true, "description": "The project the request acts in; one of the projects your credential spans.", "schema": { "type": "string" } } }, "responses": { "QuotaSpent": { "description": "Your organization has spent its quota for this operation this minute. Every credential and project in the organization shares the quota. Wait the seconds Retry-After gives before retrying, adding a little random delay so parallel workers don't all retry at once.", "headers": { "RateLimit-Limit": { "description": "The number of requests per minute your organization may make to this operation.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "The requests your organization has left for this operation in the current minute: zero on a 429.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "The whole number of seconds until the current minute ends and the count starts again.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "The whole number of seconds to wait before retrying; the same value as RateLimit-Reset.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "WebhookNotFound": { "description": "No subscription with that id belongs to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "WebhookForbidden": { "description": "Your credential lacks the permission this operation requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "WebhookBadRequest": { "description": "The request is not one the operation declares, or names an endpoint or an event type it refuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ChecklistNotFound": { "description": "No such checklist or job in the project the request names, or a job read under a checklist it was not started for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ChecklistForbidden": { "description": "Your credential lacks the permission this operation requires, or the cohort access to a patient it names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A bearer token, obtained either by signing in to xCures or by exchanging an API key for an access token." } } } }