Skip to main content

​
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

POST /v1/runs

​
Headers

​
x-api-key
string
required
Your Docex API key.
​
content-type
string
required
Must be application/json.

​
Body

​
uploadId
string
required
The upload ID returned from POST /v1/uploads/presign.
​
prompt
string
required
Plain-English description of the analysis task. Example: "company name, number, expiry".
​
outputFormat
string
Either json (default) or text.
​
schemaId
string
Reference to a built-in registry schema. Use instead of inline schema.
​
schema
object
Inline custom schema with label, expectedFields, and promptScaffold.
​
workflow
string
Optional workflow label used for dashboard filtering and usage summaries.
​
metadata
object
Arbitrary key-value pairs attached to the job record.
​
confirmCost
boolean
Explicitly confirm a job whose estimated cost exceeds the confirmation threshold.
​
maxCostUsd
number
Abort the job if the estimated cost exceeds this budget.

​
Response

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

​
Get a run

GET /v1/runs/:jobId
Poll this endpoint until status is completed or failed.

​
Response (completed)

{
  "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)

{
  "status": "failed",
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "All providers exhausted",
    "status": 502,
    "retryable": true
  }
}

​
Verify a run

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

​
accepted
boolean
Mark the result as accepted.
​
corrections
object
Key-value pairs of corrected fields.

​
Code examples

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",
});

# 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"