API Reference

DocMark’s /v1 API turns your content into a branded, verified document — deck, Word, Excel, brochure, or newsletter — in your (or your customer’s) corporate brand. Your software authors the content; DocMark renders the design deterministically and verifies the output before returning it.

Availability. The managed cloud API is available now, and API access is included in every plan — /v1 draws on the same monthly render credits. Your workspace’s admins can create and revoke tokens themselves: sign in at app.docmark.md and open API tokens. If you are not an admin, or your workspace has none yet, email hello@docmark.md and we will set one up. The same API also runs self-managed — on-prem or your own cloud tenant (deployment modes).

Authentication

Every request carries a bearer token scoped to one tenant:

Authorization: Bearer <your-api-token>

Tokens are issued per tenant. An auth failure never distinguishes between missing, malformed and revoked — no oracle — but the status code differs by endpoint: submitting returns 403 ({"error": "invalid or missing API token"}), while GET /v1/usage returns 401. Handle both if you key retry or token-refresh logic on the status code.

Submit a job — POST /v1/jobs

Send a job spec; get back a job id. The request is strictly validated — unknown keys are rejected (so a typo fails loudly instead of silently doing the wrong thing).

curl -sS https://docmark-api.happyriver-6d7d834c.australiaeast.azurecontainerapps.io/v1/jobs \
  -H "Authorization: Bearer $DOCMARK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "theme": "slate",
        "type": "brochure",
        "topic": "Q3 workplace strategy for a national occupier",
        "pages": 2
      }'
# -> { "job_id": "job_...", "state": "pending", "contract_version": "1.18.0" }

Request fields

theme is the only required field. Everything else is optional, and unknown keys are rejected.

The full machine-readable shape, including response types, is in job.schema.json.

type: "video" is a premium, entitlement-gated output: unless your tenant is entitled to video, a video submit is rejected with 402 before it is enqueued (default-deny). Ask us to enable video on your account; all other types are available to any valid token.

Poll status — GET /v1/jobs/{id}

curl -sS https://docmark-api.happyriver-6d7d834c.australiaeast.azurecontainerapps.io/v1/jobs/job_... -H "Authorization: Bearer $DOCMARK_TOKEN"
# -> { "state": "pending" | "processing" | "done" | "failed", "findings": "...", "provenance": {...}, ... }

• state: "pending" | "processing" — still queued or mid-render; keep polling.
• state: "done" — the artifact is ready; fetch it below.
• state: "failed" — the job carries findings: a string, up to 2000 characters, giving the recorded reason the job failed. A verification-gate withhold puts its machine-readable findings JSON here; any other failure (a render error, a rejected spec) puts its reason. Fix and resubmit.
• provenance — on a done job, a manifest of the brand, design profile (if one was selected), and engine that produced the artifact. brand_source says where the brand came from: mount (DocMark’s versioned brand store), baked (the brand built into the worker image) or default. brand_version is set only when brand_source is mount, and is null otherwise. Best-effort: the key is absent when the sidecar was not written (a failed write, older results, custom queues) or cannot be read, so read it defensively rather than assuming it is there.

Fetch the artifact — GET /v1/jobs/{id}/result

Returns the raw bytes with the correct content type (.pptx / .docx / .xlsx / .pdf / .png / .mp4). A 409 means “authorized but not rendered yet — keep polling.”

Submit and wait — POST /v1/jobs:render

A convenience wrapper for short jobs: submits through the same path and blocks until the artifact is ready, returning the bytes directly (?timeout_s=, clamped 5–120, default 90). On timeout it returns 202 and the job keeps running — poll GET /v1/jobs/{id}. Async-only types (video, newsletter, brochure) are rejected here; use the async submit for those.

Usage — GET /v1/usage

Your token’s own tenant render-budget usage: the daily sliding-window count plus your monthly quota (monthly_used, monthly_quota, monthly_unlimited, resets_at). Bearer-auth only; a dedicated read rate limit that never consumes your submit budget.

Rate limits & quotas

Each render debits one credit against your monthly quota (Individual 20, Studio 50, Team 300), with a derived daily burst cap. When a limit is reached, a submit is rejected with 429 before it is enqueued — code credit_exhausted (daily burst) or monthly_quota_reached (monthly quota) — each carrying a Retry-After header and an upgrade_url. Check current consumption with GET /v1/usage.

The job contract is versioned

Every response echoes contract_version (currently 1.18.0). The wire schema is producer-owned and pinned by conformance tests, so your integration won’t silently break — additive fields bump the minor version, and the schema is published for codegen: job.schema.json.

The verification promise

DocMark withholds a deliverable that fails its structural/visual gates rather than shipping a broken one. A withheld job fails with findings your agent or code can act on — the same loop a human would run, automated. This is the difference between “an AI made a slide” and “a verified, on-brand document your customer can send.”

Next: connect your AI agent over MCP · deployment modes & where the API runs · request access