Overview

Perception runs five tools on a document, each at POST /v1/documents/{tool}. They use the same nace_sk_ key and the same credit as POST /v1/systemone, at base URL https://console.nace.ai.

Tools chain: parse a file once, then pass the parse to Split, Extract or Ground so it isn't parsed and paid for again.

Create a jobCopy Anchor Link

Every tool takes a JSON body with a source (the document to work on) and that tool's options:

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $DREX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2026-10-01-0001" \
  -d '{
    "source": {
      "type": "url",
      "url": "https://example.com/invoice.pdf",
      "file_name": "invoice.pdf"
    },
    "output": { "formats": ["markdown"] }
  }'

The answer is 202 with the job, status: "queued". Its job_id is what every other route takes: read it until it finishes, as in Jobs and results. The x-drex-document-job header carries Drex's own id for the charge; quote it with request_id when you contact support.

Wait in the same callCopy Anchor Link

Add ?wait_seconds=N (up to 60) to hold the request open until the job finishes. When it finishes in time, the answer is 200 with the result. Otherwise it's 202, and you read the job as usual.

Retry safelyCopy Anchor Link

Send an Idempotency-Key header, up to 200 characters and unique within your account.

• Same key, same body: returns the same job, never a second one, and isn't billed again.
• Same key, different body: refused with 409, code idempotency_conflict.
• No key: every request creates a new job.

SourcesCopy Anchor Link

Where an operation takes corpus_sources, it may list only workspace_file sources from your workspace. Any other source, or one that names another account's job or workspace, is refused with 422, code invalid_source, before anything is created or billed.

BillingCopy Anchor Link

• Admission: a job is admitted only while the account's balance is positive. Otherwise the create answers 402.
• Charge: nothing is charged when the job is created. When it finishes, the document service reports its final credits (also in the job body, with usage_final: true), and Drex charges credits times the operation's price, once.
• Negative balance: a job that finishes after the balance reached zero is still charged, which can leave the balance negative. New jobs are then refused until a top-up.
• Free: reading, listing and deleting jobs, uploads and saved schemas cost nothing and work at any balance.

Each tool uses credits on its inputs, so a job's cost is known before it is sent:

parse_mode: "high" doubles the credits of Parse, Split, Classify and Extract, because it adds agentic OCR correction. Spreadsheets count 500 non-empty cells as one page per sheet, rounded up, and audio counts each started minute as one page.

The rest of billing is on Pricing. While document prices aren't configured, creates answer 503, code document_billing_not_configured, and nothing is started.

Errors and rate limits are on Errors.