Quantum Nexus Async API

The Async API from Quantum Nexus — 6 operation(s) for async.

GitHub OpenAPI

Operations 11

POST /api/v1/jobs Enqueue an asynchronous analysis job #
GET /api/v1/jobs List the jobs of the api_key #
GET /api/v1/jobs/{id} Status and result of a job #
DELETE /api/v1/jobs/{id} Cancel a pending job #
POST /api/mcp/jobs Submit long-running work: audit (Node B), monte_carlo, consensus #
GET /api/mcp/jobs/{id} Job result (single read, 1h TTL) #
POST /api/v1/webhooks Register a webhook endpoint #
GET /api/v1/webhooks List the webhooks of the api_key #
GET /api/v1/webhooks/{id} Detail of a webhook (without secret) #
PATCH /api/v1/webhooks/{id} Update a webhook (active / events / description) #
DELETE /api/v1/webhooks/{id} Delete a webhook #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nexusquantum-legal:nexusquantum-legal-async-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

nexusquantum-legal-async-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Nexus Legal Async API
  version: 1.95.0
  description: 'Multi-jurisdictional legal analysis API with a multi-agent architecture and Zero Retention. ## Output language


    `language` (and the language implied by the jurisdiction) sets the language the text is written in. For `es` and `en` the delivered text is also measured: when a substantial part of it came back in the other of the two, a block headed `⚠️ LANGUAGE OF THIS REPORT` (`⚠️ IDIOMA DE ESTE INFORME` when `es` was requested) is added at the end of the text. It works the same with any engine, BYO included. - **When there is no block**: it is not a confirmation. Other languages are not measured, and neither is a text too short or too mixed to tell. - **With BYO**: how closely the output follows the request depends on your engine. - **If the output language is essential to your workflow**: check it on your side against the `analysis` string. ## The verdict travels INSIDE the text — read this before you parse a response


    Every string this API returns that a lawyer reads — `analysis`, `answer`, `report`, `draft`, `synthesisText`, and the string fields of structured results like `applicableLaw[]` — carries the citation verdict **inline**, not only in the `citationChecks` object beside it. **What you will actually see:**


    ```

    An acknowledgement does not revive a claim already barred: section 29(7) of the

    Limitation Act 1980 【✓】. See also [2019] EWHC 3556 (Comm)

    【◻ not checked — the reason is in this citation''s note】. ---

    DETERMINISTIC CITATION CHECK (against the official corpus)

    1 verified · 1 not checked. ◻ **Not checked** — they were not compared against any official corpus…

    ```


    - **Inline marker**: a `【…】` block immediately after each citation, in the response language. The glyph carries the verdict: `✓` verified · `⚠` a warning (e.g. the decision exists but a party you named does not appear in it) · `⛔` broken · `◻` not checked. - **Footer**: a `---` block at the end with the tally and, for anything not clean, the list of citations and why. **Why it is in the text and not only in the JSON.** Whoever copies an answer into an email, a brief or a .docx takes the PROSE. The `citationChecks` object does not travel with it. A verdict that only exists in a field beside the text is a verdict the reader can lose without noticing. **If you parse these strings**: markers are the only `【…】` sequences we emit, so they are safe to strip with a single regex if your pipeline needs the raw prose — but do not strip them from anything a human will read. `citationChecks` remains the machine-readable source of truth for counts and per-citation status; the markers are the same verdict, placed where it cannot get lost. **Idempotent**: annotating an already-annotated text does not duplicate markers or the footer. ## Streaming: `verifiedText` on the `done` event


    On SSE routes the client already holds the raw prose by the time the verifier finishes, so the closing `{type:"done"}` event carries `verifiedText`: the same answer with the verdict already in it. **If it is present, render it in place of the concatenated `text_delta` chunks.** It is omitted when there is nothing to annotate, in which case the deltas are already final. The REST wrappers do this for you — `/v1/consulta`, `/v1/chat` and the rest aggregate server-side and hand you the annotated text — so this only concerns you if you consume the SSE stream directly. ## Base capabilities


    - **Mode=deep**: the Node A (Claude Opus 4.7) + Node B (DeepSeek V4-Pro) chain audits adversarially. 2 credits. Returns an `audit` object with structured findings (hallucinations, false citations, omissions). - **Direct models**: calls through the providers'' own APIs (Anthropic, DeepSeek) with no proxies — lower latency, better rate limits. - **Stable Stripe-style error format**: `error.type`, `error.code`, `error.request_id`, `error.details` + backward-compat aliases. ## Errors and rate limits


    - **Branch on `error.code`.** A code you do not recognise is handled by its `error.type`.'
  contact:
    name: Nexus Legal
    email: support@nexusquantum.legal
    url: https://legal.nexusquantum.legal/developers
  license:
    name: Commercial
    url: https://nexusquantum.legal/terms
servers:
- url: https://legal.nexusquantum.legal
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Async
paths:
  /api/v1/jobs:
    post:
      summary: Enqueue an asynchronous analysis job
      description: 'Creates a job and returns 202 with `{jobId}`. The client can collect the result by polling (`GET /api/v1/jobs/[id]`) or register a webhook (`POST /api/v1/webhooks`) that receives `analysis.completed`, `analysis.failed`, `citation.broken` (≥1 citation verified as broken) or `analysis.flagged` (human review), signed with HMAC-SHA256.


        Supports `Idempotency-Key`: if the client retries with the same key + kind, it returns the original `jobId` without duplicating it.


        **Kind `consensus`** — full server-side multi-agent Node A↔B loop: primary analysis + adversarial audit + re-evaluation against the auditor objections (max. 2 iterations) and deterministic citation veto (broken citations ⇒ never CONSENSO_TOTAL, fail-closed). `payload`: `{ text (required, ≤50,000 chars), jurisdiction (required and EXPLICIT — no default), legalBranch?, language?, mode?, jurisdictionB?, useJurisprudencia? (jurisdiction-agnostic case-law RAG), referenceDate? (YYYY-MM-DD) }`. `result` (encrypted at rest, via `GET /api/v1/jobs/[id]`): `{ analysis, audit, consensusVerdict: "CONSENSO_TOTAL"|"CONSENSO_PARCIAL", consensusLabel, termination, secondPassRan, nodoBVerdict, confidenceScore, iterations: [{iteration, nodoBVerdict, confidenceScore, consensus, analysisChars, auditChars}], citationChecks, jurisdiction, processingMs }`. READ `termination` BEFORE `consensusVerdict`: `CONSENSO_PARCIAL` covers two different endings — `max_iterations` (the two agents reviewed and did not agree) and `caller_stopped` (the second review NEVER RAN, so the report went through a single pass; `secondPassRan: false`). `agreement` is the only case in which Node B signed off. Cost: aggregated per piece (A+B per iteration; ≤50k chars ⇒ 3 cr on the 1st, 7 cr with a 2nd round); the debit is applied when the job completes, for the iterations actually executed.'
      operationId: createJob
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{8,200}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - kind
              - payload
              properties:
                kind:
                  type: string
                  enum:
                  - analyze
                  - analyze_batch
                  - debate
                  - consensus
                payload:
                  type: object
                  description: 'Payload equivalent to the synchronous endpoint. For `consensus`: { text, jurisdiction (required, explicit), legalBranch?, language?, mode?, jurisdictionB?, useJurisprudencia?, referenceDate? }.'
            example:
              kind: analyze
              payload:
                text: Contract text...
                jurisdiction: ES
                legalBranch: civil
      responses:
        '202':
          description: Job accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                    - pending
                  createdAt:
                    type: string
                    format: date-time
                  pollUrl:
                    type: string
        '409':
          description: 'Conflict. `BYO_PROVIDER_REQUIRED` on SUBMIT — BYO-mandatory account WITHOUT an enabled BYO config (fail-closed; no kind falls back to platform engines). With the config enabled, `debate` runs on the FIRM OWN ENGINE: the panel is made up of the A/B/C roles of its `model_map` (3 distinct models recommended; role B arbitrates). For jobs already enqueued, the same enforcement surfaces as a `failed` job with `errorCode: BYO_PROVIDER_REQUIRED`. Also returned when an `Idempotency-Key` is reused with a different body.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
      x-codeSamples:
      - lang: TypeScript
        label: '@nexus-legal/sdk'
        source: "import { NexusClient } from \"@nexus-legal/sdk\";\n\nconst nexus = new NexusClient({ apiKey: process.env.NEXUS_API_KEY! });\n\n// Option A: convenient poll helper\nconst snap = await nexus.jobs.run({\n  kind: \"analyze\",\n  payload: { text: \"...\", jurisdiction: \"ES\", legalBranch: \"civil\" },\n});\nconsole.log(snap.status, snap.result);\n\n// Option B: manual\nconst job = await nexus.jobs.create({\n  kind: \"analyze\",\n  payload: { text: \"...\", jurisdiction: \"ES\", legalBranch: \"civil\" },\n});\n// then poll: const snap = await nexus.jobs.get(job.jobId);"
    get:
      summary: List the jobs of the api_key
      operationId: listJobs
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Job list.
          content:
            application/json:
              schema:
                type: object
  /api/v1/jobs/{id}:
    get:
      summary: Status and result of a job
      operationId: getJob
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Job snapshot.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                    format: uuid
                  kind:
                    type: string
                    enum:
                    - analyze
                    - analyze_batch
                    - debate
                    - consensus
                  status:
                    type: string
                    enum:
                    - pending
                    - running
                    - completed
                    - failed
                    - cancelled
                  createdAt:
                    type: string
                    format: date-time
                  startedAt:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  completedAt:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  creditsCharged:
                    type: integer
                  error:
                    type:
                    - object
                    - 'null'
                    description: 'Present when `status=failed`. Carries `{ code, message, details? }`. Terminal `code` values include `BYO_PROVIDER_REQUIRED`, `BYO_PROVIDER_ACCOUNT_ERROR` (YOUR engine rejected the request for an ACCOUNT reason — exhausted credit, revoked key, quota, model access; `details` carries `reason` and `provider`. Nexus never falls back to another engine and never substitutes a verdict your engine did not emit: fix the account and retry), `OUTPUT_WITHHELD_BY_POLICY` (delegated enforcement; `details` follows `WithholdDetails`, no credits charged), and `KEY_REVOKED_DURING_REQUEST` (the API/sub-key was revoked or expired mid-job — parity with the sync `401 KEY_REVOKED_DURING_REQUEST`).'
                  result:
                    type:
                    - object
                    - 'null'
                    description: 'Result payload; its shape follows `kind`. For `kind=debate` it carries `analysis`, `arbiter`, `tiers`, `rounds`, `citationAudit`, `jurisdiction` and **`panel`**. `panel` = `{ requested, participated, arbitrated, degraded }` and states how many models the deliverable was ACTUALLY built on. It matters because `tiers` lists the panel that was CONVENED and `rounds` the rounds that were run — neither drops when a debater fails, so a 2-model debate reached you shaped exactly like a 3-model one. Check `panel.degraded` before presenting the output as a full adversarial panel: `true` means `participated < requested` (fewer independent analyses) and/or `arbitrated: false` (the arbiter emitted no synthesis, so `analysis` is a SINGLE model''s text, not the panel''s reconciled result). The same warning is also prepended INSIDE `analysis`, in the analysis language, so it survives PDF export and copy-paste — the JSON metadata does not. `panel` is a NEW optional object, never a new value in a published enum. Engine failures do not land here: if YOUR BYO engine fails for an account reason the job terminates as `failed` with `error.code: BYO_PROVIDER_ACCOUNT_ERROR` instead of quietly delivering a smaller panel.'
        '404':
          description: Job not found.
    delete:
      summary: Cancel a pending job
      operationId: cancelJob
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Cancelled.
        '409':
          description: Job is not in pending state — it cannot be cancelled.
  /api/mcp/jobs:
    post:
      tags:
      - Async
      summary: 'Submit long-running work: audit (Node B), monte_carlo, consensus'
      description: 'SUBMIT+POLL for operations that exceed a synchronous timeout (reasoning models, 1-6 min). Accepts the SAME nlk_ Bearer as /api/v1 (scope `mcp`/`*`). Kinds: `audit` (standalone Node B), `monte_carlo`, `consensus` (A↔B loop). Complements /api/v1/jobs (analyze, analyze_batch, debate, consensus). Responds 202 { job_id } in <1s; the work runs in the background with the same credits/gates as the equivalent synchronous route. Under mandatory BYO, generative kinds return the job as `failed` with `error.code: BYO_PROVIDER_REQUIRED` when no config is enabled.'
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - kind
              - args
              properties:
                kind:
                  type: string
                  enum:
                  - audit
                  - monte_carlo
                  - consensus
                args:
                  type: object
                  description: 'Payload of the equivalent synchronous endpoint (nodo-b-audit | nodo-monte-carlo | nodo-consensus): text/analysis, jurisdiction (REQUIRED for consensus), language optional (follows the jurisdiction).'
      responses:
        '202':
          description: '{ job_id } — poll with GET /api/mcp/jobs/{id}.'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: VALIDATION_ERROR — unknown kind or invalid args.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiMcpJobs
      x-operation-id-source: derived
  /api/mcp/jobs/{id}:
    get:
      tags:
      - Async
      summary: Job result (single read, 1h TTL)
      description: 'Returns the status/result of the job submitted to /api/mcp/jobs. The result is delivered ONCE (single read) and expires after one hour (Zero Retention). States: pending | running | done | failed.'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: '{ status, result?, error? } — result includes the text with the deterministic citation verification.'
          content:
            application/json:
              schema:
                type: object
        '404':
          description: NOT_FOUND — job does not exist, already read, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiMcpJobsById
      x-operation-id-source: derived
  /api/v1/webhooks:
    post:
      summary: Register a webhook endpoint
      description: 'Registers a URL that will receive HMAC-SHA256-signed POSTs on events. The returned secret is shown ONLY ONCE — store it to verify the `X-Nexus-Signature` signature.


        Available events: `analysis.completed`, `analysis.failed`, `credits.low`, `normativa.updated` (Spain indexed at 100%, operational event; other jurisdictions still on rails), `citation.broken` and `analysis.flagged`.


        - `citation.broken` fires when `anyBroken === true`, that is, when the analysis contained ≥1 verifiable broken citation (`mismatch` + `not_found` + `derogated` > 0). The states `pending` (not parseable) and `not_verifiable` (jurisdiction with no active corpus) do NOT count as broken and never fire the event.

        - `analysis.flagged` (the «needs human review» umbrella) fires when `anyBroken === true` OR when verification could not run (`verificationError`, fail-safe). It carries `reasons: string[]` (e.g. `["broken_citations"]`, `["verification_error"]`). The `nodoBVerdict` travels as informational data inside `quality` but is NOT by itself a trigger.


        Governance events (v1.30.0): `apikey.created`, `apikey.revoked`, `apikey.updated`, `apikey.spend_cap_changed`, `spend_cap.reached` and `byo_provider.rejected` are low-frequency lifecycle events (key management, spend-cap enforcement, BYO fail-closed rejection). Every event delivered here is also durably readable via the pull API `GET /api/v1/events` (replay/backfill), even for accounts with no push endpoint registered.


        Operational governance events (v1.31.0): `provider.unreachable` (a BYO provider was unreachable — payload `provider_id`/`error_class`/`jurisdiction`), `verify.engine.degraded` (the citation-verification engine degraded on a metric — payload `degraded_metric`/`sample_size`/`jurisdiction`) and `rate_limit.sustained` (sustained 429s over a window — payload `window`/`count_429`/`rpm_limit`/`key_id`). Zero-Retention: these payloads carry only those diagnostic fields — never url, key material or request body. Also durably readable via `GET /api/v1/events` and the signed SIEM export `GET /api/v1/audit/export`.


        Only API-key-authenticated traffic has a webhook destination: `citation.broken`/`analysis.flagged` are emitted for jobs and synchronous API-key calls, not for web-session traffic.


        Every delivery carries a stable `event_id` (uuid) in the body — identical across retries and shared by all subscribed endpoints — for idempotent deduplication in SIEM. It is an alias of `id`; the `X-Nexus-Event-Id` header mirrors that value (unlike `X-Nexus-Delivery-Id`, which is per-endpoint/per-retry and is NOT usable as a dedupe key).


        Signature: `X-Nexus-Signature: t=,v1=` where `hmac = HMAC-SHA256(secret, t + ''.'' + rawBody)`. Exponential retries up to 5 times (1m, 5m, 30m, 2h, 12h).'
      operationId: createWebhook
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                    enum:
                    - analysis.completed
                    - analysis.failed
                    - credits.low
                    - normativa.updated
                    - citation.broken
                    - analysis.flagged
                    - apikey.created
                    - apikey.revoked
                    - apikey.updated
                    - apikey.spend_cap_changed
                    - spend_cap.reached
                    - spend_burst.detected
                    - spend_burst.blocked
                    - byo_provider.rejected
                    - output.withheld
                    - provider.unreachable
                    - verify.engine.degraded
                    - rate_limit.sustained
                description:
                  type: string
                  maxLength: 200
            example:
              url: https://example.com/nexus-webhook
              events:
              - analysis.completed
              - analysis.failed
              description: Production webhook for case-management integration
      responses:
        '201':
          description: Webhook created. The `secret` field is only shown here.
          content:
            application/json:
              schema:
                type: object
      x-codeSamples:
      - lang: TypeScript
        label: '@nexus-legal/sdk'
        source: "import { NexusClient, verifyWebhookSignature } from \"@nexus-legal/sdk\";\n\n// 1. Register the endpoint (returns the secret only once)\nconst nexus = new NexusClient({ apiKey: process.env.NEXUS_API_KEY! });\nconst wh = await nexus.webhooks.create({\n  url:    \"https://example.com/nexus-webhook\",\n  events: [\"analysis.completed\", \"analysis.failed\"],\n});\n// ⚠️ Store wh.secret in your vault NOW — it cannot be retrieved later.\n// (This line must NOT be left in production.)\nconsole.log(\"✓ Webhook created:\", wh.id);\n\n// 2. In your HTTP handler (Express, Next, etc.) verify the signature:\n//\n//   const rawBody = await req.text();   // unparsed body\n//   const valid = await verifyWebhookSignature({\n//     rawBody,\n//     signature: req.headers.get(\"x-nexus-signature\")!,\n//     secret:    process.env.WEBHOOK_SECRET!,\n//   });\n//   if (!valid) return new Response(\"invalid signature\", { status: 401 });\n//   const payload = JSON.parse(rawBody);"
    get:
      summary: List the webhooks of the api_key
      operationId: listWebhooks
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      responses:
        '200':
          description: List.
          content:
            application/json:
              schema:
                type: object
  /api/v1/webhooks/{id}:
    get:
      summary: Detail of a webhook (without secret)
      operationId: getWebhook
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Webhook.
        '404':
          description: Not found.
    patch:
      summary: Update a webhook (active / events / description)
      operationId: updateWebhook
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                active:
                  type: boolean
                events:
                  type: array
                  items:
                    type: string
                    enum:
                    - analysis.completed
                    - analysis.failed
                    - credits.low
                    - normativa.updated
                    - citation.broken
                    - analysis.flagged
                    - apikey.created
                    - apikey.revoked
                    - apikey.updated
                    - apikey.spend_cap_changed
                    - spend_cap.reached
                    - spend_burst.detected
                    - spend_burst.blocked
                    - byo_provider.rejected
                    - output.withheld
                    - provider.unreachable
                    - verify.engine.degraded
                    - rate_limit.sustained
                description:
                  type: string
                  maxLength: 200
      responses:
        '200':
          description: Updated.
    delete:
      summary: Delete a webhook
      operationId: deleteWebhook
      security:
      - ApiKeyAuth: []
      tags:
      - Async
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted.
components:
  schemas:
    ConflictError:
      type: object
      required:
      - error
      description: '409 Conflict — Stripe-style envelope. Main case: code BYO_PROVIDER_REQUIRED (account with BYO-LLM enforced and no enabled configuration; register a provider with POST /api/v1/llm-providers). On SSE routes whose stream is already open, the same code travels as an event {type:''error'', code}. It applies to the generative endpoints, where the account can supply its own engine, and there is no fallback to the platform engines: with an enabled configuration, the effective routing on those endpoints is `own_only`, even if the configuration declares `own_then_platform`. Case-mode utilities that do not take your engine (timeline, metadata extraction, tone analysis) never return this code: they run with personal data masked first and return a `ZERO_RETENTION_EXTERNAL_UTILITY` notice (severity `warning`) in `notices`/`warnings`, as OCR and audio do with `ZERO_RETENTION_EXTERNAL_PERCEPTION`. The requirement is set by Nexus on the account and cannot be changed through the API.'
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          properties:
            type:
              type: string
              example: conflict_error
            code:
              type: string
              example: BYO_PROVIDER_REQUIRED
            message:
              type: string
            request_id:
              type: string
            details:
              type: object
        error_message:
          type: string
          description: Backward-compat (deprecated v1.7).
        code:
          type: string
          description: Backward-compat (deprecated v1.7).
    ErrorResponse:
      type: object
      required:
      - error
      description: Stripe-style error envelope returned by apiError() on ALL v1 routes. `error` is an OBJECT {type, code, message, request_id, details?}; the top-level `error_message`/`code` are backward-compat (deprecated v1.7). A generated client must deserialize `error` as an object, not as a string.
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          properties:
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
            request_id:
              type: string
            details:
              type: object
              description: Optional. An engine failure carries what you need in order to decide what to do next, and a `429` says whose ceiling you reached. Each field is present only when it was measured, and `details` is omitted entirely rather than sent empty.
              properties:
                retryable:
                  type: boolean
                  description: Whether retrying this exact request can succeed. Absent means not measured — do not read absence as `true`.
                refunded:
                  type: boolean
                  description: Whether the credit for this call was returned. Absent means not measured.
                reason:
                  type: string
                  description: Short machine-readable cause.
                  example: provider_timeout
                provider:
                  type: string
                  description: Which engine failed. On a BYO tenant this is the difference between checking your own key and opening a ticket with us.
                  example: Anthropic (BYO)
                error_class:
                  type: string
                scope:
                  type: string
                  enum:
                  - ip
                  - user
                  - organization
                  description: 'On a `429`: whose ceiling you reached.'
                retry_after_seconds:
                  type: integer
                  description: 'On a `429`: seconds to wait, the same value as the `Retry-After` header.'
                limit_per_minute:
                  type: integer
                  description: 'On a `429`: the per-minute ceiling you reached.'
        error_message:
          type: string
          description: Backward-compat (deprecated v1.7).
        code:
          type: string
          description: Backward-compat (deprecated v1.7).
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: nlk_...