Uploads

Each account has its own workspace on the document service, created the first time you upload. Files go straight from your client to the document service, so Drex puts no limit on their size. Uploads are free and work at any balance.

One fileCopy Anchor Link

Ask for an upload grant, then send the file to the upload_url it returns, with its token:

curl https://console.nace.ai/v1/documents/upload-grants \
  -H "Authorization: Bearer $DREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "path": "invoices/invoice.pdf", "ttl_seconds": 600 }'
# {"workspace_id":"...","upload_url":"https://.../v1/workspaces/.../files","token":"...","expires_at":"...","max_bytes":null}

curl "$UPLOAD_URL" \
  -H "X-Upload-Token: $TOKEN" \
  -F file=@invoice.pdf \
  -F 'metadata={"path":"invoices/invoice.pdf"};type=application/json'

1. The metadata part is required. Add total_size_bytes to it for a file of 32 MiB or more.
2. The upload's answer carries the file under result.file.
3. Pass its workspace_id and file_id as the job's source: {"type": "workspace_file", "workspace_id": "...", "file_id": "..."}.

A grant works once and only for your workspace, so you can hand it to a browser or another client without sharing your API key. From a browser, send the upload with credentials: "omit" and only the X-Upload-Token header.

Large filesCopy Anchor Link

POST /v1/documents/upload-sessions with path and total_size_bytes opens a resumable upload. Its answer gives session_token, chunk_size, total_parts and upload_session_url. Send each call below straight to the document service, with X-Upload-Token: <session_token>:

1. PUT {upload_session_url}/parts/{n} for each part, numbered from 0.
2. POST {upload_session_url}/complete?wait_seconds=60 with an Idempotency-Key. It assembles the file in the background and answers 202 while it runs.
3. Repeat step 2, with the same key, until it answers 200. Its result.file carries the workspace_id and file_id to use as a workspace_file source.

GET {upload_session_url} shows which parts arrived, and DELETE {upload_session_url} aborts the upload. A completed session answers complete with the same file again.