better-i18n.com
开发者文档帮助中心更新日志

Calling APIs

本页内容

Send the installation token as the Bearer token for partner API endpoints.

Identity #

Use the OAuth access token to check who connected and which Better i18n account it belongs to:

Bash
curl https://api.better-i18n.com/api/oauth-client/me \
  -H "Authorization: Bearer <access_token>"

Organizations and projects #

List organizations the user granted access to:

Bash
curl https://api.better-i18n.com/api/oauth-client/organizations \
  -H "Authorization: Bearer bi_oat_d7ab12..." \

List projects in an organization:

Bash
curl https://api.better-i18n.com/api/oauth-client/organizations/<org_id>/projects \
  -H "Authorization: Bearer bi_oat_d7ab12..."

Create a CDN-backed project in the granted organization:

Bash
curl -X POST https://api.better-i18n.com/api/oauth-client/v1/projects \
  -H "Authorization: Bearer bi_oat_d7ab12..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing site", "slug": "marketing-site", "sourceLanguage": "en" }'

Read project details:

Bash
curl https://api.better-i18n.com/api/oauth-client/v1/projects/<project_id> \
  -H "Authorization: Bearer bi_oat_d7ab12..."

Add a target language:

Bash
curl -X POST https://api.better-i18n.com/api/oauth-client/v1/projects/<project_id>/languages \
  -H "Authorization: Bearer bi_oat_d7ab12..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "de" }'

Translation keys and values #

Dedicated REST endpoints for keys, translations, publishing, glossary, and Content CMS writes are in active partner rollout. Until they are available in your account, use the Better i18n MCP tools with the same bi_oat_ token for translation key and value operations. See MCP integration.

Scope enforcement #

If your token is missing the required scope, you'll get:

JSON
{
  "error": "missing_scope",
  "required": "translations:publish"
}

Do not retry this. The user needs to re-authorize with the wider scope. See scopes for the full mapping.

Identity endpoint #

/api/oauth-client/me accepts either the OAuth access token or a bi_oat_ installation token in the Authorization header — it doesn't require any scope. All other resource endpoints (organizations, projects, keys, etc.) require an installation token. Use /me right after exchange to confirm the connection succeeded before minting an installation token.

Handling revocation #

When a token is revoked, API calls return:

JSON
HTTP/1.1 410 Gone
{ "error": "grant_revoked" }

Treat this as a first-class state in your UI — show a "Reconnect" prompt, don't retry.

Next step #

See the scope reference for what each scope unlocks.