API Reference

Complete reference for the Stringbase REST API. All endpoints require authentication via API key.

Quick Start

Enter your API key to get copy-ready commands. Generate a key in project settings

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys in your project settings.

bash

curl https://stringbase.io/api/v1/translations?env=production&lang=es \
  -H "Authorization: Bearer sb_live_your_api_key"

API keys are scoped to a single project. Each request is automatically associated with the project that owns the key.

Keep your API keys secret. Never expose them in client-side code or public repositories.

Base URL

text

https://stringbase.io/api/v1/

All endpoints are relative to this base URL.

Error Handling

All errors return a consistent JSON structure:

json

{
  "error": {
    "message": "Translation not found",
    "code": "not_found",
    "status": 404
  }
}

Status	Code	Description
400	bad_request	Invalid parameters
401	unauthorized	Missing or invalid API key
403	forbidden	Valid key but insufficient permissions
404	not_found	Resource doesn't exist
429	rate_limited	Too many requests
500	internal_error	Server error

Pagination

List endpoints support page and per_page query parameters. Default: page=1, per_page=50, max 200.

json

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 120,
    "total_pages": 3
  }
}

GET

/translations

Fetch translations for a project, environment, and language. This is the primary OTA endpoint your app calls.

Parameter	Type	Required	Description
env	string	Required	"development" or "production"
lang	string	Required	Language code (e.g., "es")
format	string	Optional	"json" (default), "flat", or "nested"
include_metadata	boolean	Optional	Include status and timestamps per key

curl "https://stringbase.io/api/v1/translations?env=production&lang=es" \
  -H "Authorization: Bearer sb_live_your_api_key"

Production environment only returns translations with status "published". Development returns all statuses.

Response

json

{
  "data": {
    "checkout.success": "Pago exitoso",
    "checkout.cancel": "Pago cancelado",
    "common.save": "Guardar"
  },
  "meta": {
    "project": "My App",
    "environment": "production",
    "language": "es",
    "count": 3,
    "generated_at": "2026-03-28T19:00:00Z"
  }
}

GET

/keys

List all translation keys in the project with pagination.

Parameter	Type	Required	Description
search	string	Optional	Search key names
tag	string	Optional	Filter by tag
page	number	Optional	Page number (default 1)
per_page	number	Optional	Items per page (default 50, max 200)

curl "https://stringbase.io/api/v1/keys?search=checkout&page=1" \
  -H "Authorization: Bearer sb_live_your_api_key"

POST

/keys

Create a new translation key. AI translation is triggered by default.

Parameter	Type	Required	Description
key	string	Required	Key name (e.g., checkout.success)
source_text	string	Required	Source language text
description	string	Optional	Context for translators
tags	string[]	Optional	Array of tags
auto_translate	boolean	Optional	Trigger AI translation (default true)

curl -X POST https://stringbase.io/api/v1/keys \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "checkout.success",
    "source_text": "Payment was successful!",
    "description": "Shown after checkout",
    "tags": ["checkout"],
    "auto_translate": true
  }'

GET

/keys/:keyId

Get a single key with all its translations.

curl https://stringbase.io/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer sb_live_your_api_key"

PATCH

/keys/:keyId

Update a key's source text, description, or tags.

Parameter	Type	Required	Description
source_text	string	Optional	New source text
description	string	Optional	New description
tags	string[]	Optional	New tags array

curl -X PATCH https://stringbase.io/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"source_text": "Payment completed successfully!"}'

DELETE

/keys/:keyId

Delete a key and all its translations.

curl -X DELETE https://stringbase.io/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer sb_live_your_api_key"

Response

json

{ "data": { "deleted": true } }

PATCH

/keys/:keyId/translations/:language

Update a translation value. Sets status to needs-review.

Parameter	Type	Required	Description
value	string	Required	New translation text

curl -X PATCH https://stringbase.io/api/v1/keys/KEY_ID/translations/es \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"value": "Pago completado con éxito"}'

POST

/keys/:keyId/translations/:language/approve

Approve a translation. Changes status from needs-review to ready-to-publish.

curl -X POST https://stringbase.io/api/v1/keys/KEY_ID/translations/es/approve \
  -H "Authorization: Bearer sb_live_your_api_key"

POST

/keys/:keyId/translations/:language/publish

Publish a translation. Copies it to production and sets status to published.

curl -X POST https://stringbase.io/api/v1/keys/KEY_ID/translations/es/publish \
  -H "Authorization: Bearer sb_live_your_api_key"

POST

/bulk/approve

Approve multiple translations at once.

Parameter	Type	Required	Description
translation_ids	string[]	Required	Array of translation UUIDs

curl -X POST https://stringbase.io/api/v1/bulk/approve \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"translation_ids": ["uuid-1", "uuid-2", "uuid-3"]}'

Response

json

{ "data": { "approved": 3, "failed": 0 } }

POST

/bulk/publish

Publish multiple translations at once.

Parameter	Type	Required	Description
translation_ids	string[]	Required	Array of translation UUIDs

bash

curl -X POST https://stringbase.io/api/v1/bulk/publish \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"translation_ids": ["uuid-1", "uuid-2"]}'

Response

json

{ "data": { "published": 2, "failed": 0 } }

POST

/bulk/promote

Promote all ready-to-publish translations in the project to production. No body needed.

curl -X POST https://stringbase.io/api/v1/bulk/promote \
  -H "Authorization: Bearer sb_live_your_api_key"

Response

json

{ "data": { "promoted": 12 } }

POST

/bulk/translate

Trigger AI translation for specific keys or all missing translations.

Parameter	Type	Required	Description
key_ids	string[]	Optional	Array of key UUIDs to translate
all_missing	boolean	Optional	Translate all missing translations

bash

curl -X POST https://stringbase.io/api/v1/bulk/translate \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"all_missing": true}'

Response

json

{ "data": { "translated": 8, "failed": 1, "limit_reached": false } }

GET

/keys/:keyId/translations/:language/comments

List all comments on a specific translation. Comments are available on all plans.

curl "https://stringbase.io/api/v1/keys/KEY_ID/translations/es/comments" \
  -H "Authorization: Bearer sb_live_your_api_key"

Response

json

{
  "data": [
    {
      "id": "uuid",
      "body": "Looks good, but consider using informal tone here @Jane",
      "mentioned_user_ids": ["uuid"],
      "author_id": "uuid",
      "author_name": "John Doe",
      "author_email": "john@example.com",
      "created_at": "2026-03-31T12:00:00Z"
    }
  ]
}

POST

/keys/:keyId/translations/:language/comments

Add a comment to a translation. Mention users by including their profile IDs in mentioned_user_ids.

Parameter	Type	Required	Description
body	string	Required	Comment text. Use @Name to mention users.
mentioned_user_ids	string[]	Optional	Array of profile UUIDs to notify

bash

curl -X POST "https://stringbase.io/api/v1/keys/KEY_ID/translations/es/comments" \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "Please review the formal vs informal tone here"}'

Response (201)

json

{
  "data": {
    "id": "uuid",
    "body": "Please review the formal vs informal tone here",
    "translation_id": "uuid",
    "author_id": "uuid",
    "created_at": "2026-03-31T12:00:00Z"
  }
}

GET

/keys/:keyId/translations/:language/history

Get the full change history for a specific translation. Includes edits, approvals, publications, and AI translations.

curl "https://stringbase.io/api/v1/keys/KEY_ID/translations/es/history" \
  -H "Authorization: Bearer sb_live_your_api_key"

Response

json

{
  "data": [
    {
      "id": "uuid",
      "action": "approved",
      "old_status": "needs-review",
      "new_status": "ready-to-publish",
      "actor_id": "uuid",
      "actor_name": "Jane Smith",
      "created_at": "2026-03-31T14:00:00Z"
    },
    {
      "id": "uuid",
      "action": "ai_translated",
      "new_value": "¡Bienvenido a nuestra aplicación!",
      "new_status": "needs-review",
      "actor_id": null,
      "actor_name": null,
      "created_at": "2026-03-31T12:00:00Z"
    }
  ]
}

GET

/glossary

List all glossary terms for your organization. Glossary terms are automatically applied to AI translations for Team plan organizations. Free plan can read via GET but cannot create, update, or delete.

curl https://stringbase.io/api/v1/glossary \
  -H "Authorization: Bearer sb_live_your_api_key"

Response

json

{
  "data": [
    {
      "id": "uuid",
      "source_term": "checkout",
      "context": "Payment flows",
      "translations": {
        "es": "pago",
        "fr": "caisse",
        "de": "Kasse"
      },
      "created_at": "2026-03-31T12:00:00Z",
      "updated_at": "2026-03-31T12:00:00Z"
    }
  ],
  "meta": {
    "count": 1
  }
}

POST

/glossary

Create a new glossary term. Requires Team plan.

Parameter	Type	Required	Description
source_term	string	Required	The source term to define
context	string	Optional	Usage context or translation notes
translations	object	Optional	Preferred translations keyed by language code

curl -X POST https://stringbase.io/api/v1/glossary \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_term": "checkout",
    "context": "Payment flows",
    "translations": {
      "es": "pago",
      "fr": "caisse"
    }
  }'

Response (201)

json

{
  "data": {
    "id": "uuid",
    "source_term": "checkout",
    "context": "Payment flows",
    "translations": {
      "es": "pago",
      "fr": "caisse"
    },
    "created_at": "2026-03-31T12:00:00Z",
    "updated_at": "2026-03-31T12:00:00Z"
  }
}

PATCH

/glossary/:termId

Update a glossary term. All fields are optional. Requires Team plan.

Parameter	Type	Required	Description
source_term	string	Optional	Updated source term
context	string	Optional	Updated usage context
translations	object	Optional	Updated translations (replaces all translations)

curl -X PATCH https://stringbase.io/api/v1/glossary/TERM_ID \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "translations": {
      "es": "proceso de pago",
      "fr": "caisse",
      "de": "Kasse"
    }
  }'

DELETE

/glossary/:termId

Delete a glossary term. Requires Team plan.

curl -X DELETE https://stringbase.io/api/v1/glossary/TERM_ID \
  -H "Authorization: Bearer sb_live_your_api_key"

Response

json

{
  "success": true
}

GET

/export

Export translations as flat JSON. Available on all plans. Keys are sorted alphabetically. Only non-empty translations are included.

Parameter	Type	Required	Description
env	string	Optional	'development' or 'production' (default: production)
lang	string	Optional	Comma-separated language codes to export (default: all configured languages)
status	string	Optional	'all', 'published', or 'approved' (default: all)

# Export Spanish translations from production
curl "https://stringbase.io/api/v1/export?env=production&lang=es" \
  -H "Authorization: Bearer sb_live_your_api_key"

Response

json

{
  "data": {
    "es": {
      "checkout.cancel": "Cancelar",
      "checkout.success": "Pago exitoso",
      "nav.home": "Inicio"
    },
    "fr": {
      "checkout.cancel": "Annuler",
      "checkout.success": "Paiement réussi",
      "nav.home": "Accueil"
    }
  },
  "meta": {
    "project": "My App",
    "environment": "production",
    "languages": ["es", "fr"],
    "count": 6
  }
}

POST

/import

Import translations from a flat JSON object. Available on all plans. Creates new keys or updates existing ones. Does not trigger AI translation. Respects key limits for Free plan (1,000 keys per project).

Parameter	Type	Required	Description
lang	string	Required	Language code to import into (must be a configured target language)
data	object	Required	Flat key-value object with string values
env	string	Optional	'development' or 'production' (default: development)
mode	string	Optional	'overwrite' or 'skip' — how to handle existing translations (default: overwrite)

curl -X POST https://stringbase.io/api/v1/import \
  -H "Authorization: Bearer sb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "lang": "es",
    "env": "development",
    "mode": "overwrite",
    "data": {
      "checkout.success": "Pago exitoso",
      "checkout.cancel": "Cancelar",
      "nav.home": "Inicio"
    }
  }'

Response

json

{
  "data": {
    "created": 2,
    "updated": 1,
    "skipped": 0
  }
}

Key limits: Free plan is limited to 1,000 keys per project. New keys that would exceed the limit are silently skipped. Upgrade to Team for unlimited keys.

GET

/project

Get information about the project associated with your API key.

curl https://stringbase.io/api/v1/project \
  -H "Authorization: Bearer sb_live_your_api_key"

Response

json

{
  "data": {
    "id": "uuid",
    "name": "My App",
    "source_language": "en",
    "target_languages": ["es", "fr", "de"],
    "key_count": 45,
    "environments": ["development", "production"],
    "ai_usage": {
      "used": 1247,
      "limit": 10000,
      "period": "2026-03"
    }
  }
}