NaceDocs
DashboardGet an API key
DocumentationAPI ReferenceSDKsCLI

Perception

Create an upload grant

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":...}.

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, sent as Authorization: Bearer nace_sk_...

  • Where: the dashboard's API Keys page. It is shown once, when you create it.
  • Format: nace_sk_ followed by 43 URL-safe characters (A-Z, a-z, 0-9, _ and -).
  • Limit: an account can hold at most 3 active keys.
  • Wrong or missing key: returns 401 authentication_error.

In: header

Request Body

application/json

workspace_idstring

Optional. A workspace from the Workspaces API that this key may use; the file goes into that workspace. Leave it out to upload a file for your document jobs (parse, extract, classify, split, ground).

pathstring

Pin the upload to exactly this path in the workspace.

max_bytesinteger

Refuse uploads larger than this.

Range1 <= value
total_size_bytesinteger

The exact size the upload must have.

Range0 <= value
ttl_secondsinteger

How long the token works.

Range1 <= value <= 3600
Default3600

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/documents/upload-grants" \  -H "Content-Type: application/json" \  -d '{    "path": "invoices/invoice.pdf",    "ttl_seconds": 600  }'
{  "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 the workspace workspace_id names, or, without one, for your document jobs, in parts of chunk_size bytes.