API and MCP reference

GET /api/{project_id}/latest/{language}/{namespace_key}

Read a namespace in one language (the CI fetch)

The flat { key: value } map for one namespace and language, served from a cache that writes refresh. Responses carry an ETag; send If-None-Match on repeat fetches and an unchanged body answers 304 Not Modified with no content. Cache the file in your build — a build only sees what existed when it ran.

Auth: Project API key or Personal access token

Responses

{
  "greeting": "Hei",
  "btn.save": "Lagre"
}

curl

curl -X GET \
  -H "Authorization: Token token=YOUR_API_KEY" \
  https://app.bemywords.org/api/PROJECT_ID/latest/nb/common

POST /api/missing/{project_id}/latest/{language}/{namespace_key}

Report missing keys

Adds keys the namespace does not have yet and leaves every existing translation untouched. The runtime safety net: when your i18n library meets a key it cannot find, post it with its source value and it appears for translation without waiting for the next build. Non-destructive, so safe to call from anywhere with a read/write key you control. Throttled with the other writes at 300 a minute per project.

Auth: Project API key or Personal access token — read/write

Request body

{
  "welcome.title": "Welcome to BeMyWords",
  "welcome.cta": "Get started"
}

Responses

{
  "error": "invalid_translation",
  "message": "Translation value starts with a script URL"
}

curl

curl -X POST \
  -H "Authorization: Token token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"welcome.title":"Welcome to BeMyWords","welcome.cta":"Get started"}' \
  https://app.bemywords.org/api/missing/PROJECT_ID/latest/nb/common

PUT /api/sync/{project_id}/latest/{language}/{namespace_key}

Declare the full key set (CI)

Declares every key that exists in your source for this namespace. Keys in the payload are created or unhidden; keys the server has that you did not send are marked hidden so translators stop seeing them — only when language is the project's source language, and nothing is ever deleted. A first push to an unknown namespace creates it.

preserve_source_values (default true) decides who owns an edit to an existing source value: with the default, edits made in BeMyWords survive your syncs and only new keys take their value from the payload. Send false when the code is canonical — changed values are overwritten and listed in source_value_changed, and per-language locks on those keys clear so translators re-review.

dynamic_key_prefixes protects keys generated at runtime (error codes, for instance) from being hidden. partial: true marks one chunk of a larger file — nothing is hidden — for namespaces of about a thousand new keys and more, since a request has a 25-second budget; finish with one full sync. A flat { key: value } body is also accepted.

Auth: Project API key or Personal access token — read/write

Request body

{
  "translations": {
    "welcome.title": "Welcome",
    "welcome.cta": "Get started",
    "btn.save": "Save"
  },
  "dynamic_key_prefixes": [
    "errors.server."
  ],
  "preserve_source_values": true,
  "partial": false
}

Responses

{
  "summary": {
    "total_incoming": 3,
    "created": 2,
    "hidden": 1,
    "unhidden": 0,
    "source_value_changed": 0,
    "unchanged": 1
  },
  "created": [
    "welcome.title",
    "btn.save"
  ],
  "unhidden": [],
  "hidden": [
    "legacy.unused_key"
  ],
  "source_value_changed": []
}

curl

curl -X PUT \
  -H "Authorization: Token token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"translations":{"welcome.title":"Welcome","welcome.cta":"Get started","btn.save":"Save"},"dynamic_key_prefixes":["errors.server."],"preserve_source_values":true,"partial":false}' \
  https://app.bemywords.org/api/sync/PROJECT_ID/latest/en/common

PUT /api/overwrite/{project_id}/latest/{language}/{namespace_key}

Overwrite values in one language

Force-sets the value of keys that already exist in this language. Keys it does not know come back in not_found and nothing is created — use missing or sync for that. refreshed lists keys whose value you sent unchanged while the source had moved: the row is stamped current so /api/stale stops flagging it, which is how you say "still correct for the new source" without rewriting it.

Auth: Project API key or Personal access token — read/write

Request body

{
  "welcome.title": "Welcome back",
  "btn.save": "Save changes"
}

Responses

{
  "summary": {
    "total_incoming": 3,
    "updated": 1,
    "refreshed": 1,
    "unchanged": 0,
    "not_found": 1
  },
  "updated": [
    "welcome.title"
  ],
  "refreshed": [
    "btn.save"
  ],
  "unchanged": [],
  "not_found": [
    "missing.key"
  ]
}

curl

curl -X PUT \
  -H "Authorization: Token token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"welcome.title":"Welcome back","btn.save":"Save changes"}' \
  https://app.bemywords.org/api/overwrite/PROJECT_ID/latest/nb/common

GET /api/stale/{project_id}/latest/{namespace_key}

List translations the source has outrun

Keys whose translation in lang was made against an older source value than the current one. Rows that predate source versioning are included unless you pass include_null=false. Close the loop with overwrite (a human value) or retranslate (AI).

Auth: Project API key or Personal access token

Responses

{
  "lang": "sv",
  "stale_keys": [
    "welcome.title",
    "btn.save"
  ]
}

curl

curl -X GET \
  -H "Authorization: Token token=YOUR_API_KEY" \
  https://app.bemywords.org/api/stale/PROJECT_ID/latest/common?lang=sv

POST /api/retranslate/{project_id}/latest/{language}/{namespace_key}

Retranslate keys with the project's AI

Regenerates the translations of the listed keys in language with the project's configured model and rules, and stores the result. Ten keys per call — the model runs inside the request — so chunk larger sets. Sixty calls a minute per project. Spend shows on Usage like any other AI work; on a BYOK workspace it runs on your key.

Auth: Project API key or Personal access token — read/write

Request body

[
  "welcome.title",
  "btn.save"
]

Responses

{
  "lang": "sv",
  "retranslated": {
    "welcome.title": "Välkommen tillbaka",
    "btn.save": "Spara ändringar"
  },
  "skipped_missing_source": [],
  "failed": []
}

curl

curl -X POST \
  -H "Authorization: Token token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["welcome.title","btn.save"]' \
  https://app.bemywords.org/api/retranslate/PROJECT_ID/latest/nb/common

POST /api/{project_id}/sync_page_strings/{namespace_key}

Register page text as source strings

For sites where the source text is the key — hosted builders and the Embed script. Creates a source row per string that is new to the namespace, key equal to value, and never touches an existing row. Creates the namespace on first use. Sixty calls a minute per project.

Auth: Project API key or Personal access token — read/write

Request body

{
  "source_strings": [
    "Book a demo",
    "Read the guide"
  ]
}

Responses

{
  "created": 2,
  "skipped": 0,
  "source_language": "en"
}

curl

curl -X POST \
  -H "Authorization: Token token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_strings":["Book a demo","Read the guide"]}' \
  https://app.bemywords.org/api/PROJECT_ID/sync_page_strings/common

POST /api/{project_id}/redeploy

Refresh the cache and dispatch the project's redeploy

Refreshes the project's translation cache, then dispatches the GitHub Actions workflow configured under Connect → Redeploy, so a build-time site rebuilds with fresh strings. An audited human action: personal access tokens only, a project key answers 403 pat_required. Every attempt is listed under Recent redeploys on the Connect page.

Auth: Personal access token

Responses

{
  "ok": true,
  "dispatched_at": "2026-07-28T12:00:00Z"
}

{
  "error": "pat_required"
}

{
  "ok": false,
  "error": "not_configured"
}

curl

curl -X POST \
  -H "Authorization: Bearer pat_…" \
  https://app.bemywords.org/api/PROJECT_ID/redeploy

GET /api/me

The token's owner and what it reaches

A project token answers with its one project; a workspace token (pat_ws_…) answers with the workspace and every active project in it. The cheapest way to check a token before wiring it anywhere.

Auth: Personal access token

Responses

{
  "user": {
    "id": "6f1c…",
    "email": "you@example.com"
  },
  "project": {
    "id": "4d1e…",
    "title": "Marketing site",
    "source_language": "en",
    "enabled_languages": [
      "nb",
      "sv"
    ],
    "editable_languages": [
      "nb",
      "sv",
      "da"
    ],
    "namespaces": [
      "common",
      "marketing"
    ],
    "deploy_configured": true,
    "integration_type": "astro",
    "auto_translate_languages": [
      "nb",
      "sv"
    ]
  }
}

curl

curl -X GET \
  -H "Authorization: Bearer pat_…" \
  https://app.bemywords.org/api/me

POST /api/mcp

MCP — the whole workspace

Workspace tokens only (pat_ws_…). JSON-RPC 2.0 in the body, one call per POST, Accept: application/json. No session is minted — every request stands alone, which is what lets it run on many dynos; tools/list and tools/call work without a prior initialize. Tools name a project per call. Send the header X-BeMyWords-Read-Only: 1 and only the read tools are offered.

Auth: Personal access token

Request body

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Responses

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_projects"
      }
    ]
  }
}

curl

curl -X POST \
  -H "Authorization: Bearer pat_…" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://app.bemywords.org/api/mcp

POST /api/{project_id}/mcp

MCP — one project

Any token for the project: an API key or a personal access token. The same protocol and tools as the workspace endpoint, with the project fixed, so a builder connected here never names one. A read-only API key is offered read tools only, whatever the client declares.

Auth: Project API key or Personal access token

Request body

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_project_status",
    "arguments": {}
  }
}

Responses

curl

curl -X POST \
  -H "Authorization: Token token=YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_project_status","arguments":{}}}' \
  https://app.bemywords.org/api/PROJECT_ID/mcp

POST /api/embed/resolve

Host → project (the first-load handshake)

Called once by the Embed script with the workspace's public token and the page's host. Answers the project for that host, creating it on first sight — the zero-config install. Thirty calls a minute per IP. Answers 503 while the emergency switch is off.

Auth: No token — called from the visitor's browser

Request body

{}

Responses

{
  "project_id": "4d1e…"
}

curl

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://app.bemywords.org/api/embed/resolve

POST /api/embed/{project_id}/harvest

Report page strings the project does not know

The script posts text it found on the page and could not translate — up to fifty strings a call, two to five thousand characters each — and they become source rows, key equal to value. Always answers 204, also when the origin is not permitted or the project is not in Embed mode; nothing about the outcome is disclosed to a page. Sixty calls a minute per IP.

Auth: No token — called from the visitor's browser

Request body

{
  "strings": [
    "Book a demo",
    "Read the guide"
  ]
}

Responses

curl

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"strings":["Book a demo","Read the guide"]}' \
  https://app.bemywords.org/api/embed/PROJECT_ID/harvest

GET /api/{project_id}/dictionary/{language}/{namespace_key}

The public swap dictionary

A flat { text_on_the_page: text_it_should_say } map for one namespace and language, read by the script on every page view and swapped into the DOM. Two kinds of entry, and which you get depends on src:

• source → current — for a page still showing the text as authored.
• prior → current — for a page whose translations were baked into its build before someone corrected them. Present only while the project has keep my site up to date between deploys on.

A regional tag falls back to its base language (en-GB → en). Carries an ETag that varies with src; unchanged answers 304. Refused with 403 from an origin the project has not allowed. Counts as visitor demand for the language. 240 calls a minute per IP.

Auth: No token — called from the visitor's browser

Responses

{
  "Book a demo": "Bestill en demo",
  "Read the guide": "Les guiden"
}

curl

curl -X GET \
  https://app.bemywords.org/api/PROJECT_ID/dictionary/nb/common

GET /api/{project_id}/changes/{language}/{namespace_key}

What changed since a moment

Translations that changed after since (ISO 8601, at most seven days back), each with the prior values that are safe to swap for the current one. Used by the editor and by ?bw-live previews. A visitor's page never calls it: the dictionary carries recent prior values, so one fetch both translates the page and corrects anything stale on it. At most 500 changes; truncated says when there were more. 120 calls a minute per IP.

Auth: No token — called from the visitor's browser

Responses

{
  "since": "2026-09-12T06:00:00Z",
  "server_time": "2026-09-12T15:40:12Z",
  "changes": [
    {
      "key": "welcome.title",
      "current": "Velkommen tilbake",
      "priors": [
        "Velkommen"
      ]
    }
  ],
  "truncated": false
}

curl

curl -X GET \
  https://app.bemywords.org/api/PROJECT_ID/changes/nb/common?since=2026-09-12T06:00:00Z

POST /api/{project_id}/install_ping

We see your site

One ping per browser session so the dashboard can show that the script is live, kept seven days, no analytics. Sixty a minute per IP.

Auth: No token — called from the visitor's browser

Responses

curl

curl -X POST \
  https://app.bemywords.org/api/PROJECT_ID/install_ping

GET /api/{project_id}/public_info

Languages for the switcher

The project's source language, the languages live for visitors, and whether the footer switcher shows — what the script needs to draw the dropdown without baking a list into the tag. Cached five minutes. 120 calls a minute per IP.

Auth: No token — called from the visitor's browser

Responses

{
  "source_language": "en",
  "enabled_languages": [
    "nb",
    "sv"
  ],
  "show_switcher": true,
  "capabilities": {
    "mode": "auto",
    "jit_harvest": true,
    "auto_apply": true
  }
}

curl

curl -X GET \
  https://app.bemywords.org/api/PROJECT_ID/public_info