Transept for developers

Everything the editor does, headless: import, translate across languages with your glossary and translation memory, review, export. One API key, one REST surface, one MCP endpoint for AI assistants. API, MCP and webhooks come with the Starter and Pro plans; the Free plan does not include them.

Reference: Swagger UI · OpenAPI JSON (import it into n8n, Zapier, or a code generator).

Prefer prose? The long-form walkthrough of everything below is the localization API guide.

1 · Get a key

Settings → Developer in the app (API keys come with Starter and Pro). Pick the key’s permissions (full access, or per-area read/write), copy the secret once. The API is key-only: session logins don’t work on it, and a key can never mint more keys. Team owners can mint team keys that survive people leaving and spend the team credit pool.

export KEY="tsk_live_…"
curl -s https://app.transept.ai/api/public/v1/me -H "Authorization: Bearer $KEY"

2 · Import a document

curl -s -X POST https://app.transept.ai/api/public/v1/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Newsletter", "content": "# Hello…", "content_type": "markdown",
       "target_language": "de", "target_languages": ["pl", "es"]}'

Three shapes of input, by what you have: prose (an email body, an article: inline markdown/HTML/text as above, or a payload webhook, below), files (DOCX, HTML, CSV, PO, XLIFF; multipart to POST /public/v1/documents/upload, and DOCX round-trips with styling reinjected on export), and string tables (.tstrings.json to POST /public/v1/documents/import-strings: keyed units with context, protected placeholders, per-language plural expansion). Translations a file already carries seed as active for free and feed translation memory immediately.

3 · Run a workflow across languages

Discover ids with GET /public/v1/workflows (or /workflow-templates), price first, then run: estimates are free floor–ceiling ranges, and the ceiling is released back as the run settles.

curl -s -X POST https://app.transept.ai/api/public/v1/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-2026-08-04-1" \
  -d '{"document_id": "…", "workflow_id": "…", "target_languages": "all"}'

Poll GET /public/v1/group-runs/{id}, or skip polling entirely: register a webhook and receive signed group_run.completed events.

A workflow step set to “wait for review” parks the run: GET /runs/{id} reports gate_pending: true with a digest of what the review found. POST /runs/{id}/gate/approve continues downstream steps (send approved_block_ids, or omit for all) and bills them; …/gate/estimate with the same body prices that first, with no side effects; …/gate/acknowledge dismisses a gate with nothing downstream. A gate never continues without an explicit approve, from your script or a person; there is no pre-approval flag.

4 · Read the results back

curl -s "https://app.transept.ai/api/public/v1/documents/{master}/content?format=strings" \
  -H "Authorization: Bearer $KEY"

Glossaries, style guides, translation memory

The consistency layer is fully scriptable, so headless onboarding never needs a UI visit: create the resources, attach them to a document, run.

Create by hand, or generate

curl -s -X POST https://app.transept.ai/api/public/v1/glossaries \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Product terms", "source_language": "en",
       "terms": [{"source_term": "Transept", "target_term": "Transept",
                  "do_not_translate": true}]}'

Or let AI build them from a document you already have: POST /glossaries/{id}/auto-build and POST /styleguides/generate (each with a free …/estimate twin). Both bill credits and both require auto_apply: true over the API; there is no interactive review step headless, so the result commits on completion. They return a generation-job id; poll GET /generation-jobs/{id}.

Attach, then every run uses them

curl -s -X PATCH https://app.transept.ai/api/public/v1/documents/{id}/translation-settings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"glossary_ids": ["…"], "styleguide_version_ids": ["…"]}'

Style guides attach by active version id (read it from GET /styleguides/{id}); an explicit [] detaches. Both can also be passed straight to POST /documents at create time.

Memory is automatic

Every completed translation is indexed; future runs reuse your own phrasing without being asked. Query it (POST /translation-memory/query, free hybrid retrieval), seed it from a TMX/XLIFF you already have (POST /translation-memory/import, free), export the lot (GET /translation-memory/export-tmx). A team key shares the team’s memory automatically.

Update only the delta

The reason this API is cheap on a living corpus: you never diff by hand.

String tables: re-submit the whole current file to POST /documents/{id}/import-strings; the server diffs by unit id and returns delta_block_ids. Feed that object verbatim as a group run’s block_ids and only those blocks translate; unchanged strings keep their translations and their review state. Fixing one string in a file of hundreds costs one string.

# 1. Re-import the current corpus (the server owns the diff):
curl -s -X POST https://app.transept.ai/api/public/v1/documents/{master}/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @strings.tstrings.json
# → { units: {added, changed, unchanged, removed}, delta_block_ids: {…} }

# 2. Run exactly the delta:
curl -s -X POST https://app.transept.ai/api/public/v1/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "{master}", "workflow_id": "…",
       "target_languages": "all", "block_ids": { …delta_block_ids… }}'

Prose documents: when the source changed, POST /documents/{id}/resync-source re-aligns blocks (unchanged blocks keep their translations, changed ones go stale), then run with only-updated behavior to touch just those. Resync re-parses the stored source, so edit sources through the import path, not by patching individual blocks.

Teams

A team key bills the team pool and inherits the team’s projects, glossaries, style guides, and translation memory. Create documents inside the team by passing a team project’s project_id (list them with GET /projects); everything else (runs, attach, readback) is identical to personal use. Team keys are minted by a team owner in the app, a human action by design.

Send content in, no request at all

A workflow’s incoming trigger can take the request body AS the content: point your email platform, Zapier/n8n, or CI at the trigger URL and POST raw markdown/HTML/text (or JSON {"content": "…"}). Transept creates or updates the document and runs the workflow; retries dedupe for 24 hours, and an external_id in the JSON gives you exact control.

curl -s -X POST https://app.transept.ai/api/public/v1/hooks/<trigger-secret>   -H "Content-Type: application/json"   -d '{"content": "<h1>Welcome!</h1>", "content_type": "html",
       "external_id": "welcome-v4"}'
# → 202 { run id, document_id, created }

AI assistants (MCP)

The same capabilities as agent tools, at https://app.transept.ai/api/public/v1/mcp (streamable HTTP). Connecting uses OAuth: your assistant opens a browser sign-in the first time, no key to paste. Tools respect the granted permissions, and anything that spends credits answers with the estimate first; the agent must confirm explicitly.

claude mcp add --transport http transept https://app.transept.ai/api/public/v1/mcp

Headless environments (CI) can use an API key instead: --header "Authorization: Bearer $KEY". The connection shows up as a revocable key under Settings → Developer either way. Binary formats (docx/xliff/tmx, file uploads) stay REST-only; the MCP tools point there.

The parts you’d otherwise build yourself

• Webhooks: HMAC-signed (Stripe scheme), 8 retries with backoff, a readable delivery log, rotation.
• Idempotency: an Idempotency-Key on job-creating POSTs makes retries safe for 24 h.
• Delta billing: re-imports diff server-side; translated-already content seeds free and feeds translation memory.
• Review gates: a “wait for review” step parks the run until a human (or your script) approves; automation can’t skip it.

Going deeper: the localization API guide (long-form, end to end) · help center: Automate Transept with the API · Connect your AI assistant (MCP) · Localize a string catalog · Webhook triggers