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

string

required

Your Docex API key.

string

required

Must be application/json.

Body

string

required

The upload ID returned from POST /v1/uploads/presign.

string

required

Plain-English description of the analysis task. Example: "company name, number, expiry".

string

Either json (default) or text.

string

Reference to a built-in registry schema. Use instead of inline schema.

object

Inline custom schema with label, expectedFields, and promptScaffold.

string

Optional workflow label used for dashboard filtering and usage summaries.

object

Arbitrary key-value pairs attached to the job record.

boolean

Explicitly confirm a job whose estimated cost exceeds the confirmation threshold.

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

boolean

Mark the result as accepted.

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"

Getting Started

Concepts

API Reference

SDK & CLI

Integrations

Changelog

Runs

Runs

Create a run

Headers

Body

Response

Get a run

Response (completed)

Response (failed)

Verify a run

Body

Code examples

​Runs

​Create a run

​Headers

​Body

​Response

​Get a run

​Response (completed)

​Response (failed)

​Verify a run

​Body

​Code examples

Runs

Create a run

Headers

Body

Response

Get a run

Response (completed)

Response (failed)

Verify a run

Body

Code examples