REST API

ShipEasyI18n REST API reference — base URL, authentication, error codes, and rate limits.

Base URL: https://api.i18n.shipeasy.ai/v1

All endpoints return JSON. Requests that write data require a Content-Type: application/json header.

Authentication

The ShipEasyI18n API uses two types of credentials:

Credential	Prefix	Used for
Public key	`i18n_pk_`	Loader script, CDN fetch, read-only public endpoints
Secret token	`i18n_at_`	CLI, server-side API calls, management operations

Public key

Passed as the data-key attribute on the loader script or as a query parameter on CDN requests. Safe to include in client-side HTML — it only identifies your account, not authenticate it.

Secret token

Pass in the Authorization header:

Authorization: Bearer i18n_at_your_secret_token

Generate tokens in the dashboard under Settings → Secret Tokens. Store them as environment variables — never commit to version control.

# .env.local (never commit)
ShipEasyI18n_SECRET_TOKEN=i18n_at_your_secret_token

Secret tokens have full write access to your account. Rotate immediately if exposed.

Error responses

All errors return JSON with an error field:

{ "error": "profile_not_found" }

Status	Error code	Meaning
`400`	`invalid_request`	Missing or malformed request body
`400`	`invalid_key_format`	Key name contains invalid characters
`401`	`unauthorized`	Missing or invalid token
`403`	`forbidden`	Token lacks permission for this operation
`404`	`profile_not_found`	Profile name doesn't exist
`404`	`key_not_found`	Label key doesn't exist
`409`	`key_already_exists`	Attempted to create a key that already exists
`422`	`validation_error`	Request body failed schema validation
`429`	`rate_limited`	Too many requests — back off and retry
`500`	`internal_error`	Server error — contact support if persistent

Rate limits

Operation	Limit
Management API (write)	300 req/min per token
Management API (read)	1 000 req/min per token
CDN label file fetch	Unlimited (edge-cached)
`i18n translate` (AI)	60 req/min per account

Rate limit headers on every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1712345678

When rate-limited, retry after the Retry-After header value (seconds).

Pagination

List endpoints return paginated results:

{
  "data": [...],
  "meta": {
    "total": 142,
    "page": 1,
    "perPage": 50,
    "hasMore": true
  }
}

Pass ?page=2&perPage=50 to paginate. Maximum perPage is 200.

Versioning

The API is versioned via the URL path (/v1). Breaking changes are released as new versions with a deprecation notice and a 6-month migration window.

Non-breaking additions (new fields, new endpoints) are made to the current version without notice.