Your first document

Generate a multi-page report from markdown and images, then export a PDF.

This guide walks through a realistic flow: turn a markdown report (plus logos and figures) into a designed PDF.

Choose a format

For long-form narrative with pages, use report. See Formats for alternatives (proposal, whitepaper, slide-deck, …).

Option A — One-shot multipart (simplest)

Upload content and assets in a single request. Image paths in markdown like images/chart.png are rewritten to assets/chart.png automatically when filenames match.

code

export NXD_API_URL=https://api.nexdoc.design
export NXD_API_KEY=nxd_live_...

JOB=$(curl -sS -X POST "$NXD_API_URL/v1/jobs" \
  -H "Authorization: Bearer $NXD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Career Navigator Report"}' | jq -r .job_id)

RUN=$(curl -sS -X POST "$NXD_API_URL/v1/jobs/$JOB/runs" \
  -H "Authorization: Bearer $NXD_API_KEY" \
  -F "format=report" \
  -F "instructions=Publication-grade print report. Preserve all section headings and figures. Use the provided logos." \
  -F "content=@./report.md;type=text/markdown;filename=content.md" \
  -F "files=@./logo-dark.png;type=image/png;filename=logo-dark.png" \
  -F "files=@./logo-white.png;type=image/png;filename=logo-white.png" \
  -F "files=@./images/chart.png;type=image/png;filename=chart.png")

echo "$RUN" | jq
RUN_ID=$(echo "$RUN" | jq -r .run_id)

Save job_id and run_id immediately. A report commonly takes 10–20 minutes. Pass notify_email=true if you cannot poll.

Allowed upload types for files include images (png, jpeg, gif, webp, heic, svg), PDF, and text (md, txt, csv, json). Office formats are rejected. Brand colors and fonts may also go in instructions.

Option B — Presign then JSON

Use this when you already manage files in object storage or reuse the same assets across runs.

POST /v1/files/request-upload → {file_id, upload_url}
PUT raw bytes to upload_url
GET /v1/files/:id until status is ready
POST /v1/jobs/:id/runs with JSON files / assets

Details: Files and assets.

Poll and inspect

code

curl -sS "$NXD_API_URL/v1/jobs/$JOB/runs/$RUN_ID" \
  -H "Authorization: Bearer $NXD_API_KEY" | jq '{
    status, charge_usd, commit_hash, viewer_url, error, log_tail
  }'

Field	Meaning
`status`	`queued` … `completed` / `failed` / `cancelled`
`charge_usd`	Amount billed for this run
`viewer_url`	Interactive preview (when completed)
`commit_hash`	Snapshot id for this version
`log_tail`	Present on many failures — agent output tail for debugging

Export PDF

code

curl -sS -X POST "$NXD_API_URL/v1/jobs/$JOB/export" \
  -H "Authorization: Bearer $NXD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"format\":\"pdf\",\"run_id\":\"$RUN_ID\"}" | jq

code

{
  "job_id": "job_...",
  "format": "pdf",
  "run_id": "run_...",
  "commit_hash": "...",
  "download_url": "https://...",
  "expires_at": "..."
}

Download download_url within the expiry window (~1 hour).

Publish a public URL

code

curl -sS -X POST "$NXD_API_URL/v1/jobs/$JOB/publish" \
  -H "Authorization: Bearer $NXD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"run_id\":\"$RUN_ID\"}" | jq
# → { "public_url", "run_id", "commit_hash" }

Writing good inputs

Input	Tips
content	Facts in clean markdown: headings, lists, tables, real names, numbers, dates, prices. Keep everything the user supplied; invent nothing. Reference images by filename (`![Logo](logo.png)`). NexDoc re-authors for the medium.
instructions	Design brief: audience, specific mood/palette/type, brand tokens inline (`Brand: primary #2563EB, fonts Inter; logo.png in nav`), structure, must-haves. Avoid “modern and professional”. Updates are a diff.
format	Matches the medium. A 15-page narrative → `report`; a pitch → `pitch-deck`.
assets	png/jpg/gif/pdf only, with clear filenames referenced from content.

Next: Updating a design to iterate without starting over.