API Reference

Complete reference for the Papuga 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://papuga.io/api/v1/translations?env=production&lang=es \
  -H "Authorization: Bearer pg_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://papuga.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://papuga.io/api/v1/translations?env=production&lang=es" \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/keys?search=checkout&page=1" \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/keys \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/keys/KEY_ID/translations/es \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/keys/KEY_ID/translations/es/approve \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/keys/KEY_ID/translations/es/publish \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/bulk/approve \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/bulk/publish \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/bulk/promote \
  -H "Authorization: Bearer pg_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://papuga.io/api/v1/bulk/translate \
  -H "Authorization: Bearer pg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"all_missing": true}'

Response

json

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

GET

/project

Get information about the project associated with your API key.

curl https://papuga.io/api/v1/project \
  -H "Authorization: Bearer pg_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"
    }
  }
}