Universally has two APIs, and which one you need depends on what you are building. One translates content, the other manages your account. Both are documented with live request examples at developer.universally.com.
The two APIs
| Translator API | Platform API | |
|---|---|---|
| Host | translator.universally.com |
api.universally.com |
| Reference | Open the spec | Open the spec |
| For | turning content into another language | managing projects, languages, glossary and stored translations |
| Key | the project's private API key | a workspace API key |
| Used by | the WordPress plugin, and your own integration | scripts and tooling around the dashboard |
If you are replacing the WordPress plugin on another platform, the Translator API is the one you want. The Platform API is for automating the dashboard, not for serving pages.
First, create a project
A project is what holds your domain, your source language, your target languages and your keys, so it comes before any API call. Two ways to make one.
In the dashboard. Open New Project. Select Your Technology currently only offers WordPress: the other options carry a Coming Soon badge and cannot be selected. That is fine for an API integration, since the technology only changes what the dashboard shows you, not what the Translator API accepts. One consequence to expect: the project's API Settings screen will keep reporting "Universally plugin not detected", because for a WordPress project it looks for the plugin on your domain. Nothing is wrong, and translation works regardless.
With the Platform API. POST /sites creates a project with a workspace pak_ key, and takes name, domain, sourceLanguage and tech. Use tech: "wordpress" for a site with a domain, or tech: "app" when there is no domain to give. tech: "website" and subdomain mode are in a closed beta and are rejected for now. Do not send a workspaceId: it is taken from the key.
curl -X POST https://api.universally.com/sites \
-H "X-API-Key: $UNIVERSALLY_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Docs site","domain":"example.com","sourceLanguage":"en-us","tech":"wordpress"}'
Then add target languages, either on the project's All Languages screen or through the Platform API, and copy the project key from API Settings.
The Translator API
Three endpoints, all POST, all authenticated with the project's private key in an X-API-Key header:
| Endpoint | Send it |
|---|---|
/v1/translate/html |
a rendered page, when you can hand over whole HTML |
/v1/translate/strings |
an array of strings, when you hold the content yourself |
/v1/translate |
either, and it decides which of the above applies |
The HTML endpoint is the closest match to how the plugin works: your server sends the page it was about to return, and serves back what it gets. Nothing needs to know in advance which text is on the page. See REST API overview for the request and response shapes, and API errors and limits for what to expect when a word limit is reached mid-request.
curl -X POST https://translator.universally.com/v1/translate/html \
-H "X-API-Key: $UNIVERSALLY_KEY" \
-H "Content-Type: application/json" \
-d '{"html":"<html>...</html>","targetLanguage":"es","sourceUrl":"https://example.com/pricing/"}'
The Platform API
Same header, different key: a workspace API key, which starts with pak_. It reaches the same endpoints the dashboard uses, so it can add languages, edit glossary rules, read stored translations and list sites without anyone clicking through the UI.
Create one under Workspaces, then API Keys. See Find your API key.
What you still have to build
The plugin does more than call an endpoint, and none of it comes for free through the API:
- Serving language URLs. Something has to route
/es/pricing/to your Spanish response. Universally translates what you send; it does not sit in front of your site. - Caching. Translate once and store the result. Re-sending the same page does not spend words again, since a string is only charged the first time it is seen, but every request costs a round trip and the latency that comes with it.
- Detecting changes. Re-send a page when its content changes, otherwise visitors keep seeing the old translation.
- The language switcher. The plugin ships one. Through the API, the markup is yours. See Build a custom language switcher in WordPress for the shape of it.