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 DocMark-managed cloud API is in private preview (by invitation). The same API runs today in the self-managed options — on-prem and your own cloud tenant. See deployment modes. Request access via hello@docmark.md.

Authentication

Every request carries a bearer token scoped to one tenant:

Authorization: Bearer <your-api-token>

Tokens are issued per tenant from the admin console. Any auth failure returns a uniform 401 (no distinction between missing, malformed, or revoked — no oracle).

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://api.docmark.md/v1/jobs \
  -H "Authorization: Bearer $DOCMARK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "brochure",
        "topic": "Q3 workplace strategy for a national occupier",
        "pages": 2
      }'
# -> { "job_id": "job_...", "state": "pending", "contract_version": "1.9.0" }

Common fields: type (deck · docx · xlsx · brochure · newsletter · video), topic or structured content, optional theme/profile (which brand + which sanctioned look), pages (brochure, 1–4), charts (deck), sheets (xlsx), items (newsletter). Full field list on request.

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://api.docmark.md/v1/jobs/job_... -H "Authorization: Bearer $DOCMARK_TOKEN"
# -> { "state": "done" | "pending" | "failed", "findings": [...], "provenance": {...}, ... }

• state: "done" — the artifact is ready; fetch it below.
• state: "failed" — the job carries findings: the machine-readable reason it was withheld (e.g. a verification gate that fired). Fix and resubmit.
• provenance — on a done job, a manifest of exactly which brand version, design profile, and engine produced the artifact.

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 (a sliding window). Bearer-auth only; a dedicated read rate limit that never consumes your submit budget.

The job contract is versioned

Every response echoes contract_version (currently 1.9.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.

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