{"openapi":"3.1.0","info":{"title":"MedChartScan E/M API","description":"MedChartScan E/M: Evaluation and Management (E/M) coding of clinical notes. Authenticate with an access token from POST /v1/oauth/token. Errors are JSON: {\"error\": {\"code\", \"message\"}}; messages never echo your input.","version":"1"},"paths":{"/v1/oauth/token":{"post":{"summary":"Get an access token","description":"OAuth 2.0 client credentials. Send the key's client_id and client_secret in the form or JSON body, or as HTTP Basic credentials. The token is valid for one hour. At most 20 tokens per key per minute; at most 30 failed authentications per client IP per minute.","operationId":"token_v1_oauth_token_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string","description":"Omit when sending HTTP Basic credentials."},"client_secret":{"type":"string","description":"Omit when sending HTTP Basic credentials."}},"type":"object","required":["grant_type"]},"example":{"grant_type":"client_credentials","client_id":"mcs_ci_k3x7q2mzr5tvw4yb6nhd2pfa","client_secret":"mcs_sk_…"}},"application/json":{"schema":{"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string","description":"Omit when sending HTTP Basic credentials."},"client_secret":{"type":"string","description":"Omit when sending HTTP Basic credentials."}},"type":"object","required":["grant_type"]},"example":{"grant_type":"client_credentials","client_id":"mcs_ci_k3x7q2mzr5tvw4yb6nhd2pfa","client_secret":"mcs_sk_…"}}},"required":true},"responses":{"200":{"description":"An access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenOut"}}}},"400":{"description":"invalid_request or unsupported_grant_type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"401":{"description":"invalid_client: unknown, wrong or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"403":{"description":"org_locked: support locked the key's organization, so no token is issued. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"429":{"description":"slow_down: more than 20 tokens, or more than 20 wrong secrets, for this key in the current minute (a wrong secret never blocks the right one), or a failed authentication after 30 from your IP address in the current minute (correct credentials still get a token; malformed requests don't count). Retry-After gives the seconds until the next minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{},{"basicAuth":[]}]}},"/v1/analyses":{"post":{"summary":"Analyze one note","description":"Runs the E/M analysis and returns the result (typically about 40 seconds; use a client timeout of 300 seconds). One credit is charged only when the status is succeeded.","operationId":"create_analysis_v1_analyses_post","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional, 1-255 printable ASCII characters, kept 24 hours per organization. A retry with the same key and body returns the original response without running or charging again.","title":"Idempotency-Key"},"description":"Optional, 1-255 printable ASCII characters, kept 24 hours per organization. A retry with the same key and body returns the original response without running or charging again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeIn"}}}},"responses":{"200":{"description":"The result (succeeded or out_of_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisOut"}}}},"400":{"description":"invalid_request: the request is malformed or a field is invalid (the message names the fields, never their values or keys you chose); also an invalid Idempotency-Key, an invalid cursor, or a date outside 2000-01-01 to 2100-01-01.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits: the balance does not cover the request. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"baa_resign_required: the organization is past its due date to sign an updated BAA, so new notes and batches are refused until an owner signs it (reads still work); org_suspended: support suspended the organization, so new notes and batches are refused (reads still work); org_locked: support locked the organization, so every request is refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict (the key was used with another request) or idempotency_in_progress (the first request with this key is still running).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"note_too_long: a note exceeds 100,000 characters; request_too_large: the body exceeds 1 MB (12 MB for POST /v1/batches).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"test_data_required: the organization's BAA is not accepted yet; send \"test_data\": true with test data only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the organization's per-minute limit (60, or 10 until it first buys credits), or too_many_uncharged_runs: 25 notes ended failed or out of scope in the last 24 hours (never charged, so limited). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"analysis_failed: the analysis could not be completed. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List results","description":"Newest first. Pass `next_cursor` back as `cursor` for the next page. To filter by client_reference, channel or the review signals (coding_change, has_missed_revenue, has_denial_risk), use POST /v1/analyses/search (filters never go in a URL).","operationId":"list_analyses_v1_analyses_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["queued","running","succeeded","failed","out_of_scope"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only results created after this time (2000-01-01 to 2100-01-01; no offset means UTC).","title":"Created After"},"description":"Only results created after this time (2000-01-01 to 2100-01-01; no offset means UTC)."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only results created before this time (2000-01-01 to 2100-01-01; no offset means UTC).","title":"Created Before"},"description":"Only results created before this time (2000-01-01 to 2100-01-01; no offset means UTC)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Opaque `next_cursor` from the previous page, passed back unchanged (up to 512 characters). Don't build or edit one: an invalid cursor is 400 invalid_request.","title":"Cursor"},"description":"Opaque `next_cursor` from the previous page, passed back unchanged (up to 512 characters). Don't build or edit one: an invalid cursor is 400 invalid_request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisPage"}}}},"400":{"description":"invalid_request: the request is malformed or a field is invalid (the message names the fields, never their values or keys you chose); also an invalid Idempotency-Key, an invalid cursor, or a date outside 2000-01-01 to 2100-01-01.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"org_locked: support locked the organization, so every request is refused. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: more than 600 reads (GET requests and POST /v1/analyses/search) for this API key in the current minute; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analyses/search":{"post":{"summary":"Search results","description":"The list filters, including client_reference and the review-signal filters (coding_change, has_missed_revenue, has_denial_risk) and channel, in a request body.","operationId":"search_analyses_v1_analyses_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisPage"}}}},"400":{"description":"invalid_request: the request is malformed or a field is invalid (the message names the fields, never their values or keys you chose); also an invalid Idempotency-Key, an invalid cursor, or a date outside 2000-01-01 to 2100-01-01.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"org_locked: support locked the organization, so every request is refused. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"request_too_large: the body exceeds 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: more than 600 reads (GET requests and POST /v1/analyses/search) for this API key in the current minute; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/analyses/{analysis_id}":{"get":{"summary":"Get a result","operationId":"get_analysis_v1_analyses__analysis_id__get","security":[{"bearerAuth":[]}],"parameters":[{"name":"analysis_id","in":"path","required":true,"schema":{"type":"string","title":"Analysis Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisOut"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"org_locked: support locked the organization, so every request is refused. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such result or batch for this organization's API keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: more than 600 reads (GET requests and POST /v1/analyses/search) for this API key in the current minute; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a result","description":"Deletes the result with its note and report. A queued batch note is not run and its credit is returned. A running analysis can't be deleted (409 analysis_running): delete it once it has finished. Deleting results does not free rate-limit slots.","operationId":"delete_analysis_v1_analyses__analysis_id__delete","security":[{"bearerAuth":[]}],"parameters":[{"name":"analysis_id","in":"path","required":true,"schema":{"type":"string","title":"Analysis Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"org_locked: support locked the organization, so every request is refused. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such result or batch for this organization's API keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"analysis_running: the analysis is still running. Delete it once it has finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/credits":{"get":{"summary":"Credit balance","description":"The balance and the lots it is drawn from, soonest to expire first.","operationId":"credits_v1_credits_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsOut"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"org_locked: support locked the organization, so every request is refused. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: more than 600 reads (GET requests and POST /v1/analyses/search) for this API key in the current minute; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/batches":{"post":{"summary":"Analyze many notes","description":"Queues up to 100 notes and returns at once (202). Poll GET /v1/batches/{id} until finished_at is set. One credit is held per note and charged only for notes that succeed. Counts as one call toward the per-minute rate limit. An idempotent replay returns the batch as it is now.","operationId":"create_batch_v1_batches_post","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional, 1-255 printable ASCII characters, kept 24 hours per organization. A retry with the same key and body returns the original response without running or charging again.","title":"Idempotency-Key"},"description":"Optional, 1-255 printable ASCII characters, kept 24 hours per organization. A retry with the same key and body returns the original response without running or charging again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchIn"}}}},"responses":{"202":{"description":"The batch, with its notes queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchOut"}}}},"400":{"description":"invalid_request: the request is malformed or a field is invalid (the message names the fields, never their values or keys you chose); also an invalid Idempotency-Key, an invalid cursor, or a date outside 2000-01-01 to 2100-01-01.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits: the balance does not cover every note. Nothing was stored or held.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"baa_resign_required: the organization is past its due date to sign an updated BAA, so new notes and batches are refused until an owner signs it (reads still work); org_suspended: support suspended the organization, so new notes and batches are refused (reads still work); org_locked: support locked the organization, so every request is refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict or idempotency_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"note_too_long: a note exceeds 100,000 characters; request_too_large: the body exceeds 1 MB (12 MB for POST /v1/batches).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"test_data_required: the organization's BAA is not accepted yet; send \"test_data\": true with test data only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-organization limit per minute on analyses: 60, or 10 until the organization first buys credits; on reads, GET requests and POST /v1/analyses/search: 600 per API key per minute; see Retry-After), too_many_uncharged_runs (25 notes ended failed or out of scope in the last 24 hours; see Retry-After) or too_many_batches (5 unfinished batches).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List batches","description":"Batches created through the API in your organization, newest first, with their status counts. Pass `next_cursor` back as `cursor` for the next page.","operationId":"list_batches_v1_batches_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Opaque `next_cursor` from the previous page, passed back unchanged (up to 512 characters). Don't build or edit one: an invalid cursor is 400 invalid_request.","title":"Cursor"},"description":"Opaque `next_cursor` from the previous page, passed back unchanged (up to 512 characters). Don't build or edit one: an invalid cursor is 400 invalid_request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_BatchSummary_"}}}},"400":{"description":"invalid_request: the request is malformed or a field is invalid (the message names the fields, never their values or keys you chose); also an invalid Idempotency-Key, an invalid cursor, or a date outside 2000-01-01 to 2100-01-01.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"org_locked: support locked the organization, so every request is refused. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: more than 600 reads (GET requests and POST /v1/analyses/search) for this API key in the current minute; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches/{batch_id}":{"get":{"summary":"Get a batch","description":"Status counts and every note (in submission order, each showing its latest attempt). Open a finished note with GET /v1/analyses/{id}.","operationId":"get_batch_v1_batches__batch_id__get","security":[{"bearerAuth":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchOut"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"org_locked: support locked the organization, so every request is refused. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such result or batch for this organization's API keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: more than 600 reads (GET requests and POST /v1/analyses/search) for this API key in the current minute; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches/{batch_id}/retry":{"post":{"summary":"Retry failed notes","description":"Queues failed notes again, each as a new note id in the same position, with a new credit hold. A failed note can be retried for 7 days.","operationId":"retry_batch_v1_batches__batch_id__retry_post","security":[{"bearerAuth":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/RetryIn"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchOut"}}}},"400":{"description":"invalid_request: the request is malformed or a field is invalid (the message names the fields, never their values or keys you chose); also an invalid Idempotency-Key, an invalid cursor, or a date outside 2000-01-01 to 2100-01-01.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the access token is missing, invalid, expired or its key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits: the balance does not cover the request. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"baa_resign_required: the organization is past its due date to sign an updated BAA, so new notes and batches are refused until an owner signs it (reads still work); org_suspended: support suspended the organization, so new notes and batches are refused (reads still work); org_locked: support locked the organization, so every request is refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such result or batch for this organization's API keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_retryable: a listed note did not fail, or its 7-day retry window has passed. Nothing changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"request_too_large: the body exceeds 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"too_many_batches: 5 unfinished batches, or too_many_uncharged_runs: 25 notes ended failed or out of scope in the last 24 hours (see Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side. Retry with backoff; with an Idempotency-Key, a retry never runs or charges twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"ActiveProblem":{"properties":{"icd10":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Icd10"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"},"onset_date":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Onset Date"},"status":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Status"}},"additionalProperties":false,"type":"object","title":"ActiveProblem","description":"The engine's ActiveProblem with bounded strings: `icd10` (or `diagnosis_code`),\n`description`, `onset_date` (or `created_date`) and `status`. Unknown fields are refused."},"AnalysisListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","enum":["queued","running","succeeded","failed","out_of_scope"],"title":"Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"is_test":{"type":"boolean","title":"Is Test"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"client_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Reference"},"batch_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Batch Id"},"final_cpt_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Cpt Code"},"channel":{"type":"string","enum":["api","api_batch"],"title":"Channel","description":"How the result was run: api (one POST /v1/analyses call) or api_batch (a note of a POST /v1/batches batch).","default":"api"},"submitted_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted Code","description":"The first E/M code among the submitted cpts (add-on and procedure codes are skipped). Null unless succeeded, and when no E/M code was submitted."},"coding_change":{"anyOf":[{"type":"string","enum":["upgraded","maintained","downgraded","changed","not_submitted"]},{"type":"null"}],"title":"Coding Change","description":"How the supported code compares with submitted_code: upgraded or downgraded (a higher or lower level in the same office visit family), maintained (the same code), changed (another family, such as new versus established, or no single office code supported) or not_submitted (no E/M code was submitted). Null unless succeeded."},"missed_revenue_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Missed Revenue Count","description":"How many missed revenue opportunities the report lists (report.revenueAndCompliance.missedRevenueOpportunities). Null unless succeeded."},"denial_risk_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Denial Risk Count","description":"How many denial risks the report lists (report.revenueAndCompliance.denialRiskAssessment). Null unless succeeded."}},"type":"object","required":["id","status","created_at","is_test","expires_at","client_reference","batch_id","final_cpt_code","channel","submitted_code","coding_change","missed_revenue_count","denial_risk_count"],"title":"AnalysisListItem","examples":[{"channel":"api","client_reference":"enc-2026-10-25-0001","coding_change":"upgraded","created_at":"2026-10-25T14:10:00Z","denial_risk_count":0,"final_cpt_code":"99214","id":"7f9c2d4e-1b3a-4c5d-8e6f-0a1b2c3d4e5f","is_test":false,"missed_revenue_count":1,"status":"succeeded","submitted_code":"99213"}]},"AnalysisOut":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","enum":["queued","running","succeeded","failed","out_of_scope"],"title":"Status"},"is_test":{"type":"boolean","title":"Is Test"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"credits_charged":{"type":"integer","title":"Credits Charged"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"organization_status":{"type":"string","enum":["pending","active","paused"],"title":"Organization Status"},"client_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Reference"},"channel":{"type":"string","enum":["api","api_batch"],"title":"Channel","description":"How the result was run: api (one POST /v1/analyses call) or api_batch (a note of a POST /v1/batches batch).","default":"api"},"submitted_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted Code","description":"The first E/M code among the submitted cpts (add-on and procedure codes are skipped). Null unless succeeded, and when no E/M code was submitted."},"coding_change":{"anyOf":[{"type":"string","enum":["upgraded","maintained","downgraded","changed","not_submitted"]},{"type":"null"}],"title":"Coding Change","description":"How the supported code compares with submitted_code: upgraded or downgraded (a higher or lower level in the same office visit family), maintained (the same code), changed (another family, such as new versus established, or no single office code supported) or not_submitted (no E/M code was submitted). Null unless succeeded."},"missed_revenue_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Missed Revenue Count","description":"How many missed revenue opportunities the report lists (report.revenueAndCompliance.missedRevenueOpportunities). Null unless succeeded."},"denial_risk_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Denial Risk Count","description":"How many denial risks the report lists (report.revenueAndCompliance.denialRiskAssessment). Null unless succeeded."},"report":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Report"}},"type":"object","required":["id","status","is_test","expires_at","credits_charged","credits_remaining","organization_status","client_reference","channel","submitted_code","coding_change","missed_revenue_count","denial_risk_count","report"],"title":"AnalysisOut","description":"A result. `report` is the full E/M analysis (null until succeeded, and for out of scope).","examples":[{"channel":"api","client_reference":"enc-2026-10-25-0001","coding_change":"upgraded","credits_charged":1,"credits_remaining":49,"denial_risk_count":0,"id":"7f9c2d4e-1b3a-4c5d-8e6f-0a1b2c3d4e5f","is_test":false,"missed_revenue_count":1,"organization_status":"active","report":{"codingAnalysis":{"finalCptCode":"99214"}},"status":"succeeded","submitted_code":"99213"}]},"AnalysisPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AnalysisListItem"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque: pass it back unchanged as `cursor` for the next page. Null on the last page."}},"type":"object","required":["items","next_cursor"],"title":"AnalysisPage"},"AnalyzeIn":{"properties":{"document_text":{"type":"string","maxLength":100000,"minLength":20,"title":"Document Text"},"cpts":{"items":{"$ref":"#/components/schemas/CptIn"},"type":"array","maxItems":50,"title":"Cpts"},"icds":{"items":{"type":"string","maxLength":8,"minLength":3},"type":"array","maxItems":100,"title":"Icds"},"jurisdiction":{"anyOf":[{"type":"string","enum":["AL","AK","AZ","AR","CA","CO","CT","DE","DC","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY","AS","GU","MP","PR","VI"],"description":"A US state, DC or territory code in capitals, such as TX."},{"type":"null"}],"title":"Jurisdiction"},"visit_type":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Visit Type"},"provider_type":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Provider Type"},"patient_demographics":{"anyOf":[{"$ref":"#/components/schemas/PatientDemographics"},{"type":"null"}],"description":"Optional. gender and dob: up to 100 characters each."},"active_problems":{"items":{"anyOf":[{"type":"string","maxLength":500},{"$ref":"#/components/schemas/ActiveProblem"}]},"type":"array","maxItems":50,"title":"Active Problems","description":"Up to 50 entries: a string of up to 500 characters, or an object (description up to 500 characters; icd10, onset_date and status up to 100 each)."},"client_reference":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Client Reference","description":"Your own identifier for the note (an encounter id, a file name). Returned with the result; never logged. Filter by it with POST /v1/analyses/search."},"test_data":{"type":"boolean","title":"Test Data","description":"Required (true) while your organization's BAA is not yet accepted: you confirm the note is test data with no PHI. Results are then marked is_test and expire in 30 days.","default":false}},"additionalProperties":false,"type":"object","required":["document_text"],"title":"AnalyzeIn","description":"One clinical note to code. Only `document_text` is required.","examples":[{"client_reference":"enc-2026-10-25-0001","cpts":[{"code":"99214","modifiers":[],"units":1}],"document_text":"Established patient seen for follow-up of type 2 diabetes and hypertension. Reports good adherence to metformin; no hypoglycemia. BP 138/86. A1c 7.4% reviewed. Assessment: diabetes, improving; hypertension, not at goal. Plan: increase lisinopril to 20 mg daily, recheck BMP in 2 weeks, follow up in 3 months.","icds":["E11.9","I10"],"jurisdiction":"TX"}]},"BatchCounts":{"properties":{"queued":{"type":"integer","title":"Queued","default":0},"running":{"type":"integer","title":"Running","default":0},"succeeded":{"type":"integer","title":"Succeeded","default":0},"failed":{"type":"integer","title":"Failed","default":0},"out_of_scope":{"type":"integer","title":"Out Of Scope","default":0}},"type":"object","title":"BatchCounts"},"BatchIn":{"properties":{"label":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Label","description":"Your name for the batch."},"items":{"items":{"$ref":"#/components/schemas/BatchItemIn"},"type":"array","maxItems":100,"minItems":1,"title":"Items"},"test_data":{"type":"boolean","title":"Test Data","description":"Required (true) while your organization's BAA is not yet accepted: you confirm the note is test data with no PHI. Results are then marked is_test and expire in 30 days.","default":false}},"additionalProperties":false,"type":"object","required":["items"],"title":"BatchIn","description":"Up to 100 notes, analyzed in the background. Poll GET /v1/batches/{id}.","examples":[{"items":[{"client_reference":"enc-0001","document_text":"Established patient seen for follow-up of type 2 diabetes and hypertension. Reports good adherence to metformin; no hypoglycemia. BP 138/86. A1c 7.4% reviewed. Assessment: diabetes, improving; hypertension, not at goal. Plan: increase lisinopril to 20 mg daily, recheck BMP in 2 weeks, follow up in 3 months.","jurisdiction":"TX"},{"client_reference":"enc-0002","document_text":"New patient with acute low back pain after lifting, no red flags. Exam: paraspinal tenderness, normal strength and reflexes. Plan: NSAIDs, activity as tolerated, return if worse."}],"label":"Clinic day 2026-10-25"}]},"BatchItemIn":{"properties":{"document_text":{"type":"string","maxLength":100000,"minLength":20,"title":"Document Text"},"cpts":{"items":{"$ref":"#/components/schemas/CptIn"},"type":"array","maxItems":50,"title":"Cpts"},"icds":{"items":{"type":"string","maxLength":8,"minLength":3},"type":"array","maxItems":100,"title":"Icds"},"jurisdiction":{"anyOf":[{"type":"string","enum":["AL","AK","AZ","AR","CA","CO","CT","DE","DC","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY","AS","GU","MP","PR","VI"],"description":"A US state, DC or territory code in capitals, such as TX."},{"type":"null"}],"title":"Jurisdiction"},"visit_type":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Visit Type"},"provider_type":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Provider Type"},"patient_demographics":{"anyOf":[{"$ref":"#/components/schemas/PatientDemographics"},{"type":"null"}],"description":"Optional. gender and dob: up to 100 characters each."},"active_problems":{"items":{"anyOf":[{"type":"string","maxLength":500},{"$ref":"#/components/schemas/ActiveProblem"}]},"type":"array","maxItems":50,"title":"Active Problems","description":"Up to 50 entries: a string of up to 500 characters, or an object (description up to 500 characters; icd10, onset_date and status up to 100 each)."},"client_reference":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Client Reference"}},"additionalProperties":false,"type":"object","required":["document_text"],"title":"BatchItemIn","description":"One note of a batch. `client_reference` is the caller's own label for the note (a file\nname, an encounter id): it may be PHI, so it is returned to the org but never logged,\nemailed or audited."},"BatchItemOut":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"client_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Reference"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When this attempt was submitted (a retried note shows its retry's time)."},"status":{"type":"string","title":"Status"},"final_cpt_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Cpt Code"},"retryable":{"type":"boolean","title":"Retryable"},"submitted_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted Code","description":"The first E/M code submitted with the note. Null unless succeeded."},"coding_change":{"anyOf":[{"type":"string","enum":["upgraded","maintained","downgraded","changed","not_submitted"]},{"type":"null"}],"title":"Coding Change","description":"How final_cpt_code compares with submitted_code: upgraded, maintained, downgraded, changed (another E/M family, or no single office code) or not_submitted (no E/M code was submitted). Null unless succeeded."},"missed_revenue_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Missed Revenue Count","description":"Missed revenue opportunities in the report. Null unless succeeded."},"denial_risk_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Denial Risk Count","description":"Denial risks in the report. Null unless succeeded."}},"type":"object","required":["id","client_reference","created_at","status","final_cpt_code","retryable","submitted_code","coding_change","missed_revenue_count","denial_risk_count"],"title":"BatchItemOut"},"BatchOut":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"source":{"type":"string","title":"Source"},"is_test":{"type":"boolean","title":"Is Test"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Who started the batch: the member's email for a web batch, the API key's label (its client ID if the label is empty) for an API batch. Null when the member has left the organization or the key no longer exists."},"counts":{"$ref":"#/components/schemas/BatchCounts"},"items":{"items":{"$ref":"#/components/schemas/BatchItemOut"},"type":"array","title":"Items"}},"type":"object","required":["id","label","source","is_test","created_at","finished_at","created_by","counts","items"],"title":"BatchOut"},"BatchSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"source":{"type":"string","title":"Source"},"is_test":{"type":"boolean","title":"Is Test"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At"},"item_count":{"type":"integer","title":"Item Count"},"counts":{"$ref":"#/components/schemas/BatchCounts"}},"type":"object","required":["id","label","source","is_test","created_at","finished_at","item_count","counts"],"title":"BatchSummary"},"CptIn":{"properties":{"code":{"type":"string","maxLength":5,"minLength":5,"title":"Code"},"units":{"type":"integer","maximum":99.0,"minimum":1.0,"title":"Units","default":1},"modifiers":{"items":{"type":"string","maxLength":4},"type":"array","maxItems":4,"title":"Modifiers"}},"additionalProperties":false,"type":"object","required":["code"],"title":"CptIn"},"CreditsOut":{"properties":{"balance":{"type":"integer","title":"Balance"},"lots":{"items":{"$ref":"#/components/schemas/LotOut"},"type":"array","title":"Lots"}},"type":"object","required":["balance","lots"],"title":"CreditsOut"},"Error":{"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"type":"object","required":["error"],"title":"Error"},"ErrorDetail":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"ErrorDetail"},"LotOut":{"properties":{"remaining":{"type":"integer","title":"Remaining"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["remaining","expires_at"],"title":"LotOut"},"OAuthError":{"properties":{"error":{"type":"string","enum":["invalid_request","invalid_client","unsupported_grant_type","slow_down","org_locked"],"title":"Error"},"error_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Description"}},"type":"object","required":["error"],"title":"OAuthError"},"Page_BatchSummary_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BatchSummary"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque: pass it back unchanged as `cursor` for the next page. Null on the last page."}},"type":"object","required":["items","next_cursor"],"title":"Page[BatchSummary]"},"PatientDemographics":{"properties":{"age":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age"},"gender":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Gender"},"dob":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Dob"}},"additionalProperties":false,"type":"object","title":"PatientDemographics","description":"The engine's PatientDemographics with bounded strings (converted for the engine in\nanalyses.service._engine_input). Unknown fields are refused."},"RetryIn":{"properties":{"analysis_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100,"minItems":1},{"type":"null"}],"title":"Analysis Ids"}},"additionalProperties":false,"type":"object","title":"RetryIn","description":"Omit `analysis_ids` (or send no body) to retry every failed note still within its\n7-day retry window."},"SearchIn":{"properties":{"client_reference":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Client Reference"},"status":{"anyOf":[{"type":"string","enum":["queued","running","succeeded","failed","out_of_scope"]},{"type":"null"}],"title":"Status"},"created_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created After","description":"Only results created after this time (2000-01-01 to 2100-01-01; no offset means UTC)."},"created_before":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Before","description":"Only results created before this time (2000-01-01 to 2100-01-01; no offset means UTC)."},"channel":{"anyOf":[{"type":"string","enum":["api","api_batch"]},{"type":"null"}],"title":"Channel","description":"Only single calls (api) or only batch notes (api_batch)."},"coding_change":{"anyOf":[{"type":"string","enum":["upgraded","maintained","downgraded","changed","not_submitted"]},{"type":"null"}],"title":"Coding Change","description":"Only results with this coding_change."},"has_missed_revenue":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Missed Revenue","description":"true: only results with at least one missed revenue opportunity; false: only succeeded results with none. Omit for no filter."},"has_denial_risk":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Denial Risk","description":"true: only results with at least one denial risk; false: only succeeded results with none. Omit for no filter."},"cursor":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Cursor","description":"Opaque `next_cursor` from the previous page, passed back unchanged (up to 512 characters). Don't build or edit one: an invalid cursor is 400 invalid_request."},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","default":50}},"additionalProperties":false,"type":"object","title":"SearchIn","description":"List filters in a body, so a client reference never appears in a URL.","examples":[{"client_reference":"enc-2026-10-25-0001","limit":10},{"has_missed_revenue":true,"limit":50},{"coding_change":"downgraded","has_denial_risk":true}]},"TokenOut":{"properties":{"access_token":{"type":"string","title":"Access Token"},"token_type":{"type":"string","const":"Bearer","title":"Token Type"},"expires_in":{"type":"integer","title":"Expires In"}},"type":"object","required":["access_token","token_type","expires_in"],"title":"TokenOut"}},"securitySchemes":{"bearerAuth":{"type":"http","description":"An access token from POST /v1/oauth/token (`mcs_at_…`, valid one hour).","scheme":"bearer","bearerFormat":"opaque"},"basicAuth":{"type":"http","scheme":"basic","description":"client_id and client_secret, for POST /v1/oauth/token only."}}},"servers":[{"url":"https://api.medchartscan.io"}]}