Automate Transept with the API

Create a personal API key under Settings → Developer. It’s available on every plan, including Free — there’s no separate gate, your word balance is what limits usage. Give the key a name, optionally set an expiry, and copy the secret when it’s shown: it appears once and can’t be retrieved later. Revoke a key anytime from the same page.

Requests authenticate with the key in an Authorization: Bearer tsk_live_… header — header only, never in a URL.

Six short calls take you from an API key to translated output. Only the translation run itself costs words; estimates are free, and a retried call with the same Idempotency-Key returns the original result instead of billing twice.

The same calls with more commentary live at transept.ai/developers. The localization API guide walks through the rest: string catalogs, email templates, glossaries, teams, and review gates.

export KEY="tsk_live_…"                          # minted under Settings → Developer
BASE="https://app.transept.ai/api/public/v1"

# 1. Check the key: your account, its permissions, your word balance
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2. Create a document; Transept creates one language version per target
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome…", "content_type": "markdown",
       "source_language": "en", "target_languages": ["de", "fr", "uk"]}'

# 3. Estimate: the word cost, free, with no side effects
curl -s -X POST $BASE/group-runs/estimate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'

# 4. Run: the same body starts it
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-1" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'

# 5. Wait: poll for per-language progress (or get pushed an event; see below)
curl -s $BASE/group-runs/<group-run-id> -H "Authorization: Bearer $KEY"

# 6. Read each language back in the format you need (the table below lists them)
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

Create a document from raw text, HTML, or markdown, or upload a file — the same formats the app accepts. You can also import a string table (.tstrings.json): a structured format for UI text or game strings, where each string is a unit with a stable key and its own context — a note on what it is, where it appears, a character limit, and what its placeholders mean. All of that reaches the model, placeholders like {name} are protected from being dropped or renamed, and plurals are expanded per language (one English form becomes two in German, four in Ukrainian). Any translations the file already carries are imported as-is, free, and feed translation memory straight away.

A group run translates into several languages at once. Name the document, the workflow or template to run, and the target languages; Transept creates any missing language versions and runs the workflow on each. One id tracks the whole thing — poll it for each language’s progress and whether it’s waiting on a review.

For repeat runs, re-submit a string table’s current file and Transept works out what changed: unchanged strings keep their translations (and any review already done), and the run touches only the new or genuinely changed units — the API side of Run only what changed. The whole keyed loop, from first import to delta runs, is Localize a string catalog over the API.

Instead of polling, register a URL and Transept pushes an event when a run finishes or fails, when a review is ready to look at, when an upload finishes processing, and when an export is ready. Every delivery carries an HMAC-SHA256 X-Transept-Signature: t=…,v1=… header so your receiver can verify it really came from us, and a failing endpoint is retried with backoff before it’s switched off.

# register once; every matching event is POSTed to your URL, signed
curl -s -X POST $BASE/webhooks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/transept-events",
       "events": ["group_run.completed", "run.gate_ready", "run.failed"]}'
# → the endpoint, including its ONE-TIME secret; verify X-Transept-Signature with it

A workflow can also run itself from a Notion database automation: point the automation’s webhook at the trigger URL and Transept runs the workflow on the page that changed. The catch is that a Notion webhook never carries the page’s content — it only says which page fired. Transept reads that page through your Notion connection, so two things both have to be in place, or every fire is turned away with an access error and the trigger card shows a “couldn’t read the Notion page” note:

• Connect Notion in Transept — under Settings → Integrations. That’s the one-time OAuth link that lets Transept read on your behalf.
• Share the source database with the integration inside Notion — open the database (or page), click its ••• menu, choose Connections, and add Transept. Connecting Notion in Settings doesn’t grant access to a specific database on its own; without this step the connection is live but the page stays unreadable.
• Fire on a property change, not just a body edit. Notion automations trigger on property changes (and page adds), so editing a page’s body alone may not fire anything. The reliable pattern is a Status property the automation watches — flip it (e.g. to “Ready to translate”) and that change is what calls the trigger.

The full endpoint list is published as an OpenAPI spec you can import into n8n, Zapier, or a code generator: browse the interactive reference, or fetch the raw JSON. Prefer a walkthrough? transept.ai/developers has the quickstart with copy-paste examples, and the localization API guide covers the whole loop in depth. Runs started over the API bill words exactly like the in-app editor.

Yes — Transept has an MCP endpoint AI assistants connect to: https://app.transept.ai/api/public/v1/mcp. Connecting uses standard OAuth: add the URL to Claude Code, Claude Desktop, Cursor or any MCP client, and a browser window asks you to approve the access — no key to paste (an API key as a Bearer header still works for CI and headless setups). The assistant then has tools for the whole loop: import documents, run workflows across languages, manage glossaries and style guides, query translation memory, read results back. Two guardrails are built in: every tool respects the permissions you granted, and anything that would spend words first answers with the word estimate — the assistant has to confirm explicitly before a run starts, so an agent can never bill you by accident. Ready-made setup snippets for each client are on the Integrations page in the app; the full walkthrough, from consent screen to disconnecting, is Connect your AI assistant.