---
title: "Enqueue an asynchronous analysis job"
method: POST
path: "/api/v1/jobs"
tags: ["Async"]
---

# Enqueue an asynchronous analysis job

`POST /api/v1/jobs`

## Request

- Base URL: `https://legal.nexusquantum.legal`
- URL: `https://legal.nexusquantum.legal/api/v1/jobs`
- Auth: HTTP bearer

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. Both fields were dropped by the async lane until 2026-07-26. 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.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `kind` 'analyze' | 'analyze_batch' | 'debate' | 'consensus', required
  - `payload` object, required: Payload equivalent to the synchronous endpoint. For `consensus`: { text, jurisdiction (required, explicit), legalBranch?, language?, mode?, jurisdictionB?, useJurisprudencia?, referenceDate? }.

## Response `202`

Job accepted.

- object
  - `jobId` string, uuid
  - `status` 'pending'
  - `createdAt` string, date-time
  - `pollUrl` string

## Other responses

- `409`: 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.

---

[API](https://skmtc.dev/nexusquantum/apis/nexus-legal-api.md) · [All operations](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/revisions/4084d8d4eb0b?raw)