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.

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.

A naming note: the billing unit is words everywhere a person reads, but API response fields keep the historical name credits (estimatedCredits, spendable). Same quantity; don’t be thrown.

1 · Get a key

Settings → Developer in the app. 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 word 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); …/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 words 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 words 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