API reference

Classify and extract any document. Authenticate with an API key from Integrations → API keys: Authorization: Bearer dwk_…. Every error has the shape { "error": { "code", "message", "request_id" } }.

Base URL https://www.docwise.io/api/v1 · OpenAPI 3.1: /api/v1/openapi.json

Authentication

Create a key under Integrations → API keys in your workspace. Send it as a bearer token. Keys carry scopes (documents:read, documents:write, uploads:write, webhooks:read), can be bound to one project and can expire. Paths end with a slash.

Errors, rate limits and idempotency

{ "error": { "code": "insufficient_scope", "message": "This API key lacks the documents:write scope", "request_id": "req_…" } }

Every response has an X-Request-Id; quote it when contacting support.
Each key has a per-minute limit. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After (seconds).
Send an Idempotency-Key header when creating documents, starting uploads or retrying, and reuse it when you retry the same request.
Ids from other workspaces return 404.

Documents

Create, list, read, cancel, retry and export documents

GET/documents/documents:read

List documents

Newest first. Pass next_cursor back as cursor to fetch the next page; a cursor only works with the same filters.

Requires scope documents:read.

Parameters
limit	query	integer
cursor	query	string
status	query	"UPLOADING" \| "SCANNING" \| "QUEUED" \| "CLASSIFYING" \| "EXTRACTING" \| "NEEDS_REVIEW" \| "COMPLETED" \| "FAILED" \| "REJECTED" \| "BLOCKED" \| "CANCELLED"
type	query	string	Document type id
project_id	query	string
created_after	query	string (date-time)
created_before	query	string (date-time)

Responses

200 A page of documents DocumentList
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X GET "https://www.docwise.io/api/v1/documents/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

POST/documents/documents:write

Upload a document (multipart)

For files up to 100 MB. Processing is asynchronous: poll the document or subscribe to webhooks. For large files or browser uploads prefer the presigned upload flow.

Requires scope documents:write.

Parameters
Idempotency-Key	header	string	Retrying with the same key and the same file returns the original document (200) instead of creating a new one.

Body multipart/form-data CreateDocumentForm

Responses

200 Idempotent replay of an earlier request DocumentCreated
201 Document accepted and queued DocumentCreated
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X POST "https://www.docwise.io/api/v1/documents/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY" \
  -F "file=@document.pdf"

GET/documents/{id}/documents:read

Get a document's status and result

result is the latest extraction: data holds typed values; fields lists every value with its JSON pointer, confidence and evidence (page, quote and boxes).

Requires scope documents:read.

Parameters
id *	path	string

Responses

200 The document DocumentDetail
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X GET "https://www.docwise.io/api/v1/documents/{id}/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

POST/documents/{id}/cancel/documents:write

Cancel processing

Requires scope documents:write.

Parameters
id *	path	string

Responses

202 Cancellation accepted DocumentOperation
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X POST "https://www.docwise.io/api/v1/documents/{id}/cancel/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

POST/documents/{id}/retry/documents:write

Retry a failed, blocked or cancelled document

Requires scope documents:write.

Parameters
id *	path	string
Idempotency-Key	header	string	8–100 characters. A repeated key returns the original retry.

Responses

202 Retry queued DocumentOperation
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X POST "https://www.docwise.io/api/v1/documents/{id}/retry/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

GET/documents/export/documents:read

Export results of one document type

CSV and XLSX have one row per line item (the type's first table field) with header fields repeated; JSON returns one object per document. X-Export-Truncated: true means more documents matched than limit.

Requires scope documents:read.

Parameters
type *	query	string	Document type id (required: columns follow the type's fields)
format	query	"csv" \| "json" \| "xlsx"
status	query	"COMPLETED" \| "NEEDS_REVIEW"
created_after	query	string (date-time)
created_before	query	string (date-time)
limit	query	integer

Responses

200 The export file text/csv, application/json, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X GET "https://www.docwise.io/api/v1/documents/export/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

Uploads

Presigned direct-to-storage uploads

GET/uploads/uploads:write

Check whether presigned uploads are enabled

Requires scope uploads:write.

Responses

200 Availability UploadAvailability
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X GET "https://www.docwise.io/api/v1/uploads/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

POST/uploads/uploads:write

Start a presigned upload

Declare the file (name, MIME type, size, SHA-256). PUT the bytes to upload.url with upload.headers before it expires, then complete the upload.

Requires scope uploads:write.

Parameters
Idempotency-Key	header	string	Repeating the same declaration with the same key returns the same session.

Body application/json UploadRequest

Responses

201 Upload session UploadStarted
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X POST "https://www.docwise.io/api/v1/uploads/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY" \
  -H "Content-Type: application/json" -d '{…}'

GET/uploads/{uploadId}/uploads:write

Poll an upload session

After SUCCEEDED, documentId is the created document.

Requires scope uploads:write.

Parameters
uploadId *	path	string

Responses

200 Upload session UploadSession
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X GET "https://www.docwise.io/api/v1/uploads/{uploadId}/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

POST/uploads/{uploadId}/complete/uploads:write

Complete an upload

Send an empty JSON object. The file is scanned and verified, then queued for processing.

Requires scope uploads:write.

Parameters
uploadId *	path	string

Body application/json object

Responses

202 Upload accepted for inspection UploadSession
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X POST "https://www.docwise.io/api/v1/uploads/{uploadId}/complete/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY" \
  -H "Content-Type: application/json" -d '{…}'

Document types

Types enabled in this workspace

GET/document-types/documents:read

List enabled document types

Requires scope documents:read.

Responses

200 Enabled document types DocumentTypeList
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X GET "https://www.docwise.io/api/v1/document-types/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

Webhooks

Endpoints are managed in the workspace; events are listed under webhooks

GET/webhook-endpoints/webhooks:read

List webhook endpoints

Endpoints are managed in the workspace under Integrations. Secrets are never returned.

Requires scope webhooks:read.

Responses

200 Endpoints and supported events WebhookEndpointList
Errors: 400, 401, 403, 404, 409, 429 — see errors.

Example request

curl -sS -X GET "https://www.docwise.io/api/v1/webhook-endpoints/" \
  -H "Authorization: Bearer $DOCWISE_API_KEY"

Webhook events

Every delivery body is a WebhookEvent. See the signature verification guide.

document.completed: Processing finished. Also sent after a review accepts or corrects the fields.
document.needs_review: A person must classify the document or confirm low-confidence fields.
document.failed: Processing failed after retries. code says why; the document can be retried.
document.blocked: No published document type or available model could process the document.
review.completed: A reviewer accepted or corrected the fields. review identifies the decision and result is final.

Schemas

Error

error *

object

DocumentTypeRef

id *	string
name *	string

DocumentStatus

Document

id *	string
object *	"document"
project_id *	string
status *	DocumentStatus
filename *	string \| null
mime_type *	string
page_count *	integer
file_size *	integer	Bytes
source *	string	API, UI or EMAIL
document_type *	DocumentTypeRef \| null
confidence *	number \| null	Classification confidence, 0–1
failure_reason *	string \| null
parent_document_id *	string \| null	Set when this document is a segment split from a multi-document upload
cancel_requested *	boolean
created_at *	string (date-time)
updated_at *	string (date-time)

EvidenceBox

page *	integer
x *	number
y *	number
width *	number
height *	number

FieldEvidence

page *	integer \| null
quote *	string \| null
boxes *	EvidenceBox[]

ResultField

path *	string	JSON pointer into result.data
label *	string
type *	string	Field type: string, number, integer, currency, date, boolean, enum, …
value *	any
confidence *	number \| null
evidence *	FieldEvidence \| null

DocumentResult

run_id *	string
outcome *	"MATCHED" \| "AMBIGUOUS" \| "UNKNOWN" \| "MIXED_DOCUMENT" \| null
document_type *	DocumentTypeRef \| null
confidence *	number \| null
completed_at *	string (date-time) \| null
data *	any	Extracted values, shaped by the document type's fields
fields *	ResultField[]

DocumentReview

id *	string
status *	"OPEN" \| "IN_PROGRESS" \| "RESOLVED"
reason *	"AMBIGUOUS" \| "UNKNOWN" \| "MIXED_DOCUMENT" \| "FIELD_BELOW_THRESHOLD"
created_at *	string (date-time)
resolved_at *	string (date-time) \| null

DocumentDetail

id *	string
object *	"document"
project_id *	string
status *	DocumentStatus
filename *	string \| null
mime_type *	string
page_count *	integer
file_size *	integer	Bytes
source *	string	API, UI or EMAIL
document_type *	DocumentTypeRef \| null
confidence *	number \| null	Classification confidence, 0–1
failure_reason *	string \| null
parent_document_id *	string \| null	Set when this document is a segment split from a multi-document upload
cancel_requested *	boolean
created_at *	string (date-time)
updated_at *	string (date-time)
result *	DocumentResult \| null
review *	DocumentReview \| null

DocumentList

object *	"list"
data *	Document[]
has_more *	boolean
next_cursor *	string \| null

DocumentCreated

id *	string
object *	"document"
status *	DocumentStatus
idempotent_replay *	boolean
errors	string[]

DocumentOperation

id *	string
object *	"document"
status *	DocumentStatus
cancel_requested	boolean

DocumentType

id *	string
object *	"document_type"
name *	string
category *	string
description *	string \| null
version *	string \| null
schema *	any	JSON Schema of the extracted data

DocumentTypeList

object *	"list"
data *	DocumentType[]

UploadRequest

projectId	string
fileName *	string
mimeType *	"application/pdf" \| "image/png" \| "image/jpeg" \| "image/tiff"
size *	integer
sha256 *	string

UploadSession

id *	string
state *	"UPLOADING" \| "READY" \| "PROCESSING" \| "SUCCEEDED" \| "FAILED" \| "EXPIRED"
expiresAt *	string (date-time)
failureCode *	string \| null
documentId *	string \| null
documentStatus	DocumentStatus

UploadStarted

session *	UploadSession
upload	object	Present while the session is UPLOADING. PUT the exact bytes to url with these headers.

UploadAvailability

enabled *

boolean

WebhookEndpoint

id *	string
object *	"webhook_endpoint"
url *	string
events *	string[]
status *	string
created_at *	string (date-time)

WebhookEndpointList

object *	"list"
data *	WebhookEndpoint[]
supported_events *	string[]

WebhookEvent

id *	string	Stable event id; deduplicate on it (delivery is at least once)
event *	"document.completed" \| "document.needs_review" \| "document.failed" \| "document.blocked" \| "review.completed" \| "webhook.test"
version *	string
createdAt *	string (date-time)
data *	object

ApiScope

documents:read | documents:write | uploads:write | webhooks:read

API reference

Authentication

Errors, rate limits and idempotency

Documents

List documents

Upload a document (multipart)

Get a document's status and result

Cancel processing

Retry a failed, blocked or cancelled document

Export results of one document type

Uploads

Check whether presigned uploads are enabled

Start a presigned upload

Poll an upload session

Complete an upload

Document types

List enabled document types

Webhooks

List webhook endpoints

Meta

This OpenAPI document

Webhook events

Schemas

Error

DocumentTypeRef

DocumentStatus

Document

EvidenceBox

FieldEvidence

ResultField

DocumentResult

DocumentReview

DocumentDetail

DocumentList

DocumentCreated

DocumentOperation

DocumentType

DocumentTypeList

UploadRequest

UploadSession

UploadStarted

UploadAvailability

WebhookEndpoint

WebhookEndpointList

WebhookEvent

ApiScope