{"openapi":"3.1.0","info":{"title":"Braes External Extension REST API","version":"2","description":"Curated governed extension REST partition. Internal Braes API routes are intentionally excluded. Speaks extension contract version 2: pin it with the `braes-contract-version` request header; every success response names the version it was served under in `braes-extension-contract-version`.","x-braes-contract":{"current":"2","requestHeader":"braes-contract-version","responseHeader":"braes-extension-contract-version","idempotencyKeyHeader":"idempotency-key","deprecationPolicy":"Extension contract versions are additive-only within a version; breaking changes mint a successor version and the prior version passes through a deprecated window before retirement. Registration under unknown or retired versions is rejected. See lib/platform/extension-contract.ts.","versions":[{"version":"1","status":"deprecated","successor":"2","deprecatedAt":"2026-07-25T00:00:00Z","surfaces":{"manifestVersion":"1.1.0","webhookEnvelopeVersion":"2026-06-27"}},{"version":"2","status":"current","surfaces":{"manifestVersion":"2.7.0","webhookEnvelopeVersion":"2026-06-27"}}]}},"servers":[{"url":"http://localhost:3000","description":"Development"},{"url":"https://braes.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"schemas":{"ExternalPlatformError":{"type":"object","description":"A refusal from the extension gateway. Branch on `error.code`; `retryable` says whether the same request may succeed later.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable platform error code. New codes may be added within a contract version; treat an unknown code by its category and retryable flag.","x-braes-known-values":["PLATFORM_ACCESS_DENIED","PLATFORM_AGENCY_SCOPE_REQUIRED","PLATFORM_APPROVAL_ALREADY_USED","PLATFORM_APPROVAL_EXPIRED","PLATFORM_APPROVAL_NOT_FOUND","PLATFORM_APPROVAL_REJECTED","PLATFORM_APPROVAL_REQUIRED","PLATFORM_AUDIT_WRITE_FAILED","PLATFORM_AUTHENTICATION_REQUIRED","PLATFORM_CAPABILITY_EXECUTION_FAILED","PLATFORM_CAPABILITY_NOT_ALLOWED","PLATFORM_CAPABILITY_NOT_FOUND","PLATFORM_CONCURRENT_MODIFICATION","PLATFORM_CONFLICT","PLATFORM_CONSENT_REQUIRED","PLATFORM_COST_LIMIT_EXCEEDED","PLATFORM_DESTRUCTIVE_CONFIRMATION_REQUIRED","PLATFORM_DOWNSTREAM_UNAVAILABLE","PLATFORM_EXTENSION_DISABLED","PLATFORM_IDEMPOTENCY_CONFLICT","PLATFORM_INTERNAL_ERROR","PLATFORM_INVALID_CREDENTIAL","PLATFORM_INVALID_IDEMPOTENCY_KEY","PLATFORM_INVALID_INPUT","PLATFORM_INVALID_REQUEST","PLATFORM_ISOLATION_FAILURE","PLATFORM_METERING_WRITE_FAILED","PLATFORM_PHI_MODE_DENIED","PLATFORM_PHI_MODE_REQUIRED","PLATFORM_POLICY_DENIED","PLATFORM_PRICING_UNAVAILABLE","PLATFORM_PSEUDONYM_UNRESOLVED","PLATFORM_QUERY_COLUMN_MISMATCH","PLATFORM_QUERY_EXECUTION_FAILED","PLATFORM_QUERY_NOT_ALLOWED","PLATFORM_QUERY_NOT_FOUND","PLATFORM_QUOTA_EXCEEDED","PLATFORM_RATE_LIMITED","PLATFORM_RESOURCE_NOT_FOUND","PLATFORM_SCOPE_NOT_GRANTED","PLATFORM_SERVICE_UNAVAILABLE","PLATFORM_TIMEOUT","PLATFORM_TOKEN_EXPIRED","PLATFORM_TOKEN_REVOKED","PLATFORM_UNSUPPORTED_OPERATION","PLATFORM_WORKFLOW_ACTION_NOT_ALLOWED"]},"message":{"type":"string"},"category":{"type":"string","x-braes-known-values":["approval","authentication","authorization","conflict","execution","isolation","limits","not_found","service","validation"]},"retryable":{"type":"boolean"},"terminal":{"type":"boolean"},"correlationId":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":["string","number","boolean","null"]}}},"required":["code","message","category","retryable","terminal"]}},"required":["error"]},"ExternalRestError":{"description":"Either a platform refusal (`ExternalPlatformError`) or a shared API error (`ApiError`, authentication and request-validation failures).","oneOf":[{"$ref":"#/components/schemas/ExternalPlatformError"},{"$ref":"#/components/schemas/ApiError"}]},"ApiError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{},"issues":{"type":"array","items":{}},"user_message":{"type":"string"},"user_next_step":{"type":"string"},"request_id":{"type":"string"}},"required":["error","code"]},"PageMeta":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["total","limit","offset","has_more"]},"ExternalRestEnvelope":{"type":"object","properties":{"data":{},"meta":{"type":"object","additionalProperties":{}},"warnings":{"type":"array","items":{"type":"string"}}}},"ExternalRestCommandBody":{"type":"object","additionalProperties":{}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Cognito-issued extension bearer token, sent as `Authorization: Bearer <token>`. It identifies the extension principal and its agency to the Braes gateway, which enforces authentication, policy, metering, and idempotency. Every route in this partition requires it."}},"parameters":{}},"paths":{"/api/v1/ext/health":{"get":{"summary":"Read extension REST partition health.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_health","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/catalog":{"get":{"summary":"Read the curated external REST catalog.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_catalog","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/queries/{queryId}/run":{"post":{"summary":"Run an approved governed query.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_run_query","x-braes-route-kind":"query","parameters":[{"schema":{"type":"string"},"required":true,"name":"queryId","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Governed query run. Results are paginated: when the response's `data.nextCursor` is a string, send it back as `cursor` to read the next page.","properties":{"parameters":{"type":"object","additionalProperties":true,"description":"Query parameters declared by the catalog entry."},"limit":{"type":"number","description":"Rows per page."},"cursor":{"type":"string","description":"`data.nextCursor` from the previous page."},"natural_language_input":{"type":"string","description":"Optional natural-language framing of the question (`naturalLanguageInput` is also accepted)."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/query-tokens":{"get":{"summary":"List governed query tokens.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_query_tokens_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}},"post":{"summary":"Create a governed query token.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_query_tokens_create","x-braes-route-kind":"command","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","description":"Required on every command. A retry with the same key and body replays the first response instead of executing twice; the same key with a different body is refused with PLATFORM_IDEMPOTENCY_CONFLICT."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestCommandBody"}}}},"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/query-tokens/{id}":{"delete":{"summary":"Revoke a governed query token.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_query_tokens_delete","x-braes-route-kind":"command","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","description":"Required on every command. A retry with the same key and body replays the first response instead of executing twice; the same key with a different body is refused with PLATFORM_IDEMPOTENCY_CONFLICT."},"required":true,"name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/query-tokens/{id}/templates/excel/{templateType}":{"get":{"summary":"Download a safe Excel Power Query template.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_query_token_excel_template","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"templateType","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/patients":{"get":{"summary":"List patients using the external patient summary profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_patients_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/patients/{id}":{"get":{"summary":"Read one patient using the external patient detail profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_patients_get","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/referrals":{"get":{"summary":"List referrals using the external referral summary profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_referrals_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}},"post":{"summary":"Create a referral from a full intake packet (demographics, coverage, diagnoses, documents) through the canonical referral-ingress pipeline. A 2xx means the lead was RECORDED, not necessarily accepted: read `disposition` on the echo — an out-of-area lead comes back as `declined` with `decline_reason` and `decline_detail` rather than being refused and lost.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway. Current request shape: 2026-08-19. Every earlier dated shape listed under x-braes-request-shape-history is still accepted, so an existing integration keeps working unchanged; a call written against a deprecated shape succeeds and returns a Deprecation header plus a meta.deprecations entry naming what to send instead.","tags":["External REST"],"operationId":"external_referrals_create","x-braes-route-kind":"command","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","description":"Required on every command. A retry with the same key and body replays the first response instead of executing twice; the same key with a different body is refused with PLATFORM_IDEMPOTENCY_CONFLICT."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","x-braes-request-shape-version":"2026-08-19","x-braes-request-shape-history":[{"version":"2026-04-01","status":"deprecated","summary":"Thin create: service line, a display name, and a few scalar ids. Still accepted and still creates a referral. It carries no demographics, address, coverage, diagnoses, or documents, so Braes cannot match the patient's existing chart, cannot validate the service territory from a ZIP the packet does not carry, and intake starts the referral with the record blank.","successor":"2026-08-19","deprecated_at":"2026-08-19T00:00:00Z","sunset_at":null},{"version":"2026-08-19","status":"current","summary":"Converged intake packet: demographics and date of birth for chart matching, service address and ZIP for territory and office routing, coverage, diagnoses, physician roles, and the referral document packet. Runs the same pipeline an emailed or faxed referral runs, and the echo reports what the pipeline decided (`intake_id`, `patient_created`, `patient_matched`, and the accepted/declined `disposition`).","sunset_at":null}],"properties":{"service_line":{"type":"string","description":"Business line the referral belongs to (home_health, hospice, private_duty, …).","x-braes-since":"2026-04-01"},"patient_name":{"type":"string","description":"Full display name. Supply this OR patient_first_name with patient_last_name.","x-braes-since":"2026-04-01"},"patient_first_name":{"type":"string","description":"Given name; used with patient_last_name to open a chart.","x-braes-since":"2026-08-19"},"patient_last_name":{"type":"string","description":"Family name; used with patient_first_name to open a chart.","x-braes-since":"2026-08-19"},"patient_middle_name":{"type":"string","description":"Middle name carried onto the chart.","x-braes-since":"2026-08-19"},"patient_suffix":{"type":"string","description":"Name suffix (Jr., III) carried onto the chart.","x-braes-since":"2026-08-19"},"patient_dob":{"type":"string","description":"Date of birth, YYYY-MM-DD. Part of the identity rule that matches an existing chart instead of forking a duplicate.","x-braes-since":"2026-08-19"},"patient_phone":{"type":"string","description":"Primary contact number; also participates in identity match.","x-braes-since":"2026-08-19"},"patient_alt_phone":{"type":"string","description":"Secondary contact number.","x-braes-since":"2026-08-19"},"patient_preferred_phone":{"type":"string","description":"Which number to call first: \"primary\" or \"alternate\".","x-braes-since":"2026-08-19"},"patient_address":{"type":"string","description":"Service address. The ZIP is extracted from it when patient_zip_code is absent.","x-braes-since":"2026-08-19"},"patient_zip_code":{"type":"string","description":"Service ZIP. Drives territory validation and office routing. Legacy alias: zip_code.","x-braes-since":"2026-08-19"},"zip_code":{"type":"string","description":"Service ZIP under its original field name. Still read exactly as before, and still used when patient_zip_code is absent. DEPRECATED since 2026-08-19: Send patient_zip_code instead; it names the same value and sits with the rest of the patient block. zip_code keeps working — there is no removal date.","x-braes-since":"2026-04-01","deprecated":true,"x-braes-replaced-by":"patient_zip_code"},"patient_coordinates":{"type":"object","description":"Geocoded service location as { latitude, longitude }, when the sender already resolved it.","x-braes-since":"2026-08-19"},"patient_id":{"type":"string","description":"Existing Braes patient to link this referral to. Omit to let the identity rule match or open a chart.","x-braes-since":"2026-04-01"},"existing_patient_episode_reviewed":{"type":"boolean","description":"Confirms the matched patient's open episode was accounted for (readmission vs additional referral). Required to link onto a patient who is mid-episode.","x-braes-since":"2026-08-19"},"referral_type":{"type":"string","description":"Referral type: \"soc\" (start of care), \"roc\" (resumption of care), or \"other\". Any other value is stored on the referral as sent and is treated as \"other\" by the intake surfaces that branch on it.","x-braes-since":"2026-04-01"},"referral_date":{"type":"string","description":"ISO timestamp the referral was made. Defaults to now.","x-braes-since":"2026-04-01"},"referral_source":{"type":"string","description":"Free-text name of the referring organization.","x-braes-since":"2026-04-01"},"referral_source_id":{"type":"string","description":"Braes referral source id, when the sender already knows it.","x-braes-since":"2026-08-19"},"referring_facility":{"type":"string","description":"Facility the patient is being referred from.","x-braes-since":"2026-08-19"},"referring_physician":{"type":"string","description":"Referring physician name when no Braes physician id is known.","x-braes-since":"2026-08-19"},"referring_physician_id":{"type":"string","description":"Braes physician id in the referring role.","x-braes-since":"2026-08-19"},"signing_physician_id":{"type":"string","description":"Braes physician id in the signing role.","x-braes-since":"2026-08-19"},"certifying_physician_id":{"type":"string","description":"Braes physician id in the certifying role.","x-braes-since":"2026-08-19"},"payor_id":{"type":"string","description":"Braes payor id for the primary coverage.","x-braes-since":"2026-04-01"},"hospital_id":{"type":"string","description":"Braes hospital id the referral originated from.","x-braes-since":"2026-08-19"},"marketer_id":{"type":"string","description":"Braes user id of the owning marketer.","x-braes-since":"2026-04-01"},"marketer_label":{"type":"string","description":"Marketer name when no Braes user id is known.","x-braes-since":"2026-04-01"},"insurance":{"type":"object","description":"Coverage facts: { payor_id, policy_number, group_number, effective_date, termination_date, is_primary, coverage_order, other_insurance_name }. A bare string is read as the plan name. coverage_order 0 is primary; send either it or is_primary and the other is derived. When the patient is covered through someone else's plan, add the policy holder (all optional): relationship_to_insured (X12 1069 code — 18 self, 01 spouse, 19 child, 20 employee, 53 life partner, G8 other, 21 unknown — or its name), insured_first_name, insured_last_name, insured_middle_name, insured_suffix, insured_dob (YYYY-MM-DD), insured_gender (female, male, unknown), insured_address_line_1, insured_address_line_2, insured_city, insured_state (two letters), insured_zip_code. An intake reviewer confirms the policy holder before it reaches the patient's coverage; a dependent sent without the policy holder's name is accepted and the intake asks for it.","x-braes-since":"2026-08-19"},"insurance_name":{"type":"string","description":"Plan name when insurance is sent as an object.","x-braes-since":"2026-08-19"},"insurance_notes":{"type":"string","description":"Free-text coverage notes for the intake reviewer.","x-braes-since":"2026-08-19"},"diagnoses":{"type":"array","description":"Referral diagnoses as [{ code, description, is_primary }]. The first entry is primary unless is_primary says otherwise.","x-braes-since":"2026-08-19"},"document_ids":{"type":"array","description":"Ids of documents already uploaded through the document upload flow; linked onto the created referral.","x-braes-since":"2026-08-19"},"notes":{"type":"string","description":"Free-text intake notes carried onto the referral.","x-braes-since":"2026-08-19"},"custom_data":{"type":"object","description":"Scalar key/value pairs stored on the intake record.","x-braes-since":"2026-08-19"},"source_system":{"type":"string","description":"Sending system name, stamped into the referral audit trail.","x-braes-since":"2026-08-19"},"external_reference_id":{"type":"string","description":"The sender's own identifier for this referral, stamped into the referral audit trail.","x-braes-since":"2026-08-19"}},"required":["service_line"],"additionalProperties":true}}}},"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/referrals/{id}":{"get":{"summary":"Read one referral using the external referral detail profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_referrals_get","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/intakes":{"get":{"summary":"List intakes using the external intake summary profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_intakes_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/intakes/{id}":{"get":{"summary":"Read one intake using the external intake detail profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_intakes_get","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/visits":{"get":{"summary":"List visits using the external visit summary profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_visits_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/visits/{id}":{"get":{"summary":"Read one visit using the external visit detail profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_visits_get","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/tasks":{"post":{"summary":"Create a task through the governed gateway.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_tasks_create","x-braes-route-kind":"command","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","description":"Required on every command. A retry with the same key and body replays the first response instead of executing twice; the same key with a different body is refused with PLATFORM_IDEMPOTENCY_CONFLICT."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestCommandBody"}}}},"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/tasks/{id}":{"get":{"summary":"Read one task using the external task profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_tasks_get","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}},"patch":{"summary":"Update one task using the external task update profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_tasks_patch","x-braes-route-kind":"command","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","description":"Required on every command. A retry with the same key and body replays the first response instead of executing twice; the same key with a different body is refused with PLATFORM_IDEMPOTENCY_CONFLICT."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestCommandBody"}}}},"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/actions/start-workflow":{"post":{"summary":"Start an approved workflow binding.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_start_workflow","x-braes-route-kind":"command","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","description":"Required on every command. A retry with the same key and body replays the first response instead of executing twice; the same key with a different body is refused with PLATFORM_IDEMPOTENCY_CONFLICT."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestCommandBody"}}}},"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/authorizations":{"get":{"summary":"List authorizations using the external authorization profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_authorizations_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/authorizations/{id}":{"get":{"summary":"Read one authorization using the external authorization profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_authorizations_get","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/claims/worklist":{"get":{"summary":"List claims worklist items using the external claim profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_claims_worklist","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/claims/{id}":{"get":{"summary":"Read one claim using the external claim detail profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_claims_get","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/documents/upload-url":{"post":{"summary":"Create a governed document upload placeholder.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_documents_upload_url","x-braes-route-kind":"command","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","description":"Required on every command. A retry with the same key and body replays the first response instead of executing twice; the same key with a different body is refused with PLATFORM_IDEMPOTENCY_CONFLICT."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestCommandBody"}}}},"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/documents/{id}/complete-upload":{"post":{"summary":"Complete a governed document upload.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_documents_complete_upload","x-braes-route-kind":"command","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","description":"Required on every command. A retry with the same key and body replays the first response instead of executing twice; the same key with a different body is refused with PLATFORM_IDEMPOTENCY_CONFLICT."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestCommandBody"}}}},"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/documents":{"get":{"summary":"List documents using the external document metadata profile.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_documents_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/documents/{id}/signed-url":{"get":{"summary":"Create a short-lived signed document URL.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_documents_signed_url","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/reference/branches":{"get":{"summary":"List branch reference values.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_reference_branches","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/reference/clinicians":{"get":{"summary":"List clinician reference values.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_reference_clinicians","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/reference/payors":{"get":{"summary":"List payor reference values.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_reference_payors","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/reference/physicians":{"get":{"summary":"List physician reference values.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_reference_physicians","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/reference/users/ids":{"get":{"summary":"List user ID reference values.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_reference_user_ids","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/remittances":{"get":{"summary":"List ERA remittance payments (payer, amount, payment date, status, claim count), newest payment date first. Read-only: posting and matching stay with the ERA owner in Braes.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_remittances_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/remittances/{id}/allocations":{"get":{"summary":"List the claim-level allocations of one ERA payment (charged, allowed, paid, adjusted, patient responsibility, CARC adjustment codes, match status) with page totals in meta.summary. An unknown remittance or one with no claim allocations returns an empty page.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_remittance_allocations_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/physician-orders":{"get":{"summary":"List physician orders with signature status and aging (days outstanding, aging bucket, SLA breach, days to sign), newest first. Order content is not included.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_physician_orders_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/physician-orders/{id}":{"get":{"summary":"Read one physician order's signature status and aging. Order content is not included.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_physician_orders_get","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/working-collections":{"get":{"summary":"List working collections this extension's agency identity can read (shared agency-wide, or naming it as an editor), with their typed field definitions. Read-only: rows are changed in Braes by the collection's owner or editors; each collection's `write` block names the door.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_working_collections_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/working-collections/{id}/rows":{"get":{"summary":"Read a page of one working collection's rows. Values are keyed by stable field id; meta.collection carries the field definitions. Supplemental values never establish clinical or financial facts. Read-only.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_working_collection_rows_list","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/quality/hhvbp/summary":{"get":{"summary":"Read the agency's Home Health Value-Based Purchasing summary: the CMS-published adjusted payment percentage and total performance score when available, and Braes' modeled projection (a diagnostic, not a CMS determination) in separately named fields. Agency-level; no patient data.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_quality_hhvbp_summary","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}},"/api/v1/ext/quality/hhvbp/measures":{"get":{"summary":"List the agency's HHVBP measure scores for one cycle (rates, thresholds, benchmarks, weights, achievement and improvement points, data sufficiency). Agency-level; no patient data.","description":"Curated governed extension REST route. Authentication, policy, metering, and idempotency are enforced by the platform gateway.","tags":["External REST"],"operationId":"external_quality_hhvbp_measures","x-braes-route-kind":"read","parameters":[{"schema":{"type":"string","enum":["1","2"],"description":"Extension contract version this request is written against. Omitted means the current version (2). An unknown or retired version is refused; a deprecated version still works and names its successor."},"required":false,"name":"braes-contract-version","in":"header"}],"responses":{"200":{"description":"Success","headers":{"braes-extension-contract-version":{"description":"Extension contract version this response was served under (the pinned version, or the current one when none was pinned).","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestEnvelope"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"402":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"500":{"description":"internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}},"504":{"description":"error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRestError"}}}}}}}},"webhooks":{}}