PerceptionDocs

Create an upload grant

A short-lived token for uploading one file straight to the document service, into your account's own workspace (created on first use). Free, and works at any balance.

POST
/v1/documents/upload-grants
  1. POST the file to upload_url as multipart form data, with the header X-Upload-Token: <token> and two parts:
    • file: the file.
    • metadata (required): JSON such as {"path": "..."}. Add total_size_bytes for files of 32 MiB or more.
  2. The upload's response 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":...}.

The bytes never pass through Drex, so there is no 4.5 MB limit.

Other errors (500, 502, 503, 504, 529) are on Errors.

Authorization

bearerAuth
AuthorizationBearer <token>

Your API key from the dashboard's API Keys page: nace_sk_ followed by 43 URL-safe characters (A-Z, a-z, 0-9, _ and -), shown once when you create it. Send it as Authorization: Bearer nace_sk_... Any other value returns 401 authentication_error. An account can hold at most 3 active keys.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/documents/upload-grants" \  -H "Content-Type: application/json" \  -d '{}'
{  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",  "upload_url": "http://example.com",  "token": "string",  "expires_at": "2019-08-24T14:15:22Z",  "max_bytes": 0}

Get a job artifact GET

A file the job produced (parse images, transcripts, ground crops, converted files), its request echo, or its events stream, at the path the job body links to.

Start a chunked upload POST

A resumable upload of a large file into your account's workspace, in parts of chunk_size bytes.