API quick start

Everything the dashboard and plugins do goes through the control-plane API under /v1. This walk-through uses curl. All values are placeholders: there is no public endpoint yet.

export RL_API_BASE="https://api.example"        # placeholder host
export RL_SECRET_KEY="rl_sec_test_..."          # from the dashboard; shown once; keep it in a secret store

Secret keys stay on servers. Never put an rl_sec_ key in a web page, a mobile app or a repository. Use a test key while experimenting.

1. Create a site#

curl -sS -X POST "$RL_API_BASE/v1/sites" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Idempotency-Key: create-site-1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example shop","sourceLanguage":"en","targetLanguages":["fr","de"],"allowedOrigins":["https://shop.example"]}'

The response contains id and the public siteKey.

2. Submit strings#

curl -sS -X POST "$RL_API_BASE/v1/sites/$SITE_ID/strings" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"text":"Add to cart","kind":"text"},{"text":"Search","kind":"attr","context":"placeholder"}]}'

Up to 1000 items per request. The response returns one key per item (see Strings and keys); identical text always yields the same key.

3. Translate#

curl -sS -X POST "$RL_API_BASE/v1/sites/$SITE_ID/translate" \
  -H "Authorization: Bearer $RL_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"langs":["fr"]}'

This returns 202 with a list of jobs. Poll GET /v1/jobs/{jobId} until state is succeeded or failed. Manual translations you set with PUT /v1/sites/{siteId}/translations/{lang}/{key} are never overwritten by machine runs.

4. Publish#

curl -sS -X POST "$RL_API_BASE/v1/sites/$SITE_ID/publish" \
  -H "Authorization: Bearer $RL_SECRET_KEY" -H "Content-Type: application/json" -d '{"onlyIfChanged":true}'

Publishing builds signed bundles and writes them to every storage target, then updates the manifest last. It is asynchronous: poll the returned job.

5. Export (you own your translations)#

curl -sS "$RL_API_BASE/v1/sites/$SITE_ID/export?format=json" -H "Authorization: Bearer $RL_SECRET_KEY" -o translations.json

Other formats: xliff, po, csv.

Next: API overview for errors, pagination and idempotency, and the API reference.