Skip to content
nexdoc.design Docs

Files API

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

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

Allowed content_type: image/png, image/jpeg, image/gif, image/webp, image/heic, image/heif, image/svg+xml, application/pdf, text/markdown, text/plain, text/csv, application/json. Anything else (including Office formats) is 400. The worker normalizes uploads per run (exotic images → PNG, PDF → page PNGs + text, CSV/JSON/MD/TXT → content.md; brand-kit JSON → brand-kit.json). You may also 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 }