Get Started with the Stepes Translation API

export STEPES_BASE_URL="YOUR_STEPES_API_BASE_URL"
export STEPES_API_KEY="YOUR_STEPES_API_KEY"

$env:STEPES_BASE_URL = "YOUR_STEPES_API_BASE_URL"
$env:STEPES_API_KEY = "YOUR_STEPES_API_KEY"

curl --request GET \
--url "$STEPES_BASE_URL/v2/account" \
--header "Authorization: Bearer $STEPES_API_KEY" \
--header "Accept: application/json"

const response = await fetch(
`${process.env.STEPES_BASE_URL}/v2/account`,
{
headers: {
  Authorization: `Bearer ${process.env.STEPES_API_KEY}`,
  Accept: "application/json"
}
}
);

const account = await response.json();

import os
import requests

response = requests.get(
f"{os.environ['STEPES_BASE_URL']}/v2/account",
headers={
    "Authorization": f"Bearer {os.environ['STEPES_API_KEY']}",
    "Accept": "application/json",
},
)

account = response.json()

{
"id": "org_example",
"environment": "sandbox",
"status": "active",
"apiVersion": "2.1"
}

curl --request POST \
--url "$STEPES_BASE_URL/v2/translation-projects" \
--header "Authorization: Bearer $STEPES_API_KEY" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Idempotency-Key: first-translation-example-001" \
--data '{
"clientReference": "getting-started-example",
"sourceLocale": "en-US",
"targetLocales": ["de-DE"],
"content": {
  "type": "text",
  "items": [{
    "id": "support-message",
    "text": "Your order has shipped and is expected to arrive within three business days."
  }]
},
"workflow": { "mode": "ai_translation" },
"metadata": { "application": "developer-quickstart" }
}'

const response = await fetch(
`${process.env.STEPES_BASE_URL}/v2/translation-projects`,
{
method: "POST",
headers: {
  Authorization: `Bearer ${process.env.STEPES_API_KEY}`,
  "Content-Type": "application/json",
  Accept: "application/json",
  "Idempotency-Key": "first-translation-example-001"
},
body: JSON.stringify({
  clientReference: "getting-started-example",
  sourceLocale: "en-US",
  targetLocales: ["de-DE"],
  content: {
    type: "text",
    items: [{
      id: "support-message",
      text: "Your order has shipped and is expected to arrive within three business days."
    }]
  },
  workflow: { mode: "ai_translation" }
})
}
);

import os
import requests

response = requests.post(
f"{os.environ['STEPES_BASE_URL']}/v2/translation-projects",
headers={
    "Authorization": f"Bearer {os.environ['STEPES_API_KEY']}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "first-translation-example-001",
},
json={
    "clientReference": "getting-started-example",
    "sourceLocale": "en-US",
    "targetLocales": ["de-DE"],
    "content": {
        "type": "text",
        "items": [{
            "id": "support-message",
            "text": "Your order has shipped and is expected to arrive within three business days."
        }]
    },
    "workflow": {"mode": "ai_translation"},
},
)

{
"id": "trp_01JEXAMPLE",
"clientReference": "getting-started-example",
"status": "accepted",
"sourceLocale": "en-US",
"targetLocales": ["de-DE"],
"createdAt": "2026-07-20T15:30:00Z",
"jobs": [{
"id": "trj_01JEXAMPLE_DE",
"targetLocale": "de-DE",
"status": "queued"
}],
"links": {
"self": "/v2/translation-projects/trp_01JEXAMPLE",
"results": "/v2/translation-projects/trp_01JEXAMPLE/results"
}
}

PROJECT_ID="trp_01JEXAMPLE"

curl --request GET \
--url "$STEPES_BASE_URL/v2/translation-projects/$PROJECT_ID" \
--header "Authorization: Bearer $STEPES_API_KEY" \
--header "Accept: application/json"

const terminalStates = new Set([
"completed",
"partially_completed",
"failed",
"canceled"
]);

async function waitForProject(projectId) {
let delay = 3000;

while (true) {
const response = await fetch(
  `${process.env.STEPES_BASE_URL}/v2/translation-projects/${projectId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.STEPES_API_KEY}`,
      Accept: "application/json"
    }
  }
);

if (!response.ok) {
  throw new Error(`Status request failed with ${response.status}`);
}

const project = await response.json();
if (terminalStates.has(project.status)) return project;

const retryAfter = Number(response.headers.get("retry-after"));
const waitTime = Number.isFinite(retryAfter)
  ? retryAfter * 1000
  : delay;

await new Promise(resolve => setTimeout(resolve, waitTime));
delay = Math.min(delay * 2, 30000);
}
}

import os
import time
import requests

TERMINAL_STATES = {
"completed",
"partially_completed",
"failed",
"canceled",
}

def wait_for_project(project_id):
delay = 3

while True:
    response = requests.get(
        f"{os.environ['STEPES_BASE_URL']}/v2/translation-projects/{project_id}",
        headers={
            "Authorization": f"Bearer {os.environ['STEPES_API_KEY']}",
            "Accept": "application/json",
        },
    )
    response.raise_for_status()
    project = response.json()

    if project["status"] in TERMINAL_STATES:
        return project

    retry_after = response.headers.get("Retry-After")
    time.sleep(int(retry_after) if retry_after else delay)
    delay = min(delay * 2, 30)

{
"id": "trp_01JEXAMPLE",
"status": "processing",
"sourceLocale": "en-US",
"targetLocales": ["de-DE"],
"jobs": [{
"id": "trj_01JEXAMPLE_DE",
"targetLocale": "de-DE",
"status": "processing",
"progress": 65
}],
"updatedAt": "2026-07-20T15:30:18Z"
}

curl --request GET \
--url "$STEPES_BASE_URL/v2/translation-projects/$PROJECT_ID/results" \
--header "Authorization: Bearer $STEPES_API_KEY" \
--header "Accept: application/json"

const response = await fetch(
`${process.env.STEPES_BASE_URL}/v2/translation-projects/${projectId}/results`,
{
headers: {
  Authorization: `Bearer ${process.env.STEPES_API_KEY}`,
  Accept: "application/json"
}
}
);

const results = await response.json();

import os
import requests

response = requests.get(
f"{os.environ['STEPES_BASE_URL']}/v2/translation-projects/{project_id}/results",
headers={
    "Authorization": f"Bearer {os.environ['STEPES_API_KEY']}",
    "Accept": "application/json",
},
)

results = response.json()

{
"projectId": "trp_01JEXAMPLE",
"status": "completed",
"sourceLocale": "en-US",
"completedAt": "2026-07-20T15:30:24Z",
"results": [{
"jobId": "trj_01JEXAMPLE_DE",
"targetLocale": "de-DE",
"status": "completed",
"content": {
  "type": "text",
  "items": [{
    "id": "support-message",
    "translation": "Ihre Bestellung wurde versandt und wird voraussichtlich innerhalb von drei Werktagen eintreffen."
  }]
}
}]
}