curl --request POST \
--url http://localhost:3500/v1/documents/{id}/extract \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"strategy": "datalab"
}
'{
"status": "ready",
"content_url": "/v1/documents/550e8400-e29b-41d4-a716-446655440000/content?strategy=datalab"
}{
"workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"workflow_run_item_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "validation_error",
"message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).",
"request_id": "req_example"
}
}{
"error": {
"code": "invalid_token",
"message": "Missing or invalid bearer credential.",
"request_id": "req_example"
}
}{
"error": {
"code": "forbidden",
"message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.",
"request_id": "req_example"
}
}{
"error": {
"code": "not_found",
"message": "The resource does not exist in the current organization.",
"request_id": "req_example"
}
}{
"error": {
"code": "extraction_in_progress",
"message": "A different extraction is active, the source is unavailable, or the admitted run ended concurrently. workflow_run_id identifies conflicting work when available.",
"request_id": "req_example"
}
}{
"error": {
"code": "unsupported_media_type",
"message": "Supports PDF, DOCX, XLSX, EML, MSG, PNG and JPEG declarations. Unsupported MIME types, including text, Markdown and legacy Office formats, are rejected; filenames do not override declarations.",
"request_id": "req_example"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "The IP or authenticated credential exceeded its request limit.",
"request_id": "req_example"
}
}{
"error": {
"code": "internal_error",
"message": "Unexpected server failure. Include the request ID when contacting support.",
"request_id": "req_example"
}
}{
"error": {
"code": "service_unavailable",
"message": "Authentication infrastructure is unavailable or rate limited, or extraction dispatch failed or was not confirmed. Inspect workflow_run_id before retrying when provided. Honor Retry-After when provided.",
"request_id": "req_example"
}
}Extract Document content
Extracts an organization-owned PDF, DOCX, XLSX, EML, MSG, PNG or JPEG. PDF and DOCX support datalab and deterministic; XLSX, EML and MSG support deterministic; PNG/JPEG support datalab. Defaults are datalab for PDF/images and deterministic otherwise. Optional fallback_strategy runs once only when the primary produces no extractable content. Incomplete content, malformed files, limits, cancellation and provider errors never trigger fallback. Content is kept per strategy and reused whatever converter version produced it, so a newer version never re-extracts a Document by itself. A fallback is reused only after the requested strategy found no extractable content. Equivalent active work is shared. A different active strategy or fallback policy returns 409 with workflow_run_id. A new strategy adds content and never replaces content from another strategy. Failed/cancelled work can be retried as a linked new run. Does not extend unlinked-upload retention.
curl --request POST \
--url http://localhost:3500/v1/documents/{id}/extract \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"strategy": "datalab"
}
'{
"status": "ready",
"content_url": "/v1/documents/550e8400-e29b-41d4-a716-446655440000/content?strategy=datalab"
}{
"workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"workflow_run_item_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "validation_error",
"message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).",
"request_id": "req_example"
}
}{
"error": {
"code": "invalid_token",
"message": "Missing or invalid bearer credential.",
"request_id": "req_example"
}
}{
"error": {
"code": "forbidden",
"message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.",
"request_id": "req_example"
}
}{
"error": {
"code": "not_found",
"message": "The resource does not exist in the current organization.",
"request_id": "req_example"
}
}{
"error": {
"code": "extraction_in_progress",
"message": "A different extraction is active, the source is unavailable, or the admitted run ended concurrently. workflow_run_id identifies conflicting work when available.",
"request_id": "req_example"
}
}{
"error": {
"code": "unsupported_media_type",
"message": "Supports PDF, DOCX, XLSX, EML, MSG, PNG and JPEG declarations. Unsupported MIME types, including text, Markdown and legacy Office formats, are rejected; filenames do not override declarations.",
"request_id": "req_example"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "The IP or authenticated credential exceeded its request limit.",
"request_id": "req_example"
}
}{
"error": {
"code": "internal_error",
"message": "Unexpected server failure. Include the request ID when contacting support.",
"request_id": "req_example"
}
}{
"error": {
"code": "service_unavailable",
"message": "Authentication infrastructure is unavailable or rate limited, or extraction dispatch failed or was not confirmed. Inspect workflow_run_id before retrying when provided. Honor Retry-After when provided.",
"request_id": "req_example"
}
}Authorizations
Personal API key. Send X-Organization-Id. The required cumulative level is listed in x-watchdog-permission.
Headers
Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization.
Path Parameters
Body
Omit for the MIME default: datalab for PDF, PNG and JPEG; deterministic for DOCX, XLSX, EML, MSG and HTML.
datalab, deterministic Optional distinct strategy supported by this MIME. Invoked once only on no extractable content. Omit for no fallback.
datalab, deterministic