{ "openapi": "3.1.0", "info": { "title": "Clarity Developer API", "version": "2.7.0", "description": "Revenue estimates and deterministic workflow evaluation. No live payer verification. Do not send patient data." }, "servers": [ { "url": "https://clarity-revenue.vercel.app" } ], "paths": { "/api/v1/revenue/estimate": { "post": { "operationId": "estimateRevenue", "summary": "Estimate gross billable revenue opportunity", "description": "Required API key scope: estimates:write", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" } } } }, "responses": { "200": { "description": "Result from supplied assumptions or facts", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workflows/evaluate": { "post": { "operationId": "evaluateWorkflow", "summary": "Evaluate supplied workflow facts", "description": "Required API key scope: workflows:write", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRequest" } } } }, "responses": { "200": { "description": "Result from supplied assumptions or facts", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/usage": { "get": { "operationId": "getUsage", "summary": "Read workspace usage and request metadata", "description": "Required API key scope: usage:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result from supplied assumptions or facts", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "requestId" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Structured error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/ai/analyze": { "post": { "operationId": "analyzeRevenue", "summary": "Generate and save a grounded AI action plan", "description": "Required scope: analysis:write", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIRequest" } } } }, "responses": { "200": { "description": "Structured result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Missing or invalid key" }, "403": { "description": "Wrong scope" }, "422": { "description": "Invalid fields" }, "429": { "description": "Quota reached" }, "503": { "description": "AI unavailable" } } } }, "/api/v1/workflows/batch": { "post": { "operationId": "evaluateWorkflowBatch", "summary": "Prioritize a queue of 1\u201325 encounters", "description": "Required scope: workflows:write", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "200": { "description": "Structured result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Missing or invalid key" }, "403": { "description": "Wrong scope" }, "422": { "description": "Invalid fields" }, "429": { "description": "Quota reached" }, "503": { "description": "AI unavailable" } } } }, "/api/v1/coverage/snapshots": { "post": { "operationId": "saveCoverageSnapshot", "summary": "saveCoverageSnapshot", "description": "Required scope: coverage:write. Synthetic test data only. No live payer verification or transport authorization.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Saved snapshot or workspace feed. All records have payerVerified=false; clinical transport decisions are not assessed." }, "409": { "description": "Revision conflict, stale observation, or changed input under an existing idempotency token." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reference", "status", "planType", "ambulanceBenefit", "networkStatus", "authorizationStatus" ], "properties": { "reference": { "type": "string", "pattern": "^(TEST_|DEMO_)[A-Za-z0-9_-]{1,50}$" }, "status": { "type": "string", "enum": [ "active", "inactive", "unknown" ] }, "planType": { "type": "string", "enum": [ "commercial", "medicare", "medicaid", "other", "unknown" ] }, "ambulanceBenefit": { "type": "string", "enum": [ "reported_covered", "reported_not_covered", "unknown" ] }, "networkStatus": { "type": "string", "enum": [ "in_network", "out_of_network", "unknown" ] }, "authorizationStatus": { "type": "string", "enum": [ "approved", "pending", "denied", "not_required", "unknown" ] }, "expectedRevision": { "type": "integer", "minimum": 0, "description": "0 for a new record; last-read revision for an update. Conflicts return 409." }, "observedAt": { "type": "string", "format": "date-time", "description": "UTC ISO timestamp. Older observations are rejected." }, "serviceDate": { "type": "string", "format": "date" }, "plans": { "type": "array", "maxItems": 10, "description": "Full policy list, including prior plans. Omit to preserve existing policies on legacy summary updates; an explicit empty list removes policies from the current snapshot. Previous values remain in retained history. IDs must be unique.", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "payer", "memberReference", "order", "status", "startsOn", "endsOn", "ambulanceBenefit", "authorizationStatus", "networkStatus" ], "properties": { "id": { "type": "string", "pattern": "^(TEST_|DEMO_)[A-Za-z0-9_-]{1,50}$" }, "payer": { "type": "string", "enum": [ "demo_commercial_a", "demo_commercial_b", "demo_medicare", "demo_medicaid", "demo_other" ] }, "memberReference": { "type": "string", "pattern": "^(TEST_|DEMO_)[A-Za-z0-9_-]{1,50}$" }, "order": { "type": "string", "enum": [ "primary", "secondary", "tertiary", "unknown" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "unknown" ] }, "startsOn": { "type": [ "string", "null" ], "format": "date" }, "endsOn": { "type": [ "string", "null" ], "format": "date" }, "ambulanceBenefit": { "type": "string", "enum": [ "unknown", "reported_covered", "reported_not_covered" ] }, "authorizationStatus": { "type": "string", "enum": [ "unknown", "approved", "pending", "denied", "not_required" ] }, "networkStatus": { "type": "string", "enum": [ "unknown", "in_network", "out_of_network" ] } } } } }, "dependentRequired": { "plans": [ "serviceDate" ] } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable retry token, retained seven days. Changed payload returns 409. Replays consume API allowance.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" } } ] } }, "/api/v1/coverage": { "get": { "operationId": "listCoverage", "summary": "listCoverage", "description": "Required scope: coverage:read. Synthetic test data only. No live payer verification or transport authorization.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Saved snapshot or workspace feed. All records have payerVerified=false; clinical transport decisions are not assessed." } } } }, "/api/v1/coverage/alerts/{id}/acknowledge": { "post": { "operationId": "acknowledgeCoverageAlert", "summary": "acknowledgeCoverageAlert", "description": "Required scope: coverage:write. Synthetic test data only. No live payer verification or transport authorization.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Saved snapshot or workspace feed. All records have payerVerified=false; clinical transport decisions are not assessed." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/coverage/alerts": { "get": { "operationId": "listCoverageAlerts", "summary": "Page through retained coverage alerts", "description": "Requires coverage:read. Stable order by creation time and ID. Each response includes items, hasMore and nextCursor. No live payer data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque nextCursor returned by the previous page.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all", "unread", "reviewed" ], "default": "all" } } ], "responses": { "200": { "description": "Page of retained records" }, "422": { "description": "Invalid limit, filter or cursor" } } } }, "/api/v1/coverage/history": { "get": { "operationId": "listCoverageHistory", "summary": "Page through retained coverage history", "description": "Requires coverage:read. Stable order by creation time and ID. Each response includes items, hasMore and nextCursor. No live payer data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque nextCursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of retained records" }, "422": { "description": "Invalid limit, filter or cursor" } } } }, "/api/v1/intake": { "get": { "summary": "List retained synthetic intake drafts and follow-up tasks", "description": "Required scope: intake:read. Synthetic examples only. No patient processing or live payer submission. AI extraction shares the existing 20/day workspace and 100/month project allowance.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Intake metadata with submissionEnabled/liveSubmission false." }, "422": { "description": "Invalid input, unsupported synthetic data, or review missing." }, "429": { "description": "Rate, queue, or AI allowance reached." }, "503": { "description": "AI unavailable; use manual entry." } } }, "post": { "summary": "Save a human-reviewed synthetic intake draft", "description": "Required scope: intake:write. Synthetic examples only. No patient processing or live payer submission. AI extraction shares the existing 20/day workspace and 100/month project allowance.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Intake metadata with submissionEnabled/liveSubmission false." }, "422": { "description": "Invalid input, unsupported synthetic data, or review missing." }, "429": { "description": "Rate, queue, or AI allowance reached." }, "503": { "description": "AI unavailable; use manual entry." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reference", "fields", "revision", "humanReviewed" ], "properties": { "reference": { "type": "string", "pattern": "^(DEMO|TEST)_[A-Z0-9_]{1,48}$" }, "fields": { "type": "object", "additionalProperties": false, "required": [ "patientAlias", "dob", "serviceDate", "payer", "memberId" ], "properties": { "patientAlias": { "type": [ "string", "null" ], "enum": [ "DEMO_PATIENT_01", "DEMO_PATIENT_02", "DEMO_PATIENT_03", null ] }, "dob": { "type": [ "string", "null" ], "enum": [ "1990-01-01", "1985-06-15", "1970-09-20", null ] }, "serviceDate": { "type": [ "string", "null" ], "format": "date" }, "payer": { "type": [ "string", "null" ], "enum": [ "DEMO_COMMERCIAL", "DEMO_MEDICARE", "DEMO_MEDICAID", null ] }, "memberId": { "type": [ "string", "null" ], "enum": [ "TEST_MEMBER_01", "TEST_MEMBER_02", "TEST_MEMBER_03", null ] } } }, "revision": { "type": "integer", "minimum": 0, "description": "0 to create; the last returned revision to update." }, "humanReviewed": { "const": true } } } } } } } }, "/api/v1/intake/extract": { "post": { "summary": "Extract a synthetic intake draft with AI", "description": "Required scope: analysis:write. Synthetic examples only. No patient processing or live payer submission. AI extraction shares the existing 20/day workspace and 100/month project allowance.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Intake metadata with submissionEnabled/liveSubmission false." }, "422": { "description": "Invalid input, unsupported synthetic data, or review missing." }, "429": { "description": "Rate, queue, or AI allowance reached." }, "503": { "description": "AI unavailable; use manual entry." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 1200, "example": "Patient Alex Example. DOB 1990-01-01. Service date 2026-10-15. Payer DEMO_COMMERCIAL. Member ID TEST_MEMBER_01." } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cl_test_ API key" } }, "schemas": { "EstimateRequest": { "type": "object", "additionalProperties": false, "required": [ "monthlySelfPayEncounters", "averageClaimValue", "discoveryRate" ], "properties": { "monthlySelfPayEncounters": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "averageClaimValue": { "type": "number", "minimum": 0.01, "maximum": 1000000 }, "discoveryRate": { "type": "number", "minimum": 0, "maximum": 1 } } }, "WorkflowRequest": { "type": "object", "additionalProperties": false, "required": [ "encounterReference", "claimValue", "coverageKnown", "eligibilityVerified", "authorizationRequired", "authorizationStatus", "deductibleRemaining", "daysUntilFilingDeadline", "retroactiveCoverage" ], "properties": { "encounterReference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Use only test identifiers, never patient data." }, "claimValue": { "type": "number", "minimum": 0.01, "maximum": 1000000 }, "coverageKnown": { "type": "boolean" }, "eligibilityVerified": { "type": "boolean" }, "authorizationRequired": { "type": "boolean" }, "authorizationStatus": { "type": "string", "enum": [ "not_required", "pending", "approved", "denied" ] }, "deductibleRemaining": { "type": "number", "minimum": 0, "maximum": 1000000 }, "daysUntilFilingDeadline": { "type": "integer", "minimum": -365, "maximum": 3650 }, "retroactiveCoverage": { "type": "boolean" } } }, "Error": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" } } }, "BatchRequest": { "type": "object", "additionalProperties": false, "required": [ "encounters" ], "properties": { "encounters": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/WorkflowRequest" } } } }, "ReadinessRequest": { "type": "object", "additionalProperties": false, "required": [ "monthlyEncounters", "selfPayPercentage", "denialPercentage", "manualMinutesPerEncounter", "ehrConnectionReady" ], "properties": { "monthlyEncounters": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "selfPayPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "denialPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "manualMinutesPerEncounter": { "type": "number", "minimum": 0, "maximum": 240 }, "ehrConnectionReady": { "type": "boolean" } } }, "AIRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "organizationType", "data" ], "properties": { "kind": { "type": "string", "const": "opportunity" }, "organizationType": { "type": "string", "enum": [ "ems", "hospital", "specialty", "rcm" ] }, "data": { "$ref": "#/components/schemas/EstimateRequest" } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "organizationType", "data" ], "properties": { "kind": { "type": "string", "const": "workflow" }, "organizationType": { "type": "string", "enum": [ "ems", "hospital", "specialty", "rcm" ] }, "data": { "$ref": "#/components/schemas/WorkflowRequest" } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "organizationType", "data" ], "properties": { "kind": { "type": "string", "const": "readiness" }, "organizationType": { "type": "string", "enum": [ "ems", "hospital", "specialty", "rcm" ] }, "data": { "$ref": "#/components/schemas/ReadinessRequest" } } } ] } } } }