{"openapi":"3.1.0","info":{"title":"DOCumenter Partner API","description":"Swiss medical documentation API for EHR integrations.\n\n**Two submission formats, one job lifecycle.** Submit audio, documents, or text and receive structured medical reports, transcriptions with speaker diarization and medication extraction, and TARDOC billing codes.\n\n## Authentication\n\nProduction and partner-parity requests use two headers: `Authorization: Bearer <api_key>` + `X-User-Token: <physician_id>`. Only quick-evaluation sandbox keys omit the physician header.\n\n- **Institution keys** (`doc_live_`): X-User-Token is a JWT signed with your signing secret\n- **Partner keys** (`doc_partner_`): X-User-Token is a pairing code (e.g., `DOC-A7K2M3P9`)\n- **Quick-evaluation sandbox keys** (`doc_test_`): X-User-Token is optional and responses are mocked\n- **Partner-parity sandbox keys** (`doc_test_`): use the supplied fake pairing codes to exercise real auth, tier gates, and entitlements\n\n## Rate Limits\n\nDefault: **30 requests/minute** per API key, **10 concurrent jobs**. Exceeding limits returns `429 Too Many Requests` with a `Retry-After` header. Limits are per API key (not per physician). Polls of a job you own are exempt from the per-minute budget and are instead throttled to about one poll per 2 seconds per (key, physician, job) — treat it as a floor on your poll interval, not a quota; polling job ids you do not own does spend the budget. Contact dev@documenter.ch to increase.\n\n## Versioning\n\nThis is API **v1**. Breaking changes will ship under `/v2/` with at least 6 months overlap. Non-breaking additions (new fields, new types) are added in-place. `GET /v1/health` (liveness, no auth) is intentionally outside this generated contract.\n\n## Data-handling scope\n\nThis schema is the authoritative EHR integration contract. API results remain pollable for up to one hour for delivery and webhook recovery. The standalone web/mobile platform is separate and does not keep clinical processing results after delivery — they are queued for deletion when delivered to the user's browser and removed by automatic background cleanup (no fixed time guarantee).","version":"1.0.0"},"paths":{"/v1/process":{"post":{"tags":["Pipeline"],"summary":"Submit a processing job (JSON)","description":"Submit a medical document processing job.\n\n**Six modes:** `document` (default), `transcript`, `dictation`, `chat`, `rename`, `form`.\n\nIn **document mode** (the default), a note is ALWAYS generated; the pipeline is inferred from your inputs:\n- Audio content → transcription (speaker diarization + medication extraction) then generation\n- Text/documents → report generation\n- Audio + text → transcription then generation from both\n- `tardoc: true` → appends TARDOC billing code extraction\n\nIn **transcript mode**, only the transcript is returned — never a note. It accepts\n`tardoc: true` too (transcription + TARDOC codes, no generation).\n\nIn **dictation mode**, one speaker dictates and the plain text is returned — never a note:\nno speaker labels, no audio events, no `transcript_token`, and no add-on.\n\nIn **form mode**, send a blank official form in `form` and get it back filled, in its own\nformat (a PDF form as a filled PDF, a Word form as a filled .docx). Sources are the same\n`content`/`documents` document mode takes; audio is transcribed first and the transcript\nbecomes a source, so `results.transcription` is returned alongside `results.form`. The\nvalues are AI drafts the physician must verify before the form is sent.\n\n**Two ways to submit:**\n- **JSON** (`Content-Type: application/json`): Send text/audio in `content` field.\n- **Multipart** (file upload): Use `POST /v1/process/upload` for raw files.\n\n**Authentication:** Always send `Authorization: Bearer <api_key>`. For `doc_partner_`\nkeys, `X-User-Token` is the physician's pairing code. For `doc_live_` institution\nkeys, it is the physician JWT. It is optional only for quick-evaluation sandbox keys;\npartner-parity sandbox keys require one of the documented fake pairing codes.\n\n**Sandbox:** Use a `doc_test_` key for instant mock responses. Quick-evaluation keys need\nonly the API key; partner-parity keys use the supplied fake pairing codes to exercise\nauthentication, tier gates, and entitlements.","operationId":"submit_pipeline_v1_process_post","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DocumentModeRequest"},{"$ref":"#/components/schemas/TranscriptModeRequest"},{"$ref":"#/components/schemas/DictationModeRequest"},{"$ref":"#/components/schemas/ChatModeRequest"},{"$ref":"#/components/schemas/RenameModeRequest"},{"$ref":"#/components/schemas/FormModeRequest"}],"title":"Body","discriminator":{"propertyName":"mode","mapping":{"document":"#/components/schemas/DocumentModeRequest","transcript":"#/components/schemas/TranscriptModeRequest","dictation":"#/components/schemas/DictationModeRequest","chat":"#/components/schemas/ChatModeRequest","rename":"#/components/schemas/RenameModeRequest","form":"#/components/schemas/FormModeRequest"}}}}},"required":true},"responses":{"202":{"description":"Job accepted and queued for processing","headers":{"Idempotent-Replayed":{"description":"Present with value `true` when this response replays an existing job.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineAcceptedResponse"}}}},"400":{"description":"Bad request (DOC_VAL_001/002/003/006/008/009/015)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication failed (DOC_AUTH_001..005)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded (DOC_RATE_001 / DOC_RATE_002)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Processing service unavailable (DOC_SVC_001 / DOC_SRV_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation error (schema / enum / missing field)","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","examples":["DOC_VAL_001"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object"},"description":"Structured field-level validation details"}}}}}},"403":{"description":"Forbidden — billing/subscription/license (DOC_SUB_001, DOC_LIC_001, DOC_BILL_001) or session-only route (DOC_AUTH_006). (DOC_BILL_002 is NOT a 403 — it is a non-fatal partial-fulfillment NOTICE in the 202/poll `billing_notices[]` when tardoc is dropped.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown prompt_id (DOC_VAL_007)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency-Key reused with a different request (DOC_VAL_016)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"File too large (DOC_VAL_004)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/process/upload":{"post":{"tags":["Pipeline"],"summary":"Submit a processing job (file upload)","description":"Upload raw files (audio, PDFs, text) directly — no base64, no preprocessing.\n\n**Audio files** (.mp3, .wav, .ogg, .m4a, .flac, .webm, .aac, .opus, .wma, .amr, .mp4, .3gp, .dss, .dvf) → transcribed.\n**Documents** (.pdf, .docx, .txt, .md) → text extracted automatically.\n**Images** (.jpg, .png, .tiff, .bmp, .webp) → text extracted with OCR.\n**Free text** via the `text` field → appended to extracted document text.\n\nMax 100MB per file, 200MB total.\n\nWith `mode=form`, send the blank form in its own `form` part (PDF AcroForm max 8 MB, or a\nWord form with native controls, .docx/.dotx, max 2 MB) — `files` and `text` stay the sources\nit is filled from. The filled form comes back in `results.form`.\n\n```bash\ncurl -X POST https://api.documenter.ch/v1/process/upload \\\n  -H \"Authorization: Bearer doc_live_YOUR_KEY\" \\\n  -H \"X-User-Token: YOUR_JWT\" \\\n  -F \"tardoc=true\" \\\n  -F \"files=@Consultation.ogg\" \\\n  -F \"files=@lettre_urgences.pdf\" \\\n  -F \"text=Notes additionnelles du médecin\"\n```","operationId":"submit_pipeline_upload_v1_process_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_submit_pipeline_upload_v1_process_upload_post"}}}},"responses":{"202":{"description":"Job accepted and queued for processing","headers":{"Idempotent-Replayed":{"description":"Present with value `true` when this response replays an existing job.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineAcceptedResponse"}}}},"400":{"description":"Bad request (DOC_VAL_001/002/003/006/008/009/015)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication failed (DOC_AUTH_001..005)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"File too large (DOC_VAL_004)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded (DOC_RATE_001 / DOC_RATE_002)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Processing service unavailable (DOC_SVC_001 / DOC_SRV_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation error (schema / enum / missing field)","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","examples":["DOC_VAL_001"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object"},"description":"Structured field-level validation details"}}}}}},"403":{"description":"Forbidden — billing/subscription/license (DOC_SUB_001, DOC_LIC_001, DOC_BILL_001) or session-only route (DOC_AUTH_006). (DOC_BILL_002 is NOT a 403 — it is a non-fatal partial-fulfillment NOTICE in the 202/poll `billing_notices[]` when tardoc is dropped.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown prompt_id (DOC_VAL_007)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency-Key reused with a different request (DOC_VAL_016)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/process/{job_id}":{"get":{"tags":["Pipeline"],"summary":"Poll for job results","description":"Check the status of a submitted job and retrieve results when complete.\n\nResults expire after 1 hour. Fetch them promptly or configure a webhook.\n\nPolling a job you own does not spend the per-minute request budget; it is instead throttled to about one poll per 2 seconds per (key, physician, job), so treat that as a floor on your poll interval rather than a quota.\n\nA `503` means the result could not be fetched right now — retryable, honor `Retry-After: 30`; the `410` is reserved for a result that is authoritatively gone (TTL expired, or the processing service confirmed the loss).\n\n**Statuses:** `accepted` → `processing` → `completed` | `error` | `cancelled`","operationId":"get_pipeline_status_v1_process__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"title":"Job Id"}}],"responses":{"200":{"description":"Job status (processing or completed with results)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineStatusResponse"}}}},"404":{"description":"Job not found or not owned by this key (DOC_JOB_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"Result gone — the 1h TTL expired, or the processing service confirmed the loss (DOC_JOB_002). A merely unreachable result returns a retryable 503 instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Result temporarily unfetchable — retryable (DOC_SVC_001); honor Retry-After: 30","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Authentication failed (DOC_AUTH_001..005)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden — billing/subscription/license (DOC_SUB_001, DOC_LIC_001, DOC_BILL_001) or session-only route (DOC_AUTH_006). (DOC_BILL_002 is NOT a 403 — it is a non-fatal partial-fulfillment NOTICE in the 202/poll `billing_notices[]` when tardoc is dropped.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded (DOC_RATE_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"tags":["Pipeline"],"summary":"Cancel a job","description":"Cancel an in-progress job. Completed or already-cancelled jobs return their current status.","operationId":"cancel_pipeline_v1_process__job_id__delete","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Authentication failed (DOC_AUTH_001..005)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden — billing/subscription/license (DOC_SUB_001, DOC_LIC_001, DOC_BILL_001) or session-only route (DOC_AUTH_006). (DOC_BILL_002 is NOT a 403 — it is a non-fatal partial-fulfillment NOTICE in the 202/poll `billing_notices[]` when tardoc is dropped.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded (DOC_RATE_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Job not found (DOC_JOB_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/prompts":{"get":{"tags":["Pipeline"],"summary":"List available prompts","description":"List prompt templates accessible to this API key. Returns the union of three tiers:\n\n1. **System defaults** — curated by Documenter, always visible.\n2. **Institution prompts** — owned by your organization (the DOCumenter account that owns this API key). Create/edit them at documenter.ch when signed in as the org account.\n3. **Physician's personal library** — only when the request's X-User-Token resolves to a linked DOCumenter physician account. Partner mode: the pairing code maps directly. Institution mode: the EHR JWT `sub` must first be linked to that physician account.\n\nEach item lists the sections it produces with your organization's field map already applied, and `is_default` marks the instruction used when `prompt_id` is omitted.","operationId":"list_prompts_for_api_v1_prompts_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/PromptListItem"},"type":"array","title":"Response List Prompts For Api V1 Prompts Get"}}}},"401":{"description":"Authentication failed (DOC_AUTH_001..005)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden — billing/subscription/license (DOC_SUB_001, DOC_LIC_001, DOC_BILL_001) or session-only route (DOC_AUTH_006). (DOC_BILL_002 is NOT a 403 — it is a non-fatal partial-fulfillment NOTICE in the 202/poll `billing_notices[]` when tardoc is dropped.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded (DOC_RATE_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entitlements":{"get":{"tags":["Pipeline"],"summary":"Get the physician's plan tier + capabilities","description":"Return the resolved subject's subscription tier, raw plan features, and the derived per-capability flags an EHR uses to gray out unavailable options up front.\n\n**Subject:** the SAME billed subject the submit gate uses. Partner mode → the physician the pairing code (`X-User-Token`) resolves to (per-physician). Institution mode → the API key owner (the billing tier resolves from the owner). Quick-evaluation sandbox keys return all capabilities as true. Partner-parity sandbox keys return the tier selected by the documented fake pairing code, so the complete UI-gating logic can be tested before go-live.\n\nThe per-request `billing_notices[]` remain the authoritative runtime source of truth; this read is a proactive convenience.","operationId":"get_entitlements_v1_entitlements_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementsResponse"}}}},"401":{"description":"Authentication failed (DOC_AUTH_001..005)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden — no active subscription (DOC_SUB_001, DOC_BILL_001) or session-only route (DOC_AUTH_006). This route is exempt from the licence cap, so it never returns that cap's error — it is how a capped physician discovers the cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded (DOC_RATE_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/section-keys":{"get":{"tags":["Pipeline"],"summary":"The canonical section-key catalogue","description":"The stable machine keys that appear in `sections[].key` when you request\n`output_format: \"json\"` — the contract your EHR field mapping is built against.\n\n**Keys are append-only.** A published key is never renamed or removed; retirement is\n`deprecated: true`, which keeps the key published and still assigned so existing\nintegrations keep working.\n\nPoll `catalogue_version` to detect that the vocabulary or the heading-matching rules\nhave changed. It is a change signal only: a request cannot select a version, and\nresults do not carry one.\n\nAuth is the same as every other `/v1` endpoint: `Authorization: Bearer <api_key>`,\nplus `X-User-Token` for `doc_live_`/`doc_partner_` keys (optional for `doc_test_`\nsandbox keys). The catalogue is global — the physician token never scopes it, so the\nresponse is identical for every token a given key can present.","operationId":"list_section_keys_v1_section_keys_get","responses":{"200":{"description":"The catalogue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SectionKeysResponse"}}}},"401":{"description":"Authentication failed (DOC_AUTH_001..005)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden — billing/subscription/license (DOC_SUB_001, DOC_LIC_001, DOC_BILL_001) or session-only route (DOC_AUTH_006). (DOC_BILL_002 is NOT a 403 — it is a non-fatal partial-fulfillment NOTICE in the 202/poll `billing_notices[]` when tardoc is dropped.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded (DOC_RATE_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Catalogue temporarily unavailable (DOC_SRV_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/partner/signup-intents":{"post":{"tags":["Partner signup"],"summary":"Create Signup Intent","description":"Prepare a doctor signup. An open intent for the same email returns 200 with a rotated link.\n\nA sandbox key gets an already-completed intent carrying the tier-3 sandbox code instead.","operationId":"create_signup_intent_v1_partner_signup_intents_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupIntentCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupIntentCreated"}}}},"422":{"description":"Validation error (schema / enum / missing field)","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","examples":["DOC_VAL_001"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object"},"description":"Structured field-level validation details"}}}}}},"200":{"description":"An open intent for the same email: same intent_id, rotated signup_url (sandbox: the existing completed intent)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupIntentCreated"}}}},"401":{"description":"A partner API key is required (DOC_AUTH_001 / DOC_AUTH_002)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Organisation not enabled for signup intents (DOC_SIGNUP_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"A doctor is completing this signup, so it cannot be rotated (DOC_SIGNUP_006); sandbox key with no sandbox pairing code available (DOC_SIGNUP_008)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded, 10 requests/minute per key (DOC_RATE_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Intent busy, honor Retry-After: 5 (DOC_SVC_001); temporarily unavailable (DOC_SRV_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/partner/signup-intents/{intent_id}":{"get":{"tags":["Partner signup"],"summary":"Get Signup Intent","description":"Intent status; `pairing_code` only within 1 hour of completion.","operationId":"get_signup_intent_v1_partner_signup_intents__intent_id__get","parameters":[{"name":"intent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Intent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupIntentStatus"}}}},"422":{"description":"Validation error (schema / enum / missing field)","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","examples":["DOC_VAL_001"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object"},"description":"Structured field-level validation details"}}}}}},"401":{"description":"A partner API key is required (DOC_AUTH_001 / DOC_AUTH_002)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Intent not found, owned by another organisation, or created with a key of the other mode (DOC_SIGNUP_002)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded, 10 requests/minute per key (DOC_RATE_001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ApiError":{"properties":{"error":{"type":"string","enum":["DOC_AUTH_001","DOC_AUTH_002","DOC_AUTH_003","DOC_AUTH_004","DOC_AUTH_005","DOC_AUTH_006","DOC_AUTH_007","DOC_BILL_001","DOC_FORM_006","DOC_JOB_001","DOC_JOB_002","DOC_LIC_001","DOC_RATE_001","DOC_RATE_002","DOC_SIGNUP_001","DOC_SIGNUP_002","DOC_SIGNUP_006","DOC_SIGNUP_008","DOC_SRV_001","DOC_SUB_001","DOC_SVC_001","DOC_SVC_002","DOC_VAL_001","DOC_VAL_002","DOC_VAL_003","DOC_VAL_004","DOC_VAL_006","DOC_VAL_007","DOC_VAL_008","DOC_VAL_009","DOC_VAL_015","DOC_VAL_016"],"title":"Error","description":"Machine-readable error code (e.g., DOC_AUTH_001, DOC_VAL_002)."},"message":{"type":"string","title":"Message","description":"Human-readable error description"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Bounded machine-readable cause of a terminal job error (e.g. audio_truncated, upstream_timeout). The value set is additive-only. Absent when the cause is unknown."}},"type":"object","required":["error","message"],"title":"ApiError","description":"Standard error response. All 4xx/5xx responses use this format."},"BillingNotice":{"properties":{"code":{"type":"string","title":"Code","description":"Notice code (e.g., DOC_BILL_002)"},"step":{"type":"string","title":"Step","description":"The dropped step (e.g., 'tardoc')"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"required_tier":{"type":"string","title":"Required Tier","description":"Subscription tier that would include the step"}},"type":"object","required":["code","step","message","required_tier"],"title":"BillingNotice","description":"A non-fatal notice that a requested step was dropped for lack of entitlement.\n\nPresent (in `billing_notices[]`) when a request asked for a step the billed\nsubject is not entitled to, but the rest of the pipeline still ran (partial\nfulfillment). Currently only `DOC_BILL_002` (tardoc dropped — requires an\nia-ssistant-pro subscription). Contrast `DOC_BILL_001`, a hard 403."},"Body_submit_pipeline_upload_v1_process_upload_post":{"properties":{"files":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Files","description":"Audio, PDF, DOCX, image, and/or text files. Optional — if you only have text, send the `text` field without any files.","default":[]},"mode":{"type":"string","enum":["document","transcript","dictation","rename","form"],"title":"Mode","description":"Processing mode: document (default), transcript, dictation, rename, or form. Chat is JSON-only; POST a messages array to /v1/process.","default":"document"},"form":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"Form","description":"The blank form to fill — required with `mode=form`, ignored otherwise. A PDF form (AcroForm, max 8 MB) or a Word form with native controls (.docx/.dotx, max 2 MB). Distinct from `files`, which carry the sources."},"tardoc":{"type":"boolean","title":"Tardoc","description":"Extract TARDOC billing codes (document and transcript modes)","default":false},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Optional free text (clinical notes, additional context)"},"transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transcript","description":"Document mode: a transcript /v1 returned, unchanged, sent with its `transcript_token` so it counts as the consultation (any plan) next to `text` and `files`."},"transcript_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transcript Token","description":"The `transcript_token` returned with `transcript`."},"prompt_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Id","description":"Prompt template UUID (optional, defaults to clinical notes)"},"length":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Length","description":"Length variant for the prompt family (concis | equilibre | exhaustif). Optional. Only valid when the chosen prompt belongs to a length family."},"output_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Format","description":"Output format: html (default), text, markdown, json, docx (base64 bytes). Document mode only — transcript mode rejects it with 422."},"locale":{"type":"string","title":"Locale","description":"Locale: fr, de, it, en","default":"fr"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url","description":"HTTPS callback URL for result delivery"}},"type":"object","title":"Body_submit_pipeline_upload_v1_process_upload_post"},"ChatMessage":{"properties":{"role":{"type":"string","enum":["user","assistant"],"title":"Role","description":"Message role: 'user' or 'assistant' only."},"content":{"type":"string","title":"Content","description":"Message text content"}},"type":"object","required":["role","content"],"title":"ChatMessage","description":"A single message in a chat conversation.\n\nOnly `user` and `assistant` are accepted — DOCumenter applies its own\nmedical system prompt, partners cannot override it. Submitting a\nmessage with `role: \"system\"` returns 422 at the API boundary."},"ChatModeRequest":{"properties":{"mode":{"type":"string","const":"chat","title":"Mode","description":"Processing mode","default":"chat"},"messages":{"items":{"$ref":"#/components/schemas/ChatMessage"},"type":"array","minItems":1,"title":"Messages","description":"Conversation messages."},"locale":{"type":"string","pattern":"^(fr|de|it|en)$","title":"Locale","description":"Locale. Determines report language and TARDOC code descriptions. Values: fr, de, it, en.","default":"fr"},"webhook_url":{"anyOf":[{"type":"string","pattern":"^https://"},{"type":"null"}],"title":"Webhook Url","description":"HTTPS callback URL. We POST the full result JSON on completion with X-Webhook-Signature (hex HMAC-SHA256 over `{X-Webhook-Timestamp}.{raw_body}`), X-Webhook-Timestamp (Unix epoch seconds), X-Webhook-Signature-Version (`v1`), X-Job-Id, and X-Webhook-Delivery-ID (stable across retries of one payload; a job's terminal DOC_JOB_002 error callback carries its own id) headers. Any 2xx acknowledges delivery. Retried up to 3 times, roughly 30 seconds apart. Redirects are not followed. Must resolve to a public IP."}},"type":"object","required":["messages"],"title":"ChatModeRequest","description":"Medical AI assistant for clinical questions."},"ChatResult":{"properties":{"content":{"type":"string","title":"Content","description":"Assistant response text"},"tokens_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens In","description":"Input tokens consumed"},"tokens_out":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens Out","description":"Output tokens generated"}},"type":"object","required":["content"],"title":"ChatResult"},"DictationModeRequest":{"properties":{"mode":{"type":"string","const":"dictation","title":"Mode","description":"Processing mode","default":"dictation"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Base64-encoded audio. For raw file uploads, use POST /v1/process/upload instead."},"content_type":{"type":"string","const":"audio","title":"Content Type","description":"Always 'audio' — dictation mode transcribes the audio content.","default":"audio"},"locale":{"type":"string","pattern":"^(fr|de|it|en)$","title":"Locale","description":"Locale. Determines report language and TARDOC code descriptions. Values: fr, de, it, en.","default":"fr"},"webhook_url":{"anyOf":[{"type":"string","pattern":"^https://"},{"type":"null"}],"title":"Webhook Url","description":"HTTPS callback URL. We POST the full result JSON on completion with X-Webhook-Signature (hex HMAC-SHA256 over `{X-Webhook-Timestamp}.{raw_body}`), X-Webhook-Timestamp (Unix epoch seconds), X-Webhook-Signature-Version (`v1`), X-Job-Id, and X-Webhook-Delivery-ID (stable across retries of one payload; a job's terminal DOC_JOB_002 error callback carries its own id) headers. Any 2xx acknowledges delivery. Retried up to 3 times, roughly 30 seconds apart. Redirects are not followed. Must resolve to a public IP."}},"additionalProperties":false,"type":"object","title":"DictationModeRequest","description":"Dictation: one speaker dictating, plain text out. Never generates a note.\n\nAudio-only, with no add-on: the result has no speaker labels or audio events.\nFor raw audio uploads, use POST /v1/process/upload with `mode=dictation`."},"DocumentAttachment":{"properties":{"type":{"type":"string","enum":["pdf","text","image"],"title":"Type","description":"Document type"},"name":{"type":"string","title":"Name","description":"Original filename"},"data":{"type":"string","title":"Data","description":"Base64-encoded file content"}},"type":"object","required":["type","name","data"],"title":"DocumentAttachment","description":"A document attachment (base64-encoded)."},"DocumentModeRequest":{"properties":{"mode":{"type":"string","const":"document","title":"Mode","description":"Processing mode","default":"document"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Text content (clinical notes) or base64-encoded audio. Set content_type to 'audio' when sending base64 audio. For raw file uploads, use POST /v1/process/upload instead."},"content_type":{"anyOf":[{"type":"string","enum":["text","audio"]},{"type":"null"}],"title":"Content Type","description":"Type of content: 'text' (default) or 'audio' (base64-encoded). When 'audio', the content is transcribed instead of used for generation."},"documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentAttachment"},"type":"array"},{"type":"null"}],"title":"Documents","description":"Document attachments (base64-encoded). Text is extracted from PDFs automatically."},"transcript_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transcript Token","description":"The `transcript_token` returned with a transcript. Send it with that transcript, unchanged, as `content` to generate another document from it: the text then counts as a transcript, not a note, so every plan can use it. An edited text or a token issued to another physician is ignored and the text is a note."},"prompt_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Id","description":"Prompt template UUID for report generation. Optional — omit to use the platform default (Note de suite - Cabinet, equilibre length). List prompts with GET /v1/prompts."},"length":{"anyOf":[{"type":"string","enum":["concis","equilibre","exhaustif"]},{"type":"null"}],"title":"Length","description":"Length variant for the prompt. Three values: `concis` (key facts only, shortest), `equilibre` (balanced — recommended; what doctors pick by default), `exhaustif` (maximum detail, longest — use for LAA/AI/expertise reports). Only valid when the chosen prompt has a `lengths` family on GET /v1/prompts. Omit to use the recommended `equilibre` variant. Passing `length` on a prompt without a family returns DOC_VAL_008."},"output_format":{"type":"string","enum":["text","markdown","html","json","docx"],"title":"Output Format","description":"Output format for generated reports. 'json' returns structured FHIR-mappable data. 'docx' returns a plain styled Word document (no template) as base64 bytes in `content`.","default":"html"},"tardoc":{"type":"boolean","title":"Tardoc","description":"When true, extract TARDOC billing codes from the consultation. Returns applicable codes with tax point values and quantities.","default":false},"locale":{"type":"string","pattern":"^(fr|de|it|en)$","title":"Locale","description":"Locale. Determines report language and TARDOC code descriptions. Values: fr, de, it, en.","default":"fr"},"webhook_url":{"anyOf":[{"type":"string","pattern":"^https://"},{"type":"null"}],"title":"Webhook Url","description":"HTTPS callback URL. We POST the full result JSON on completion with X-Webhook-Signature (hex HMAC-SHA256 over `{X-Webhook-Timestamp}.{raw_body}`), X-Webhook-Timestamp (Unix epoch seconds), X-Webhook-Signature-Version (`v1`), X-Job-Id, and X-Webhook-Delivery-ID (stable across retries of one payload; a job's terminal DOC_JOB_002 error callback carries its own id) headers. Any 2xx acknowledges delivery. Retried up to 3 times, roughly 30 seconds apart. Redirects are not followed. Must resolve to a public IP."}},"type":"object","title":"DocumentModeRequest","description":"Process medical documents: transcribe audio, generate reports, extract billing codes.\n\nDocument mode ALWAYS generates a note; the pipeline is inferred from your inputs:\n- **Audio content** → transcription + generation (a note from the transcript)\n- **Text/document content** → report generation\n- **Audio + text** → transcription, then generation using both\n- **`tardoc: true`** → appends TARDOC billing code extraction\n\nTo skip the note, use `mode: transcript` (which also accepts `tardoc: true`).\nNo need to specify steps otherwise."},"EntitlementCapabilities":{"properties":{"transcription":{"type":"boolean","title":"Transcription","description":"May run transcription (any tier)."},"generation_from_transcript":{"type":"boolean","title":"Generation From Transcript","description":"May generate a note from the request's own transcript (any tier)."},"generation_from_documents":{"type":"boolean","title":"Generation From Documents","description":"May generate grounded in uploaded documents/notes (ia-ssistant+)."},"tardoc":{"type":"boolean","title":"Tardoc","description":"May extract TARDOC billing codes (ia-ssistant-pro)."},"form_fill":{"type":"boolean","title":"Form Fill","description":"May fill official forms with `mode: \"form\"` (ia-ssistant+)."}},"type":"object","required":["transcription","generation_from_transcript","generation_from_documents","tardoc","form_fill"],"title":"EntitlementCapabilities","description":"What a subject's plan allows, derived from tier + features."},"EntitlementsResponse":{"properties":{"tier":{"type":"string","title":"Tier","description":"Plan tier: scribe | ia-ssistant | ia-ssistant-pro"},"features":{"items":{"type":"string"},"type":"array","title":"Features","description":"The plan's raw feature list."},"capabilities":{"$ref":"#/components/schemas/EntitlementCapabilities"}},"type":"object","required":["tier","features","capabilities"],"title":"EntitlementsResponse","description":"GET /v1/entitlements — the resolved subject's plan tier + capabilities.\n\nProactive discovery: an EHR calls this once per physician to gray out\nunavailable options up front. The per-request `billing_notices[]` remain the\nauthoritative runtime source of truth."},"FormAttachment":{"properties":{"filename":{"type":"string","title":"Filename","description":"Original filename. Advisory only — the form type is admitted from the file's own bytes, never from its extension."},"content_base64":{"type":"string","title":"Content Base64","description":"Base64-encoded form bytes. PDF (max 8 MB) or DOCX/DOTX (max 2 MB)."}},"additionalProperties":false,"type":"object","required":["filename","content_base64"],"title":"FormAttachment","description":"The blank form to fill: a PDF AcroForm, or a Word form with native controls."},"FormDocument":{"properties":{"content_base64":{"type":"string","title":"Content Base64","description":"Base64-encoded filled form — decode before writing to a file."},"format":{"type":"string","enum":["pdf","docx"],"title":"Format","description":"Output format: follows the submitted form."},"media_type":{"type":"string","title":"Media Type","description":"Media type of the decoded bytes."},"sha256":{"type":"string","title":"Sha256","description":"SHA-256 hex digest of the decoded bytes."}},"additionalProperties":false,"type":"object","required":["content_base64","format","media_type","sha256"],"title":"FormDocument","description":"The filled form, in the source form's own format."},"FormField":{"properties":{"key":{"type":"string","title":"Key","description":"Stable field key, deterministic for a given form file."},"question":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question","description":"The question the model restated for this field, when it did."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"The form's own label for the field."},"section":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section","description":"The form section the field belongs to."},"page":{"type":"integer","title":"Page","description":"1-based page of the source form."},"type":{"type":"string","title":"Type","description":"Field type (text, date, number, checkbox, choice, signature, …)."},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options","description":"Accepted values for a choice field; null otherwise."},"value":{"type":"string","title":"Value","description":"The value written into the field — an AI draft the physician must verify. Empty when the field was not answered, or when it is the physician's to fill (signatures, attachments, the treating doctor's identity)."}},"additionalProperties":false,"type":"object","required":["key","page","type","value"],"title":"FormField","description":"One field of the form, in form order, with the value that was written into it."},"FormModeRequest":{"properties":{"mode":{"type":"string","const":"form","title":"Mode","description":"Processing mode","default":"form"},"form":{"$ref":"#/components/schemas/FormAttachment","description":"The blank form to fill."},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Text content (clinical notes) or base64-encoded audio. Set content_type to 'audio' when sending base64 audio. For raw file uploads, use POST /v1/process/upload instead."},"content_type":{"anyOf":[{"type":"string","enum":["text","audio"]},{"type":"null"}],"title":"Content Type","description":"Type of content: 'text' (default) or 'audio' (base64-encoded). When 'audio', the content is transcribed and the transcript becomes a source."},"documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentAttachment"},"type":"array"},{"type":"null"}],"title":"Documents","description":"Document attachments (base64-encoded) used as sources. Text is extracted from PDFs automatically."},"locale":{"type":"string","pattern":"^(fr|de|it|en)$","title":"Locale","description":"Locale. Determines report language and TARDOC code descriptions. Values: fr, de, it, en.","default":"fr"},"webhook_url":{"anyOf":[{"type":"string","pattern":"^https://"},{"type":"null"}],"title":"Webhook Url","description":"HTTPS callback URL. We POST the full result JSON on completion with X-Webhook-Signature (hex HMAC-SHA256 over `{X-Webhook-Timestamp}.{raw_body}`), X-Webhook-Timestamp (Unix epoch seconds), X-Webhook-Signature-Version (`v1`), X-Job-Id, and X-Webhook-Delivery-ID (stable across retries of one payload; a job's terminal DOC_JOB_002 error callback carries its own id) headers. Any 2xx acknowledges delivery. Retried up to 3 times, roughly 30 seconds apart. Redirects are not followed. Must resolve to a public IP."}},"additionalProperties":false,"type":"object","required":["form"],"title":"FormModeRequest","description":"Fill an official form from your consultation: send the blank form, get it back filled.\n\nThe form comes back in ITS OWN format — a PDF AcroForm as a filled PDF, a Word\nform as a filled .docx with its native controls. Sources are the same ones\ndocument mode takes: `content` (notes, or base64 audio with\n`content_type: \"audio\"`) and `documents`. Audio is transcribed first and the\ntranscript becomes a source, so `results.transcription` is returned too.\n\nEvery value is an AI draft the physician must verify before the form is sent;\nthe treating doctor's own identity (GLN/RCC/address) is always left blank. There\nis no note to shape here, so `prompt_id`, `length`, `output_format` and `tardoc`\nare rejected (422)."},"FormResult":{"properties":{"document":{"$ref":"#/components/schemas/FormDocument","description":"The filled form."},"fields":{"items":{"$ref":"#/components/schemas/FormField"},"type":"array","title":"Fields","description":"Every field of the form, in form order."},"summary":{"$ref":"#/components/schemas/FormSummary","description":"Bounded counts for the fill."}},"additionalProperties":false,"type":"object","required":["document","fields","summary"],"title":"FormResult"},"FormSummary":{"properties":{"field_count":{"type":"integer","title":"Field Count","description":"Fields the form declares."},"answered_count":{"type":"integer","title":"Answered Count","description":"Fields that received a non-empty value."},"failed_page_count":{"type":"integer","title":"Failed Page Count","description":"Pages whose answering failed; their fields are blank."},"unplaced_field_count":{"type":"integer","title":"Unplaced Field Count","description":"Fields whose value did not fit its control and was moved to an annex."},"continuation_page_count":{"type":"integer","title":"Continuation Page Count","description":"Pages appended to carry overflow text."}},"additionalProperties":false,"type":"object","required":["field_count","answered_count","failed_page_count","unplaced_field_count","continuation_page_count"],"title":"FormSummary","description":"Bounded counts describing what the fill achieved."},"GenerationResult":{"properties":{"content":{"type":"string","title":"Content","description":"Generated medical report in the requested output_format. For 'docx', base64-encoded .docx bytes — decode before writing to a file."},"format":{"type":"string","title":"Format","description":"Output format used","default":"html"},"tokens_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens In","description":"Input tokens consumed"},"tokens_out":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens Out","description":"Output tokens generated"}},"type":"object","required":["content"],"title":"GenerationResult"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PipelineAcceptedResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Unique job identifier for polling"},"status":{"type":"string","title":"Status","description":"Submit status: 'processing' for every new job, live or sandbox (a sandbox job turns terminal on its first poll). An idempotency replay returns the stored job's current status, e.g. 'completed'. Never 'accepted'.","default":"processing","examples":["processing"]},"mode":{"type":"string","title":"Mode","description":"Processing mode used"},"steps":{"items":{"type":"string"},"type":"array","title":"Steps","description":"Inferred execution steps"},"poll_url":{"type":"string","title":"Poll Url","description":"Relative path to poll for status/results: GET /v1/process/{job_id}."},"estimated_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Seconds","description":"Rough estimate of total processing time in seconds. 1 for sandbox jobs (the result is ready on the next poll); absent on an idempotency replay."},"billing_notices":{"items":{"$ref":"#/components/schemas/BillingNotice"},"type":"array","title":"Billing Notices","description":"Non-fatal notices for steps dropped due to entitlement (e.g., DOC_BILL_002 when tardoc was requested without an ia-ssistant-pro plan). Empty when every requested step was dispatched."}},"type":"object","required":["job_id","mode","steps","poll_url"],"title":"PipelineAcceptedResponse","description":"202 Accepted — job submitted and queued."},"PipelineResults":{"properties":{"transcription":{"anyOf":[{"$ref":"#/components/schemas/TranscriptionResult"},{"type":"null"}]},"generation":{"anyOf":[{"$ref":"#/components/schemas/GenerationResult"},{"type":"null"}]},"tardoc":{"anyOf":[{"$ref":"#/components/schemas/TardocResult"},{"type":"null"}]},"chat":{"anyOf":[{"$ref":"#/components/schemas/ChatResult"},{"type":"null"}]},"renaming":{"anyOf":[{"$ref":"#/components/schemas/RenamingResult"},{"type":"null"}]},"form":{"anyOf":[{"$ref":"#/components/schemas/FormResult"},{"type":"null"}]}},"type":"object","title":"PipelineResults","description":"Results keyed by step type. Only completed steps are present."},"PipelineStatusResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"The polled job identifier."},"status":{"type":"string","enum":["accepted","processing","completed","error","cancelled"],"title":"Status","description":"Job lifecycle: accepted → processing → completed | error | cancelled"},"mode":{"type":"string","title":"Mode","description":"Processing mode"},"steps":{"items":{"type":"string"},"type":"array","title":"Steps","description":"Execution steps"},"current_step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Step","description":"The step currently executing (e.g., 'transcription', 'generation', 'tardoc'). Null once the job is terminal."},"estimated_seconds_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Seconds Remaining","description":"Reserved — currently always null."},"results":{"anyOf":[{"$ref":"#/components/schemas/PipelineResults"},{"type":"null"}],"description":"Results keyed by step type. Only present when status is 'completed'."},"error":{"anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}],"description":"Error details. Only present when status is 'error'."},"billing_notices":{"items":{"$ref":"#/components/schemas/BillingNotice"},"type":"array","title":"Billing Notices","description":"Non-fatal notices for steps dropped due to entitlement (e.g., DOC_BILL_002 when tardoc was requested without an ia-ssistant-pro plan). Empty when every requested step was dispatched. Mirrored in the webhook payload."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the job was submitted (UTC)."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the job completed successfully (UTC). Null for processing, error, or cancelled jobs."}},"type":"object","required":["job_id","status","mode","steps","created_at"],"title":"PipelineStatusResponse","description":"GET /v1/process/{id} — job status + results when complete."},"PromptListItem":{"properties":{"id":{"type":"string","title":"Id","description":"UUID of the default variant (or the lone prompt if no family)."},"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"visibility":{"type":"string","title":"Visibility"},"lengths":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Lengths","description":"Available length variants for this family (e.g., ['concis','equilibre','exhaustif']). Pass one as `length` at submit-time. Absent for prompts without a length family."},"default_length":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Length","description":"The variant `id` corresponds to AND the recommended starting point for new integrations. Skipping `length` at submit-time uses this. Always `equilibre` when the family has it; otherwise the first variant alphabetically. Absent for prompts without a length family."},"is_default":{"type":"boolean","title":"Is Default","description":"True for the instruction used when `prompt_id` is omitted on `POST /v1/process`. Exactly one item carries it. For production stability, still pass an explicit `prompt_id` — the platform default may change.","default":false},"is_favorite":{"type":"boolean","title":"Is Favorite","description":"True when the physician starred this instruction on documenter.ch, so it is listed first there. Always false without a physician (no `X-User-Token`).","default":false},"sections":{"anyOf":[{"items":{"$ref":"#/components/schemas/PromptSectionInfo"},"type":"array"},{"type":"null"}],"title":"Sections","description":"The sections this instruction produces, in the order it declares them, with your organisation's current field map already applied to `key`. The document title is always the first entry (`titre`). `null` when the instruction does not declare its sections up front — free-text instructions, instructions whose structure the model derives at generation time, and sandbox instructions (a sandbox evaluation returns its fixture's own sections). For a length family, these are the sections of the variant `id` points at: a `concis` variant typically declares fewer sections than `exhaustif`, so re-read this after switching `length`."}},"type":"object","required":["id","title","visibility"],"title":"PromptListItem","description":"Available prompt template for API users.\n\nPrompts that come in length variants (short/balanced/long) are grouped:\na single item is returned per family, with `id` pointing at the default\nvariant and `lengths` listing what's actually available. Singletons (no\nvariants) omit the `lengths` and `default_length` fields entirely."},"PromptSectionInfo":{"properties":{"canonical_key":{"type":"string","title":"Canonical Key","description":"DOCumenter's own key for this section, from the published catalogue (`GET /v1/section-keys`). Stable regardless of your field map."},"title":{"type":"string","title":"Title","description":"The heading the instruction declares for this section. The generated report normally carries it verbatim; it is what arrives in `results.generation.sections[].title`."},"key":{"type":"string","title":"Key","description":"The key this section arrives under in `results.generation.sections[].key`: your organisation's `ehr_key` when the field map covers `canonical_key`, otherwise `canonical_key` itself. Several entries may share one `key` — a field map may point several canonical keys at the same EHR field, and their contents are then appended under it in report order. They are listed separately here so you can see which sections merge."},"presence":{"type":"string","title":"Presence","description":"What the instruction asks for when the section has no sourced data: `required` (must appear), `omit_if_empty` (dropped), `marker_if_empty` (kept with a placeholder)."}},"type":"object","required":["canonical_key","title","key","presence"],"title":"PromptSectionInfo","description":"One section an instruction produces, keyed as the caller will receive it."},"RenameModeRequest":{"properties":{"mode":{"type":"string","const":"rename","title":"Mode","description":"Processing mode","default":"rename"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Document text or extracted content to analyze."},"documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentAttachment"},"type":"array"},{"type":"null"}],"title":"Documents","description":"Document attachments (base64-encoded) as alternative to content."},"locale":{"type":"string","pattern":"^(fr|de|it|en)$","title":"Locale","description":"Locale. Determines report language and TARDOC code descriptions. Values: fr, de, it, en.","default":"fr"},"webhook_url":{"anyOf":[{"type":"string","pattern":"^https://"},{"type":"null"}],"title":"Webhook Url","description":"HTTPS callback URL. We POST the full result JSON on completion with X-Webhook-Signature (hex HMAC-SHA256 over `{X-Webhook-Timestamp}.{raw_body}`), X-Webhook-Timestamp (Unix epoch seconds), X-Webhook-Signature-Version (`v1`), X-Job-Id, and X-Webhook-Delivery-ID (stable across retries of one payload; a job's terminal DOC_JOB_002 error callback carries its own id) headers. Any 2xx acknowledges delivery. Retried up to 3 times, roughly 30 seconds apart. Redirects are not followed. Must resolve to a public IP."}},"type":"object","title":"RenameModeRequest","description":"Intelligent document renaming: extract patient name, date, type → structured filename."},"RenamingFormat":{"properties":{"field_order":{"items":{"type":"string"},"type":"array","title":"Field Order","description":"Ordered filename field names"},"separators":{"items":{"type":"string"},"type":"array","title":"Separators","description":"Separator inserted between consecutive fields"},"source":{"type":"string","enum":["key","user","default"],"title":"Source","description":"Where the convention came from: the API key, the doctor's own preference, or the platform default."}},"type":"object","required":["field_order","separators","source"],"title":"RenamingFormat","description":"The naming convention this job actually ran under (#430)."},"RenamingResult":{"properties":{"suggestions":{"items":{"$ref":"#/components/schemas/RenamingSuggestion"},"type":"array","title":"Suggestions","description":"Renaming suggestions"},"format":{"$ref":"#/components/schemas/RenamingFormat","description":"Naming convention applied to these suggestions"}},"type":"object","required":["suggestions","format"],"title":"RenamingResult"},"RenamingSuggestion":{"properties":{"original":{"type":"string","title":"Original","description":"Original filename"},"suggested":{"type":"string","title":"Suggested","description":"Suggested structured filename"},"fields":{"$ref":"#/components/schemas/RenamingSuggestionFields","description":"Extracted metadata fields"}},"type":"object","required":["original","suggested","fields"],"title":"RenamingSuggestion"},"RenamingSuggestionFields":{"properties":{"surname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Surname"},"firstname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Firstname"},"birthdate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birthdate"},"docdate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Docdate"},"doctype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doctype"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"type_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type Detail","description":"Specialty/precision of the document type, on its own (e.g. type \"Imagerie\" with detail \"CT de la hanche\")"},"type_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type Key","description":"Canonical document-type key"},"doctor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doctor"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Issuing institution / practice"},"recipient":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Broad class derived from type_key by a fixed table (imaging, laboratory, functional, correspondence, procedure, legal, administrative, prescription, other). Additive-only vocabulary."},"modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality","description":"Imaging modality (RX, CT, IRM, US, PET, SCINTI, MAMMO, DEXA, ANGIO); null unless type_key is imaging_report. Additive-only vocabulary."}},"type":"object","title":"RenamingSuggestionFields"},"SectionKey":{"properties":{"key":{"type":"string","title":"Key","description":"Stable machine key as it appears in `sections[].key`."},"label":{"type":"string","title":"Label","description":"Human-readable name (French), for display only."},"deprecated":{"type":"boolean","title":"Deprecated","description":"Retired for NEW mappings. A deprecated key is still published and still assigned, so existing integrations keep working."}},"type":"object","required":["key","label","deprecated"],"title":"SectionKey","description":"One canonical key an EHR can map a field onto."},"SectionKeysResponse":{"properties":{"catalogue_version":{"type":"integer","title":"Catalogue Version","description":"Monotonic. Increases whenever a published key's label, aliases or deprecation state changes, or the heading-matching rules change."},"keys":{"items":{"$ref":"#/components/schemas/SectionKey"},"type":"array","title":"Keys"}},"type":"object","required":["catalogue_version","keys"],"title":"SectionKeysResponse","description":"The canonical section-key catalogue — the contract for `output_format: \"json\"`.\n\nKeys are append-only: never renamed, never removed. Retirement is `deprecated`.\n`catalogue_version` increases whenever the vocabulary or the heading-matching\nrules change; poll it to detect that mappings may have shifted. It is a change\nsignal only — a request cannot select a version, and results do not carry one."},"SignupIntentCreate":{"properties":{"email":{"type":"string","maxLength":255,"pattern":"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$","title":"Email"},"first_name":{"type":"string","maxLength":100,"minLength":1,"title":"First Name"},"last_name":{"type":"string","maxLength":100,"minLength":1,"title":"Last Name"},"phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Phone"},"specialty":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Specialty"},"address":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Address"},"external_ref":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"External Ref"},"return_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Return Url"}},"type":"object","required":["email","first_name","last_name"],"title":"SignupIntentCreate"},"SignupIntentCreated":{"properties":{"intent_id":{"type":"string","title":"Intent Id"},"status":{"type":"string","enum":["open","completed","delivered"],"title":"Status"},"signup_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signup Url"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"pairing_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pairing Code"}},"type":"object","required":["intent_id","status","expires_at"],"title":"SignupIntentCreated"},"SignupIntentStatus":{"properties":{"intent_id":{"type":"string","title":"Intent Id"},"status":{"type":"string","enum":["open","completed","delivered","expired"],"title":"Status"},"external_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Ref"},"pairing_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pairing Code"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"livemode":{"type":"boolean","title":"Livemode"}},"type":"object","required":["intent_id","status","expires_at","livemode"],"title":"SignupIntentStatus"},"TardocCode":{"properties":{"code":{"type":"string","title":"Code","description":"TARDOC position code, chapter-prefixed (e.g., 'AA.00.0010')"},"description":{"type":"string","title":"Description","description":"Code description in the requested locale"},"tp":{"type":"number","title":"Tp","description":"Tax point value per unit"},"quantity":{"type":"integer","title":"Quantity","description":"Number of units","default":1}},"type":"object","required":["code","description","tp"],"title":"TardocCode"},"TardocDiagnosis":{"properties":{"patient_index":{"type":"integer","title":"Patient Index","description":"1-based position of the patient in the consultation (patients are never named)"},"letter":{"type":"string","title":"Letter","description":"First letter of the ICD-10-GM diagnosis (e.g. 'E')"},"code_range":{"type":"string","title":"Code Range","description":"ICD-10-GM block range containing the diagnosis (e.g. 'E10-E14'); never the leaf code"},"description":{"type":"string","title":"Description","description":"French label of the block (e.g. 'Diabète sucré')"}},"type":"object","required":["patient_index","letter","code_range","description"],"title":"TardocDiagnosis"},"TardocResult":{"properties":{"codes":{"items":{"$ref":"#/components/schemas/TardocCode"},"type":"array","title":"Codes","description":"Applicable TARDOC billing codes"},"total_tp":{"type":"number","title":"Total Tp","description":"Total tax points"},"currency":{"type":"string","title":"Currency","description":"Currency (always CHF)","default":"CHF"},"diagnoses":{"items":{"$ref":"#/components/schemas/TardocDiagnosis"},"type":"array","title":"Diagnoses","description":"Pipeline-derived primary diagnosis per patient (letter + ICD-10-GM block). Empty when none was extracted."}},"type":"object","required":["codes","total_tp"],"title":"TardocResult"},"TranscriptModeRequest":{"properties":{"mode":{"type":"string","const":"transcript","title":"Mode","description":"Processing mode","default":"transcript"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Base64-encoded audio. For raw file uploads, use POST /v1/process/upload instead."},"content_type":{"type":"string","const":"audio","title":"Content Type","description":"Always 'audio' — transcript mode transcribes the audio content.","default":"audio"},"tardoc":{"type":"boolean","title":"Tardoc","description":"When true, extract TARDOC billing codes from the consultation. Returns applicable codes with tax point values and quantities.","default":false},"locale":{"type":"string","pattern":"^(fr|de|it|en)$","title":"Locale","description":"Locale. Determines report language and TARDOC code descriptions. Values: fr, de, it, en.","default":"fr"},"webhook_url":{"anyOf":[{"type":"string","pattern":"^https://"},{"type":"null"}],"title":"Webhook Url","description":"HTTPS callback URL. We POST the full result JSON on completion with X-Webhook-Signature (hex HMAC-SHA256 over `{X-Webhook-Timestamp}.{raw_body}`), X-Webhook-Timestamp (Unix epoch seconds), X-Webhook-Signature-Version (`v1`), X-Job-Id, and X-Webhook-Delivery-ID (stable across retries of one payload; a job's terminal DOC_JOB_002 error callback carries its own id) headers. Any 2xx acknowledges delivery. Retried up to 3 times, roughly 30 seconds apart. Redirects are not followed. Must resolve to a public IP."}},"additionalProperties":false,"type":"object","title":"TranscriptModeRequest","description":"Transcription-only: submit audio, receive the transcript. Never generates a note.\n\nAudio-only by construction, with `tardoc: true` as the one optional add-on.\n`documents`, `prompt_id` and `output_format` only make sense for a generated\nnote and are rejected (422) — use `document` mode for that. For raw audio\nuploads, use POST /v1/process/upload with `mode=transcript`."},"TranscriptionAudioEvent":{"properties":{"start":{"type":"number","title":"Start","description":"Event start time in seconds"},"end":{"type":"number","title":"End","description":"Event end time in seconds"},"label":{"type":"string","title":"Label","description":"Event label: 'Cough' or 'Telephone' (the only two surfaced)."},"prob":{"type":"number","title":"Prob","description":"Detection probability (0.0-1.0)"}},"additionalProperties":false,"type":"object","required":["start","end","label","prob"],"title":"TranscriptionAudioEvent"},"TranscriptionMedication":{"properties":{"name":{"type":"string","title":"Name","description":"Medication name, matched against the Swissmedic database; a dictated drug with no reliable Swissmedic match is returned under its spoken name. Drug classes and matches the pipeline declined are OMITTED from the list rather than returned with an empty name."},"dosage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dosage","description":"Dosage (e.g., '1g'). Always null today — the transcription pipeline does not surface per-medication dosage."},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Frequency","description":"Frequency (e.g., '3x/jour'). Always null today — the transcription pipeline does not surface per-medication frequency."}},"additionalProperties":false,"type":"object","required":["name"],"title":"TranscriptionMedication"},"TranscriptionResult":{"properties":{"text":{"type":"string","title":"Text","description":"Full transcript with speaker labels: '[Medecin] ...\\n[Patient] ...'. In dictation mode, plain text with no speaker labels."},"speakers":{"items":{"$ref":"#/components/schemas/TranscriptionSpeaker"},"type":"array","title":"Speakers","description":"Detected speakers. Always [] in dictation mode."},"medications":{"items":{"$ref":"#/components/schemas/TranscriptionMedication"},"type":"array","title":"Medications","description":"Extracted medications"},"audio_events":{"items":{"$ref":"#/components/schemas/TranscriptionAudioEvent"},"type":"array","title":"Audio Events","description":"Non-speech audio events (PANN). Restricted to two labels: cough and telephone only."},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Audio duration in seconds"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Detected language code (FR, DE, IT, EN). Always null in dictation mode."},"transcript_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transcript Token","description":"Send back with this exact transcript to generate further documents from it on any plan (see `transcript_token` on the submit). No expiry."}},"additionalProperties":false,"type":"object","required":["text","speakers"],"title":"TranscriptionResult"},"TranscriptionSpeaker":{"properties":{"id":{"type":"integer","title":"Id","description":"Speaker ID (1-based)"},"label":{"type":"string","title":"Label","description":"Speaker label: 'Medecin' or 'Patient'"}},"additionalProperties":false,"type":"object","required":["id","label"],"title":"TranscriptionSpeaker"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"API key: doc_live_xxx (institution), doc_partner_xxx (EHR vendor), or doc_test_xxx (sandbox). Partner-parity sandbox requests also require X-User-Token."},"X-User-Token":{"type":"apiKey","in":"header","name":"X-User-Token","description":"Physician identifier. Institution keys: JWT signed with HS256. Partner keys: pairing code (e.g., DOC-A7K2M3P9). Optional only for quick-evaluation sandbox keys; partner-parity sandbox keys require a documented fake pairing code."}}},"security":[{"ApiKeyAuth":[],"X-User-Token":[]},{"ApiKeyAuth":[]}],"servers":[{"url":"https://api.documenter.ch","description":"Production"}]}