> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs

> Create a vision analysis run, poll for completion, and receive a structured envelope with results, confidence, and usage.

# Runs

> The `/v1/runs` endpoints are the core of the Docex API. Create a run with an upload ID and prompt, poll for completion, and receive a structured envelope.

## Create a run

```bash theme={null}
POST /v1/runs
```

### Headers

<ParamField header="x-api-key" type="string" required>
  Your Docex API key.
</ParamField>

<ParamField header="content-type" type="string" required>
  Must be `application/json`.
</ParamField>

### Body

<ParamField body="uploadId" type="string" required>
  The upload ID returned from `POST /v1/uploads/presign`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Plain-English description of the analysis task. Example: `"company name, number, expiry"`.
</ParamField>

<ParamField body="outputFormat" type="string">
  Either `json` (default) or `text`.
</ParamField>

<ParamField body="schemaId" type="string">
  Reference to a built-in registry schema. Use instead of inline `schema`.
</ParamField>

<ParamField body="schema" type="object">
  Inline custom schema with `label`, `expectedFields`, and `promptScaffold`.
</ParamField>

<ParamField body="workflow" type="string">
  Optional workflow label used for dashboard filtering and usage summaries.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs attached to the job record.
</ParamField>

<ParamField body="confirmCost" type="boolean">
  Explicitly confirm a job whose estimated cost exceeds the confirmation threshold.
</ParamField>

<ParamField body="maxCostUsd" type="number">
  Abort the job if the estimated cost exceeds this budget.
</ParamField>

### Response

```json theme={null}
{
  "jobId": "job_abc123",
  "status": "queued",
  "uploadId": "ul_def456",
  "prompt": "company name, number, expiry",
  "outputFormat": "json",
  "schemaId": null,
  "estimatedCostUsd": 0.0321,
  "metadata": {}
}
```

## Get a run

```bash theme={null}
GET /v1/runs/:jobId
```

Poll this endpoint until `status` is `completed` or `failed`.

### Response (completed)

```json theme={null}
{
  "status": "completed",
  "schemaId": null,
  "protocolVersion": "0.1.0",
  "requests": 1,
  "outputFormat": "json",
  "result": {
    "legal_name": "ACME LOGISTICS L.L.C",
    "license_no": "1019388",
    "expires_on": "2026-03-13"
  },
  "usage": {
    "requests": 1,
    "billableUnits": 1,
    "costUsd": 0.0321,
    "priceUsd": 0.0642
  },
  "chargedUsd": 0.0642,
  "confidence": 0.95,
  "metadata": {}
}
```

### Response (failed)

```json theme={null}
{
  "status": "failed",
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "All providers exhausted",
    "status": 502,
    "retryable": true
  }
}
```

## Verify a run

```bash theme={null}
POST /v1/runs/:jobId/verify
```

Accept or correct an analysis result as QA metadata for dashboard review. Verification does not promote models or change routing policy.

### Body

<ParamField body="accepted" type="boolean">
  Mark the result as accepted.
</ParamField>

<ParamField body="corrections" type="object">
  Key-value pairs of corrected fields.
</ParamField>

## Code examples

<CodeGroup>
  ```js SDK theme={null}
  import { createDocex } from "docexdev";

  const docex = createDocex({ apiKey, baseUrl });
  const result = await docex.run({
    file: "./invoice.pdf",
    prompt: "Extract line items, totals, and vendor details",
  });
  ```

  ```bash curl theme={null}
  # 1. Presign upload
  curl -X POST https://api.docex.dev/v1/uploads/presign \
    -H "x-api-key: $DOCEX_API_KEY" \
    -H "content-type: application/json" \
    -d '{"fileName":"invoice.pdf","contentLength":12345}'

  # 2. Upload file (use uploadUrl from step 1)
  curl -X PUT "$UPLOAD_URL" \
    -H "content-type: application/octet-stream" \
    --data-binary @invoice.pdf

  # 3. Create run
  curl -X POST https://api.docex.dev/v1/runs \
    -H "x-api-key: $DOCEX_API_KEY" \
    -H "content-type: application/json" \
    -d '{"uploadId":"ul_...","prompt":"Extract line items, totals, and vendor details"}'

  # 4. Poll until completed
  curl https://api.docex.dev/v1/runs/job_... \
    -H "x-api-key: $DOCEX_API_KEY"
  ```
</CodeGroup>