Extract #
POST /extract: submit a document for extraction. The recommended entry point for new integrations.
POST /extract is the unified extraction entry point. It accepts a file
descriptor, returns a presigned upload URL plus the IDs you'll need to track
the job. Submission is the first of three client calls — you also need to
PUT the bytes to S3 and then call
POST /artifacts/{artifact_id}/confirm-upload
so the backend knows to enqueue the job.
| Method | Path | Auth | Returns |
|---|---|---|---|
POST | /api/v1/extract | HTTP Basic | 202 Accepted + ExtractResponse |
Request body
{
"filename": "invoice.pdf",
"artifact_type": "application/pdf",
"artifact_size": 184320,
"retention_policy": "30d",
"template_id": "tpl_invoice_v3",
"extraction_schema": null,
"webhook_id": null,
"webhook_url": null
}
| Field | Type | Required | Notes |
|---|---|---|---|
filename | string | yes | Original filename including extension. Used in the dashboard and result metadata. |
artifact_type | string | yes | MIME type. The presigned URL is signed against this; your PUT must match. |
artifact_size | integer | yes | Size in bytes. Must be > 0. |
retention_policy | enum | no | immediate, 3h, 6h, 12h, 1d, 3d, 7d, 30d (default), 90d, 365d, never. |
template_id | string | no | ID of a saved template. Mutually exclusive with extraction_schema. |
extraction_schema | object | no | Inline JSON schema. Mutually exclusive with template_id. |
webhook_id | string | no | Pre-registered webhook to call on completion. |
webhook_url | string | no | One-shot HTTPS URL. Signing secret returned in response. |
Send exactly one of template_id or extraction_schema. Sending both
returns 400 Bad Request.
If neither webhook_id nor webhook_url is supplied, the API uses the
default attached to the request's pipeline or API key. Resolution order:
request webhook_id > request webhook_url > pipeline default > API-key default.
Response (202 Accepted)
202 Accepted){
"job_id": "job_8f3c2e1a",
"artifact_id": "art_b4d8c0f1",
"upload_url": "https://s3.amazonaws.com/dd-uploads/…?X-Amz-Signature=…",
"fields": {},
"expires_in": 3600,
"webhook_signing_secret": null
}
| Field | Type | Notes |
|---|---|---|
job_id | string | Use with GET /job/{job_id} and webhook payloads. |
artifact_id | string | Use with GET /artifacts/{id}, cancel, rerun, download. |
upload_url | string | Presigned S3 PUT URL. Single-use; expires in expires_in seconds. |
fields | object | Form fields required by the upload (empty for direct PUT URLs). |
expires_in | integer | Seconds the upload URL remains valid. Default 3600 (1h). |
webhook_signing_secret | string | null | Set only when you passed webhook_url. Shown exactly once. |
Example · cURL
curl -u "$DD_KEY:$DD_SECRET" \
-X POST https://api.datadistillers.com/api/v1/extract \
-H 'Content-Type: application/json' \
-d '{
"filename": "invoice.pdf",
"artifact_type": "application/pdf",
"artifact_size": 184320,
"template_id": "tpl_invoice_v3"
}'
Example · client libraries
Errors
| Status | Meaning |
|---|---|
400 | Validation failed (missing field, both template_id and extraction_schema set, invalid webhook_url). |
401 | Auth credentials missing or invalid. |
402 | Wallet frozen or insufficient spendable. |
404 | template_id or webhook_id not found. |
422 | Body shape didn't match the schema (Pydantic / FastAPI validation). |
429 | Rate limited. See Retry-After. |
See Errors for the canonical envelope and retry guidance.
- Confirm an upload: the second client call, required to enqueue the job.
- Get job status: poll for completion.
- Get artifact: full artifact record + download URLs.
- Submit a batch: up to 50 files per request.
- Templates: manage saved schemas.
- Webhooks: register, rotate, debug.