---
title: "Code Condition"
method: POST
path: "/api/v1/code"
tags: ["code"]
---

# Code Condition

`POST /api/v1/code`

## Request

- Base URL: `https://api.accurecord.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.accurecord.io/api/v1/code`
- Auth: none declared

Convert natural language condition to ICD-10-CM codes.

Uses an AI agent with function calling to implement the proper ICD-10
coding workflow:

1. **Normalize input**: Expand abbreviations (DM2 → diabetes mellitus type 2)
2. **Alphabetic index lookup**: Find candidate codes
3. **Tabular verification**: Verify codes and check instructional notes
4. **Combination code check**: Look for single codes covering multiple conditions
5. **Structured response**: Return codes with reasoning and confidence

**Example request:**
```json
{
  "condition": "DM2 w/ CKD stage 3",
  "include_hcc": true
}
```

**Example response:**
```json
{
  "success": true,
  "codes_mentioned": ["E11.22", "N18.3"],
  "reasoning": "Type 2 diabetes with chronic kidney disease...",
  "confidence": "high",
  "warnings": [],
  "tool_calls_made": [...],
  "tokens_used": 1234
}
```

**Note:** This endpoint requires Pro or Enterprise tier.

## Headers

- `x-api-key` string, nullable

## Request body

- CodeRequest: Request body for AI coding.
  - `condition` string, required: Natural language condition description
  - `year` integer, nullable: ICD-10-CM fiscal year
  - `include_hcc` boolean: Include HCC risk adjustment information
  - `prior_codes` string[], nullable: Codes already assigned earlier in this encounter. Triggers cross-condition excludes1 detection.
  - `encounter_metadata` EncounterMetadata: Optional encounter context for denial-prevention rules.
    - `principal_code` string, nullable
    - `patient_age` integer, nullable
    - `patient_sex` string, nullable
    - `trimester` integer, nullable: Pregnancy trimester (1-3) for MCE trimester edits
    - `setting` 'inpatient_acute' | 'observation' | 'emergency_department' | 'hospital_outpatient' | 'office' | 'skilled_nursing_facility' | 'standalone_diagnostic': The A5 setting vocabulary (step map: IP / OP / office / ED / obs / SNF). Telehealth is deliberately NOT a member — §A4.7 rules it a MODALITY. An encounter conducted by video is ``OFFICE`` + ``Modality.TELEHEALTH_SYNCHRONOUS_AUDIO_VIDEO``.
  - `code_uncertain_diagnoses` boolean: Code uncertain/probable/rule-out/differential diagnoses as if established (inpatient & discharge-summary coding, ICD-10-CM Guideline II.H). Each such code is labelled `coded_as_uncertain` in the per-concept output and flagged in warnings. Default false keeps the outpatient rule (Guideline IV.H): uncertain dx are not coded.
  - `meat_profile` string, nullable: Name of the MEAT profile to use for evidence extraction (e.g. 'radv_strict' or 'ma_lite'). Falls back to the org's default profile if unset, or omits MEAT entirely if no profile is configured.
  - `coding_policy` string, nullable: Name of the per-project coding-policy profile (Layer 2 rules: code/don't-code by chart section, chronic recapture, etc.). Falls back to the org's default policy if unset; if neither exists, coding behavior is unchanged.
  - `hcc_model_version` string, nullable: HCC model version for RAF computation: 'V28' (CY2026 default) or 'V24' (legacy). Falls back to the org's preferred_hcc_model_version, then to V28.
  - `hcc_segment` string, nullable: Beneficiary segment for RAF lookup, e.g. 'community_nondual_aged' (default), 'institutional', 'community_full_dual_aged'.
  - `payer` string, nullable: Payer slug ('uhc', 'humana', 'aetna', 'anthem', 'kaiser', etc.). Surfaces payer-specific denial rules in the response's verification.findings under detail.payer.
  - `chart_id` string, nullable: Optional chart_review_jobs.id this coding belongs to. Passing it (or member_id below) opts the request into reviewer mode: each verified code is persisted as a Recommendation row reviewable via /api/v1/reviewer/* endpoints.
  - `member_id` string, nullable: Optional members.id this coding belongs to. Like chart_id, passing it opts the request into reviewer mode.
  - `previously_submitted_codes` string[], nullable: Codes ALREADY SENT TO THE PAYER for this member, to be reviewed against what this chart documents. Returns a `support_review` block per code. ⚠ This is NOT `prior_codes`: that means codes assigned earlier in THIS encounter and exists so the Excludes1 engine can see them. This asks the opposite question — does the documentation still support a code someone already submitted? Requires the support_review_enabled deployment flag (explicit 400 when off).
  - `include_hcc_decisions` boolean: Include `hcc_decisions[]` — one decision object per candidate diagnosis, saying which codes it produced, which chart spans licensed them, which findings applied and what it contributed to RAF. Modelled on include_hcc: opt-in, and never changes the codes. Requires an HCC-enabled key (403 otherwise) and the hcc_lane_enabled deployment flag (explicit 400 when off, never a silent omission).

## Response `200`

Coding result. `data` is OPEN — keys are added over time and a client must ignore ones it does not know rather than reject the response.

- object
  - `success` boolean, required
  - `data` object, required: Engine output. Not exhaustive — see docs/API.md and docs/API_CHANGELOG.md for additions.
    - `codes_mentioned` string[]: Final ICD-10-CM codes, in sequence order.
    - `code_evidence` object: code -> [chart span]. A list because the compiler can merge two documented concepts into one code, so a caller cannot rebuild it by joining on `code`.
    - `reasoning` string
    - `confidence` string
    - `warnings` string[]
    - `verification` object: Post-LLM verification report.
    - `documentation_gaps` unknown[]
      - unknown
    - `corpus_ready` boolean: Standing health of the retrieval corpus FOR THIS REQUEST'S fiscal year. False means the hybrid search channel was dark and recall was reduced.
    - `degradations` object[]: Everything that went wrong on THIS request, typed so a caller branches on `kind` instead of parsing prose. Empty = a clean run. ⚠ `kind` is an OPEN set (`search_corpus_dark`, `disambiguation_degraded`, `llm_circuit_open`, `terminology_unavailable` today) — ignore unknown kinds; do not assume the list is exhaustive.
      - `kind` string
    - `pipeline` string
    - `tokens_used` integer

## Other responses

- `400`: Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.
- `401`: Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.
- `403`: Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.
- `404`: Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.
- `412`: A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.
- `422`: Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).
- `429`: Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.
- `500`: Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.
- `503`: The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.

---

[API](https://skmtc.dev/accurecord/apis/icd-10-coding-api.md) · [All operations](https://skmtc.dev/accurecord/apis/icd-10-coding-api/llms.txt) · [OpenAPI document](https://skmtc.dev/accurecord/apis/icd-10-coding-api/revisions/b1e12ce06ba5?raw)