{ "openapi": "3.1.0", "info": { "title": "Everbility Public API", "version": "1.0.0", "description": "Pull reports from Everbility, upload notes and files, poll asynchronous jobs, and generate reports from saved templates. Partner endpoints let approved platforms connect practices with OAuth 2.0, launch report-writing sessions, receive signed lifecycle webhooks, and retrieve completed documents." }, "paths": { "/v1/public/me": { "get": { "tags": [ "external" ], "summary": "Check key identity", "operationId": "get_external_me_v1_external_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalMeResponse" } } } } }, "description": "Verify the API key, confirm whether it is a user or organisation key, and inspect the effective scope.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/clients/search": { "get": { "tags": [ "external" ], "summary": "Search clients", "operationId": "search_clients_v1_external_clients_search_get", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Q" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalClientSearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Search clients that are visible to the current API key scope.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/clients/{client_id}/documents": { "get": { "tags": [ "external" ], "summary": "List client reports", "operationId": "list_client_documents_v1_external_clients__client_id__documents_get", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalDocumentPreview" }, "title": "Response List Client Documents V1 External Clients Client Id Documents Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "List reports for a client that is visible to the current API key scope.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/clients/{client_id}/documents/{document_id}": { "get": { "tags": [ "external" ], "summary": "Get a rendered report", "operationId": "get_client_document_v1_external_clients__client_id__documents__document_id__get", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "markdown", "html" ], "type": "string", "default": "markdown", "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalDocumentDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Fetch a single report and render it as Markdown or HTML on demand.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/clients/{client_id}/notes": { "post": { "tags": [ "external" ], "summary": "Create a Markdown note", "operationId": "create_markdown_note_v1_external_clients__client_id__notes_post", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalMarkdownNoteCreateInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalNoteCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Create a client note from Markdown content and return the created note ID.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/clients/{client_id}/notes/upload": { "post": { "tags": [ "external" ], "summary": "Upload a PDF note", "operationId": "upload_pdf_note_v1_external_clients__client_id__notes_upload_post", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_pdf_note_v1_external_clients__client_id__notes_upload_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalJobQueuedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Upload a PDF for asynchronous processing into a client note. Poll the returned job ID until completion.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/clients/{client_id}/transcriptions/upload-large": { "post": { "tags": [ "external" ], "summary": "Upload large audio for transcription", "operationId": "upload_large_audio_for_transcription_v1_external_clients__client_id__transcriptions_upload_large_post", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_large_audio_for_transcription_v1_external_clients__client_id__transcriptions_upload_large_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalJobQueuedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Upload a large audio file for asynchronous transcription into a client note. Poll the returned job ID until completion.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/jobs/{job_id}": { "get": { "tags": [ "external" ], "summary": "Get async job status", "operationId": "get_job_status_v1_external_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalJobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Check the status of a public async job, including PDF-processing, large-audio transcription, and report-generation jobs.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/templates": { "get": { "tags": [ "external" ], "summary": "List templates", "operationId": "list_templates_v1_external_templates_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ExternalTemplatePreview" }, "type": "array", "title": "Response List Templates V1 External Templates Get" } } } } }, "description": "List report-generation templates visible to the current API key scope.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/templates/{template_id}": { "get": { "tags": [ "external" ], "summary": "Get a template", "operationId": "get_template_v1_external_templates__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalTemplateDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Fetch a single report-generation template that is visible to the current API key scope.", "security": [ { "bearerAuth": [] } ] } }, "/v1/public/clients/{client_id}/reports/generate": { "post": { "tags": [ "public" ], "summary": "Generate Report", "operationId": "generate_report_v1_public_clients__client_id__reports_generate_post", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalGenerateReportInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalJobQueuedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Start backend report creation from a template ID and note IDs. If the template contains prompt nodes, the backend generates those sections from the supplied notes. If the template contains no prompt nodes, the backend saves the template content directly as a report. The response returns a job_id immediately; poll GET /v1/public/jobs/{job_id} until the job completes.", "security": [ { "bearerAuth": [] } ] } }, "/v1/partner/oauth/token": { "post": { "tags": [ "partner" ], "summary": "Exchange Partner Token", "operationId": "exchange_partner_token_v1_partner_oauth_token_post", "description": "Exchange an authorization code (with its PKCE code_verifier) or a refresh token for a new access and refresh token pair. Accepts form-encoded or JSON bodies. Refresh tokens are single use: each refresh returns a new pair and revokes the previous access token. Reusing a consumed refresh token revokes the whole connection and requires re-authorization by a practice admin.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PartnerTokenRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PartnerTokenRequest" } } } }, "responses": { "200": { "description": "New token pair. The access token lasts 1 hour, the refresh token 90 days.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerTokenResponse" } } } }, "400": { "description": "Invalid code, verifier, redirect_uri, or grant_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Invalid authorization code" } } } }, "401": { "description": "Invalid client credentials, or invalid, reused, or expired refresh token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Refresh token reuse detected" } } } } }, "security": [] } }, "/v1/partner/oauth/revoke": { "post": { "tags": [ "partner" ], "summary": "Revoke Partner Connection", "operationId": "revoke_partner_token_v1_partner_oauth_revoke_post", "description": "Revoke an entire partner connection by presenting any of its tokens (access or refresh) with your client credentials. All tokens for the connection are revoked and unfinished launch sessions expire. Always returns revoked: true, including for unknown or already-revoked tokens. Accepts form-encoded or JSON bodies.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PartnerRevokeRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PartnerRevokeRequest" } } } }, "responses": { "200": { "description": "Revocation acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerRevokeResponse" } } } }, "401": { "description": "Invalid client credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Invalid OAuth client" } } } } }, "security": [] } }, "/v1/partner/launch-sessions": { "post": { "tags": [ "partner" ], "summary": "Create Launch Session", "operationId": "create_partner_launch_session_v1_partner_launch_sessions_post", "description": "Create a report-writing launch session for a clinician in the connected practice. Requires an Idempotency-Key header: retrying with the same key and identical body returns the original session; reusing a key with a different body fails with 409. Sessions expire 48 hours after creation if not completed. Open the returned launch_url for the clinician.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "Idempotency-Key" }, "description": "Unique key per logical session (for example a UUID). Enables safe retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerLaunchSessionCreateInput" } } } }, "responses": { "200": { "description": "Session created (or the existing session for a repeated Idempotency-Key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerLaunchSessionCreateResponse" } } } }, "400": { "description": "Missing Idempotency-Key, or clinician_email did not match exactly one verified practice member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "clinician_email_not_resolved" } } } }, "401": { "description": "Invalid or expired access token, or the connection was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Invalid bearer token" } } } }, "403": { "description": "The mapped Everbility client is not accessible to the assigned clinician.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "client_access_denied" } } } }, "409": { "description": "Idempotency-Key was reused with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Idempotency-Key conflict" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "partnerBearer": [] } ] } }, "/v1/partner/launch-sessions/{session_id}": { "get": { "tags": [ "partner" ], "summary": "Get Launch Session Status", "operationId": "get_partner_launch_session_status_v1_partner_launch_sessions__session_id__get", "description": "Poll a launch session. Status moves created -> opened -> completed; sessions that pass their 48-hour expiry become expired. document_url is populated once the session is completed.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Current session status and timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerLaunchSessionStatusResponse" } } } }, "401": { "description": "Invalid or expired access token, or the connection was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Invalid bearer token" } } } }, "404": { "description": "Unknown session_id, or the session belongs to a different connection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Session not found" } } } } }, "security": [ { "partnerBearer": [] } ] } }, "/v1/partner/launch-sessions/{session_id}/document": { "get": { "tags": [ "partner" ], "summary": "Get Completed Session Document", "operationId": "get_partner_launch_session_document_v1_partner_launch_sessions__session_id__document_get", "description": "Retrieve the rendered report attached to a completed launch session, as Markdown (default) or HTML. The document remains available on the completed session after the 48-hour session window.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "markdown", "html" ], "default": "markdown", "title": "Format" } } ], "responses": { "200": { "description": "Rendered document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerDocumentDetail" } } } }, "401": { "description": "Invalid or expired access token, or the connection was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Invalid bearer token" } } } }, "404": { "description": "Unknown session, or the attached document is no longer accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Document not found" } } } }, "409": { "description": "The session has not been completed yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Session not completed" } } } }, "410": { "description": "The session expired before completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerErrorResponse" }, "example": { "detail": "Session expired" } } } } }, "security": [ { "partnerBearer": [] } ] } } }, "webhooks": { "partnerLaunchSessionEvent": { "post": { "tags": [ "partner-webhooks" ], "summary": "Partner launch session event", "description": "Signed notification sent to the HTTPS webhook URL registered during onboarding. Verify the HMAC-SHA256 signature against the exact raw request body using the dedicated webhook secret. Return any 2xx response within 10 seconds after durable acceptance.", "parameters": [ { "name": "Everbility-Webhook-Id", "in": "header", "required": true, "description": "Stable event ID. Use it to deduplicate retries.", "schema": { "type": "string", "example": "pwevt_eYQdV8wYz4cZQ3JQ7r2x8w" } }, { "name": "Everbility-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix timestamp for this delivery attempt.", "schema": { "type": "string", "pattern": "^[0-9]+$", "example": "1784091792" } }, { "name": "Everbility-Webhook-Signature", "in": "header", "required": true, "description": "Versioned HMAC-SHA256 signature: v1=<64-character hexadecimal digest>.", "schema": { "type": "string", "pattern": "^v1=[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWebhookEvent" } } } }, "responses": { "200": { "description": "Event accepted. Any 2xx status is treated as success." }, "default": { "description": "A non-2xx response causes a retry. Redirects are not followed." } } } } }, "components": { "schemas": { "Body_upload_large_audio_for_transcription_v1_external_clients__client_id__transcriptions_upload_large_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_large_audio_for_transcription_v1_external_clients__client_id__transcriptions_upload_large_post" }, "Body_upload_pdf_note_v1_external_clients__client_id__notes_upload_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_pdf_note_v1_external_clients__client_id__notes_upload_post" }, "ExternalClientSearchResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/ExternalClientSearchResult" }, "type": "array", "title": "Results" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" } }, "type": "object", "required": [ "results", "total", "page", "limit" ], "title": "ExternalClientSearchResponse" }, "ExternalClientSearchResult": { "properties": { "id": { "type": "integer", "title": "Id" }, "first_name": { "type": "string", "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "is_org_client": { "type": "boolean", "title": "Is Org Client" } }, "type": "object", "required": [ "id", "first_name", "last_name", "is_org_client" ], "title": "ExternalClientSearchResult" }, "ExternalDocumentDetail": { "properties": { "_id": { "type": "string", "title": " Id" }, "type": { "type": "string", "enum": [ "report" ], "const": "report", "title": "Type", "default": "report" }, "client_id": { "type": "integer", "title": "Client Id" }, "title": { "type": "string", "title": "Title" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "format": { "type": "string", "enum": [ "markdown", "html" ], "title": "Format" }, "content": { "type": "string", "title": "Content" } }, "type": "object", "required": [ "_id", "client_id", "title", "created_at", "updated_at", "format", "content" ], "title": "ExternalDocumentDetail" }, "ExternalDocumentPreview": { "properties": { "_id": { "type": "string", "title": " Id" }, "type": { "type": "string", "enum": [ "report" ], "const": "report", "title": "Type", "default": "report" }, "client_id": { "type": "integer", "title": "Client Id" }, "title": { "type": "string", "title": "Title" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "_id", "client_id", "title", "created_at", "updated_at" ], "title": "ExternalDocumentPreview" }, "ExternalGenerateReportInput": { "properties": { "template_id": { "type": "string", "title": "Template Id" }, "note_ids": { "items": { "type": "string" }, "type": "array", "title": "Note Ids" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "type": "object", "required": [ "template_id", "note_ids" ], "title": "ExternalGenerateReportInput" }, "ExternalJobResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "task_type": { "type": "string", "title": "Task Type" }, "start_timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Timestamp" }, "end_timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Timestamp" }, "status": { "type": "string", "title": "Status" }, "progress": { "anyOf": [ { "type": "integer" }, { "type": "number" } ], "title": "Progress" }, "error": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Error" }, "result": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Result" } }, "type": "object", "required": [ "job_id", "task_type", "status", "progress" ], "title": "ExternalJobResponse" }, "ExternalMarkdownNoteCreateInput": { "properties": { "title": { "type": "string", "title": "Title" }, "markdown": { "type": "string", "title": "Markdown" } }, "type": "object", "required": [ "title", "markdown" ], "title": "ExternalMarkdownNoteCreateInput" }, "ExternalMeResponse": { "properties": { "principal_type": { "type": "string", "enum": [ "user", "organization" ], "title": "Principal Type" }, "created_by_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By User Id" } }, "type": "object", "required": [ "principal_type" ], "title": "ExternalMeResponse" }, "ExternalNoteCreateResponse": { "properties": { "note_id": { "type": "string", "title": "Note Id" } }, "type": "object", "required": [ "note_id" ], "title": "ExternalNoteCreateResponse" }, "ExternalTemplateDetail": { "properties": { "_id": { "type": "string", "title": " Id" }, "title": { "type": "string", "title": "Title" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "is_org_template": { "type": "boolean", "title": "Is Org Template", "default": false }, "content": { "type": "object", "title": "Content" } }, "type": "object", "required": [ "_id", "title", "created_at", "content" ], "title": "ExternalTemplateDetail" }, "ExternalTemplatePreview": { "properties": { "_id": { "type": "string", "title": " Id" }, "title": { "type": "string", "title": "Title" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "is_org_template": { "type": "boolean", "title": "Is Org Template", "default": false } }, "type": "object", "required": [ "_id", "title", "created_at" ], "title": "ExternalTemplatePreview" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ExternalJobQueuedResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id" } }, "type": "object", "required": [ "job_id" ], "title": "ExternalJobQueuedResponse" }, "PartnerErrorResponse": { "type": "object", "title": "PartnerErrorResponse", "properties": { "detail": { "type": "string", "title": "Detail", "description": "Human-readable error code or message." } }, "required": [ "detail" ], "example": { "detail": "Invalid authorization code" } }, "PartnerTokenRequest": { "type": "object", "title": "PartnerTokenRequest", "description": "Token request. Send as application/x-www-form-urlencoded or application/json. Fields beyond grant_type, client_id, and client_secret depend on the grant type.", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ], "title": "Grant Type" }, "client_id": { "type": "string", "title": "Client Id", "description": "Your partner app's OAuth client ID." }, "client_secret": { "type": "string", "title": "Client Secret", "description": "Your partner app's OAuth client secret. Server-side only." }, "code": { "type": "string", "title": "Code", "description": "Authorization code from the consent callback. Required for grant_type=authorization_code. Single use, expires after 5 minutes." }, "redirect_uri": { "type": "string", "title": "Redirect Uri", "description": "Must exactly match the registered redirect URI. Required for grant_type=authorization_code." }, "code_verifier": { "type": "string", "title": "Code Verifier", "pattern": "^[A-Za-z0-9\\-._~]{43,128}$", "description": "PKCE code verifier whose S256 challenge was sent to the consent page. Required for grant_type=authorization_code." }, "refresh_token": { "type": "string", "title": "Refresh Token", "description": "Current refresh token. Required for grant_type=refresh_token. Single use — a new pair is returned." } }, "required": [ "grant_type", "client_id", "client_secret" ] }, "PartnerTokenResponse": { "type": "object", "title": "PartnerTokenResponse", "properties": { "access_token": { "type": "string", "title": "Access Token", "description": "Opaque bearer token for partner endpoints. Valid for 1 hour." }, "refresh_token": { "type": "string", "title": "Refresh Token", "description": "Single-use refresh token. Valid for 90 days." }, "token_type": { "type": "string", "enum": [ "Bearer" ], "title": "Token Type", "default": "Bearer" }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Access token lifetime in seconds (3600)." } }, "required": [ "access_token", "refresh_token", "token_type", "expires_in" ], "example": { "access_token": "pat_Zl9nB1qFhOQe2kQ4rW8xJ3Ty", "refresh_token": "prt_M4kQ9wY2eXvB7cJ1sL6pR8Ud", "token_type": "Bearer", "expires_in": 3600 } }, "PartnerRevokeRequest": { "type": "object", "title": "PartnerRevokeRequest", "properties": { "client_id": { "type": "string", "title": "Client Id" }, "client_secret": { "type": "string", "title": "Client Secret" }, "token": { "type": "string", "title": "Token", "description": "Any access or refresh token from the connection to revoke." } }, "required": [ "client_id", "client_secret", "token" ] }, "PartnerRevokeResponse": { "type": "object", "title": "PartnerRevokeResponse", "properties": { "revoked": { "type": "boolean", "title": "Revoked" } }, "required": [ "revoked" ], "example": { "revoked": true } }, "PartnerLaunchSessionCreateInput": { "type": "object", "title": "PartnerLaunchSessionCreateInput", "properties": { "external_client_id": { "type": "string", "minLength": 1, "maxLength": 255, "title": "External Client Id", "description": "Your platform's ID for the client. Used to remember the client mapping across sessions on this connection." }, "clinician_email": { "type": "string", "minLength": 3, "maxLength": 320, "title": "Clinician Email", "description": "Must match the verified email of exactly one member of the connected practice. Matching is case-insensitive." }, "client_first_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Client First Name", "description": "Shown to the clinician when mapping the client for the first time." }, "client_last_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Client Last Name", "description": "Shown to the clinician when mapping the client for the first time." } }, "required": [ "external_client_id", "clinician_email" ], "example": { "external_client_id": "your-client-42", "clinician_email": "jordan@examplepractice.com", "client_first_name": "Alex", "client_last_name": "Nguyen" } }, "PartnerLaunchSessionCreateResponse": { "type": "object", "title": "PartnerLaunchSessionCreateResponse", "properties": { "session_id": { "type": "string", "title": "Session Id" }, "status": { "type": "string", "enum": [ "created", "opened", "completed", "expired" ], "title": "Status" }, "launch_url": { "type": "string", "title": "Launch Url", "description": "Open this URL for the assigned clinician to write the report in Everbility." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "Sessions expire 48 hours after creation if not completed." } }, "required": [ "session_id", "status", "launch_url", "expires_at" ], "example": { "session_id": "psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty", "status": "created", "launch_url": "https://www.everbility.com/partner-sessions/psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty", "expires_at": "2026-07-08T04:15:00Z" } }, "PartnerLaunchSessionStatusResponse": { "type": "object", "title": "PartnerLaunchSessionStatusResponse", "properties": { "session_id": { "type": "string", "title": "Session Id" }, "status": { "type": "string", "enum": [ "created", "opened", "completed", "expired" ], "title": "Status" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "opened_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Opened At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At" }, "document_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Url", "description": "Populated once the session is completed." } }, "required": [ "session_id", "status", "created_at", "expires_at" ], "example": { "session_id": "psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty", "status": "completed", "created_at": "2026-07-06T04:15:00Z", "opened_at": "2026-07-06T04:22:41Z", "completed_at": "2026-07-06T05:03:12Z", "expires_at": "2026-07-08T04:15:00Z", "document_url": "/v1/partner/launch-sessions/psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty/document" } }, "PartnerWebhookEvent": { "type": "object", "title": "PartnerWebhookEvent", "description": "Signed launch-session lifecycle event. The event ID and serialized payload remain stable across retries; the delivery timestamp and signature change for each attempt.", "properties": { "id": { "type": "string", "title": "Event Id", "description": "Stable event ID used for deduplication." }, "type": { "type": "string", "enum": [ "launch_session.opened", "launch_session.completed", "launch_session.expired" ], "title": "Event Type" }, "created_at": { "type": "string", "format": "date-time", "title": "Event Created At" }, "data": { "type": "object", "title": "Launch Session Event Data", "properties": { "session_id": { "type": "string" }, "status": { "type": "string", "enum": [ "opened", "completed", "expired" ] }, "external_client_id": { "type": "string" }, "clinician_email": { "type": "string", "description": "Assigned clinician's normalized email address." }, "opened_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expires_at": { "type": "string", "format": "date-time" }, "document_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "API-relative document URL, populated only for launch_session.completed." } }, "required": [ "session_id", "status", "external_client_id", "clinician_email", "opened_at", "completed_at", "expires_at", "document_url" ] } }, "required": [ "id", "type", "created_at", "data" ], "example": { "id": "pwevt_eYQdV8wYz4cZQ3JQ7r2x8w", "type": "launch_session.completed", "created_at": "2026-07-15T05:03:12Z", "data": { "session_id": "psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty", "status": "completed", "external_client_id": "your-client-42", "clinician_email": "jordan@examplepractice.com", "opened_at": "2026-07-15T04:22:41Z", "completed_at": "2026-07-15T05:03:12Z", "expires_at": "2026-07-17T04:15:00Z", "document_url": "/v1/partner/launch-sessions/psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty/document" } } }, "PartnerDocumentDetail": { "type": "object", "title": "PartnerDocumentDetail", "properties": { "session_id": { "type": "string", "title": "Session Id" }, "title": { "type": "string", "title": "Title" }, "everbility_client_id": { "type": "integer", "title": "Everbility Client Id" }, "format": { "type": "string", "enum": [ "markdown", "html" ], "title": "Format" }, "content": { "type": "string", "title": "Content", "description": "Rendered report content in the requested format." } }, "required": [ "session_id", "title", "everbility_client_id", "format", "content" ], "example": { "session_id": "psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty", "title": "Functional capacity report", "everbility_client_id": 864, "format": "markdown", "content": "# Functional capacity report\n\n..." } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Use a Clerk-backed Everbility user or organisation API key directly as the bearer token." }, "partnerBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Partner access token", "description": "Opaque partner access token (pat_...) issued by POST /v1/partner/oauth/token. Access tokens last 1 hour; refresh with the 90-day refresh token." } } }, "servers": [ { "url": "https://api.everbility.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ] }