API reference
Conventions for the NexDoc Design REST API — base URL, auth, status codes, and run lifecycle.
Base URL: https://api.nexdoc.design
Version prefix: /v1
Agents calling this API should follow the REST skill (endpoint catalog).
Authentication
Authorization: Bearer nxd_live_...Keys are created at app.nexdoc.design/keys. See Authentication.
Content types
| Use | Header / encoding |
|---|---|
| JSON bodies | Content-Type: application/json |
| One-shot runs with files | multipart/form-data |
| Presigned file PUT | Content-Type matching the declared upload type |
Allowed uploads: image/png, image/jpeg, image/gif, application/pdf only.
Common status codes
| Code | Meaning |
|---|---|
200 / 201 | Success (201 on job create) |
202 | Run accepted (queued) |
400 | Validation / unsupported upload type |
401 | Missing or invalid bearer |
402 | Insufficient balance / past due |
403 | Missing scope |
404 | Job, run, or file not found |
409 | Conflict (e.g. cancel terminal run) |
503 | Queue unavailable — retry once after 10 seconds |
Error body:
{ "detail": "human-readable message" }Run statuses
| Status | Terminal? |
|---|---|
queued | No |
preparing | No |
running | No |
validating | No |
uploading_outputs | No |
completed | Yes |
failed | Yes |
cancelling | No |
cancelled | Yes |
Persist job_id and run_id from the 202 create-run response, then poll GET /v1/jobs/{job_id}/runs/{run_id} until a terminal status — or set notify_email: true / POST …/notify-email if you cannot wait. Simple layouts typically finish in 1–5 minutes; decks, reports, and image-heavy work commonly take 10–20 minutes. webhook_url is accepted but delivery is not guaranteed.
Failed runs are not charged. Show error and log_tail, then retry once.