API and developer tokens
Generate a per-project API token and pull KopiMark copy and translations from your build pipeline via the read-only JSON, CSV, or XML endpoint.
Open as Markdown Full docs bundle
Open this page in
Most teams start by exporting copy as a manual download, then graduate to fetching it on every deploy. The KopiMark read API exists for that second step — your build script asks KopiMark for the current copy, and ships whatever the latest Approved (or whichever statuses you pick) revisions are.
Where the API lives
Every project has its own read-only API endpoint. Tokens are scoped to a single project — so a leaked token can only read that project’s copy, not your whole workspace.
You manage tokens at Project Settings → Developer.
1. Generate a token
-
Open the project and go to Project Settings → Developer.
-
Find the API tokens section and click Generate new token.
-
KopiMark shows the new token once. Copy it now — there’s no way to retrieve it again. The settings page only stores the prefix and the creation date, so you can tell tokens apart later.
-
Store the token in your build environment as a secret (
KOPIMARK_API_TOKENor whatever convention you use). Don’t commit it to source control.
If you lose a token, generate a new one and revoke the old one — KopiMark lets you have multiple active tokens per project, so rotating doesn’t require downtime.
2. Configure the export shape
The Developer page has a format builder that previews the exact URL your client should hit:
- Format —
json,csv, orxml. - Pretty-print — readable JSON; turn off for production.
- Flat shape — a flat key→value map, vs the default nested shape.
- Language filter — single locale, or empty for all locales.
- Status filter — usually Approved or Shipped only.
The preview pane shows the live URL with every option baked in. Copy that URL as your base.
3. Pull from your build
Hit the URL with your token as a bearer header. The response shape follows your format and options choices.
A few notes:
- Responses include a weak ETag so a build can short-circuit when nothing has changed.
- Tokens are read-only. There’s no write API yet — KopiMark stays the source of truth for editing.
- Rate limits are generous enough for build-time pulls. If you’re hitting this from request-time code, cache aggressively.
Revoking a token
In the same Developer section, each token row has a Revoke action. Revoked tokens stop working immediately. Anyone with the old token sees 401 on their next request.
There’s no grace period, by design. Rotate by generating the new token first, deploying it, and only then revoking the old.
Project export keys
The default export keys are KopiMark’s internal node ids. They’re stable across re-syncs, but they’re not meaningful to a human reader.
If you want named keys like home.hero.headline, you can assign
them per node in the editor. The editor’s text panel has an Export
key field; KopiMark also has a bulk-assign tool that suggests keys
based on the design hierarchy.
Once keys are assigned, your export uses them instead of the internal ids — which means your codebase keys don’t change when a designer restructures the Figma file.
FAQ
Can one API token access multiple projects?
No. Tokens are scoped to a single project by design, so a leaked token can only read that one project’s copy. Generate a separate token for each project your build pipeline needs to read.
Is there a write API for pushing copy back into KopiMark?
Not yet. The API is read-only — KopiMark stays the source of truth for editing, and your build pulls the latest approved copy from it.
What happens to deployed builds if I revoke a token?
They start getting 401s on the next request, immediately. There’s no grace period, so the safe rotation pattern is to generate the new token first, deploy it, and only then revoke the old one.
How aggressively should I cache API responses?
Build-time pulls are fine without extra caching — rate limits are generous for that pattern. If you’re hitting the endpoint from request-time code, cache aggressively and use the weak ETag in responses to short-circuit when nothing has changed.