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: image/png, image/jpeg, image/gif, application/pdf. Do not upload JSON brand kits — put colors and fonts 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.