Profiles & Keys API

Profiles

A profile is a named set of label values for a specific language and environment — e.g. en:prod, fr:staging.

List profiles

GET /v1/profiles
Authorization: Bearer i18n_at_...

{
  "data": [
    {
      "id": "prof_abc123",
      "name": "en:prod",
      "keyCount": 142,
      "publishedAt": "2026-04-10T14:22:00Z",
      "createdAt": "2026-01-01T00:00:00Z"
    },
    {
      "id": "prof_def456",
      "name": "fr:prod",
      "keyCount": 118,
      "publishedAt": "2026-04-10T14:22:00Z",
      "createdAt": "2026-01-15T00:00:00Z"
    }
  ],
  "meta": { "total": 2, "page": 1, "perPage": 50, "hasMore": false }
}

Create a profile

POST /v1/profiles
Authorization: Bearer i18n_at_...
Content-Type: application/json

{
  "name": "de:prod"
}

Profile names must match the pattern [a-z]{2,5}:[a-z0-9_-]+ (language code : environment slug).

{
  "id": "prof_ghi789",
  "name": "de:prod",
  "keyCount": 0,
  "publishedAt": null,
  "createdAt": "2026-04-11T10:00:00Z"
}

Delete a profile

DELETE /v1/profiles/:name
Authorization: Bearer i18n_at_...

Deletes the profile and all its keys. Irreversible — unpublish and back up with i18n export first.

{ "deleted": true }

---

Label Keys

A key is a dot-separated identifier (e.g. nav.home) with a string value in a given profile.

List keys

GET /v1/profiles/:name/keys
Authorization: Bearer i18n_at_...

Query parameters:

Parameter	Default	Description
page	1	Page number
perPage	50	Results per page (max 200)
chunk	—	Filter by chunk name
q	—	Search key names and values
missing	—	true to return only keys with empty values

{
  "data": [
    {
      "id": "key_abc123",
      "key": "nav.home",
      "value": "Home",
      "description": "Navigation home link",
      "chunk": "index",
      "updatedAt": "2026-04-10T12:00:00Z"
    }
  ],
  "meta": { "total": 142, "page": 1, "perPage": 50, "hasMore": true }
}

Get a key

GET /v1/profiles/:name/keys/:key
Authorization: Bearer i18n_at_...

{
  "id": "key_abc123",
  "key": "nav.home",
  "value": "Home",
  "description": "Navigation home link",
  "chunk": "index",
  "updatedAt": "2026-04-10T12:00:00Z",
  "updatedBy": "user_xyz"
}

Create a key

POST /v1/profiles/:name/keys
Authorization: Bearer i18n_at_...
Content-Type: application/json

{
  "key": "nav.home",
  "value": "Home",
  "description": "Navigation home link",
  "chunk": "index"
}

chunk is optional — defaults to index. description is optional.

Returns 201 Created with the key object. Returns 409 if the key already exists.

Update a key

PATCH /v1/profiles/:name/keys/:key
Authorization: Bearer i18n_at_...
Content-Type: application/json

{
  "value": "Homepage",
  "description": "Updated description"
}

Only the fields provided are updated.

Delete a key

DELETE /v1/profiles/:name/keys/:key
Authorization: Bearer i18n_at_...

{ "deleted": true }

---

Bulk operations

Bulk upsert

Create or update up to 500 keys in a single request. This is what i18n push uses internally.

POST /v1/profiles/:name/keys/bulk
Authorization: Bearer i18n_at_...
Content-Type: application/json

{
  "keys": [
    { "key": "nav.home", "value": "Home", "chunk": "index" },
    { "key": "nav.signIn", "value": "Sign in", "chunk": "index" },
    { "key": "checkout.submit", "value": "Place order", "chunk": "checkout" }
  ],
  "upsert": true
}

{
  "created": 2,
  "updated": 1,
  "unchanged": 0,
  "errors": []
}

If any key fails validation, it's listed in errors and the rest are still processed.

Bulk delete

DELETE /v1/profiles/:name/keys/bulk
Authorization: Bearer i18n_at_...
Content-Type: application/json

{
  "keys": ["nav.home", "nav.signIn"]
}

{ "deleted": 2 }

---

Coverage

Get translation coverage for all profiles relative to a source profile.

GET /v1/coverage?source=en:prod
Authorization: Bearer i18n_at_...

{
  "source": "en:prod",
  "sourceKeyCount": 142,
  "profiles": {
    "en:prod": { "count": 142, "coverage": 1.0 },
    "fr:prod": { "count": 118, "coverage": 0.83 },
    "de:prod": { "count": 61,  "coverage": 0.43 },
    "es:prod": { "count": 0,   "coverage": 0.0  }
  }
}