Translation Widgets API

List, retrieve, and create translation widget configurations through the Ours Privacy REST API.

BetaThis is in beta. The basics are stable, and more capabilities are on the way.

List, retrieve, and create translation widget configurations. A translation widget is the on-site language selector that translates your website into a visitor's language; each configuration holds the domains it runs on, its button and modal appearance, the languages it offers, and the terms it never translates.

Use the id from a widget to install it or to query Translation Widget Analytics.

GET/rest/v1/translation-widgets

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/translation-widgets"

{  "entities": [    {      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",      "createdAt": "2026-04-30T18:42:11.219Z",      "updatedAt": "string",      "whitelistedDomains": [        "www.example.com"      ],      "position": "bottom-right",      "theme": "light",      "brandColor": "string",      "widgetVariant": "compact",      "modalVariant": "standard",      "customDomain": "string",      "noTranslateTerms": [        "string"      ],      "enabledLanguages": [        "en",        "es",        "fr"      ]    }  ]}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

POST/rest/v1/translation-widgets

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

whitelistedDomains?array<string>|

Domains where this widget is allowed to run. The widget refuses to load anywhere else, so a missing host means the widget never appears. Send bare hosts — no scheme, port, or path.

position?string

Corner of the viewport the widget button is anchored to.

Value in

"bottom-right"
"bottom-left"
"top-right"
"top-left"

theme?string

Colour scheme the widget renders in.

Value in

"light"
"dark"

brandColor?|

Accent colour for the widget button and modal, as a hex value — #RGB, #RRGGBB, or #RRGGBBAA.

Match^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$

widgetVariant?string

Visual style of the widget button: compact for an icon-sized button, extended for a labelled button, minimal for the least intrusive treatment.

Value in

"compact"
"extended"
"minimal"

modalVariant?string

Layout of the language-selection modal: standard list, grid of languages, or a dropdown.

Value in

"standard"
"grid"
"dropdown"

customDomain?|

Custom domain used to serve the widget script (e.g. translate.example.com). Leave null to use the default Ours Privacy domain. Send the bare host — no scheme, port, or path.

noTranslateTerms?array<>|

Terms the widget keeps in their original form in every language — brand names, product names, and the like. Up to 500 terms of 200 characters each; duplicates and purely numeric terms are dropped.

Itemsitems <= 500

enabledLanguages?array<>|

Languages offered in the widget, as ISO codes such as en, es, fr, zh-TW. Omit or send an empty array to offer every supported language. An unrecognised code is rejected with 400 rather than silently ignored.

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/translation-widgets" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  "createdAt": "2026-04-30T18:42:11.219Z",  "updatedAt": "string",  "whitelistedDomains": [    "www.example.com"  ],  "position": "bottom-right",  "theme": "light",  "brandColor": "string",  "widgetVariant": "compact",  "modalVariant": "standard",  "customDomain": "string",  "noTranslateTerms": [    "string"  ],  "enabledLanguages": [    "en",    "es",    "fr"  ]}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

GET/rest/v1/translation-widgets/{id}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/translation-widgets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  "createdAt": "2026-04-30T18:42:11.219Z",  "updatedAt": "string",  "whitelistedDomains": [    "www.example.com"  ],  "position": "bottom-right",  "theme": "light",  "brandColor": "string",  "widgetVariant": "compact",  "modalVariant": "standard",  "customDomain": "string",  "noTranslateTerms": [    "string"  ],  "enabledLanguages": [    "en",    "es",    "fr"  ]}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

Translation Widgets

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`