Skip to content
nexdoc.design Docs

Files API

Presigned uploads, file metadata, and delete — attach logos, images, and PDFs to a NexDoc Design run.

Scopes: files:rw (write), files:read (read)

Allowed content_type: image/png, image/jpeg, image/gif, application/pdf. Anything else (svg, webp, json, brand-kit.json) is 400. Put brand colors and fonts in instructions.

For most scripts, skip this API and attach files as multipart files on create run. Use presigned upload when bytes live on a server, when reusing one asset across many runs, or when the multipart body would be large.

POST/v1/files/request-upload

code
{
  "filename": "logo.png",
  "content_type": "image/png",
  "size_bytes": 18432
}

size_bytes must be ≥ 1.

code
{
  "file_id": "file_...",
  "upload_url": "https://...",
  "uri": "s3://...",
  "expires_at": "..."
}

Then PUT the raw bytes to upload_url (not the NexDoc API host), with Content-Type matching the declared type.

GET/v1/files/{file_id}

Returns status (pending_upload → ready), filename, content_type, size_bytes.

Wait until ready before referencing the file_id in a JSON run (files / assets).

DELETE/v1/files/{file_id}

code
{ "file_id": "file_...", "deleted": true }