Translation APIReference
v2.0.0

Projects

Create a translation project

Start a translation project from uploaded files or inline JSON/text. Provide source and target languages and optional project or billing references. The response includes a project ID that can be used to track progress and retrieve completed translations.

POST/projects

API key permission: projects:write. Send a unique Idempotency-Key and reuse it only when retrying the same request.

Parameters

NameTypeDescription
Idempotency-Keystring · required

Unique operation key. Reuse it only with the same method, path, and request body.

Request body

application/json
namestringRequired

Project or quote name displayed in API responses and the Stepes client portal.

external_idstring | nullOptional

Optional correlation ID from your application, scoped to the API key environment.

source_languagestringRequired

Active source language code returned by GET /languages.

target_languagesstring[]Required

Distinct active target language codes, each different from the source language.

servicestringOptional

Service code returned by GET /service-options.

turnaroundstringOptional

Requested delivery speed.

due_atstring | nullOptional

Optional future requested due time; required by configurations using custom turnaround.

instructionsstring | nullOptional

Instructions for the translation team.

file_idsstring[]Optional

Ready file IDs returned by POST /files. Use this or content, never both.

contentobjectOptional

Inline JSON or text. Use this or file_ids, never both.

po_numberstring | nullOptional

Optional purchase-order reference for billing.

cost_centerstring | nullOptional

Optional cost center for billing.

invoice_notesstring | nullOptional

Optional billing notes.

Standard response headers

HeaderExampleDescription
Stepes-Request-Idb09de4aa-3874-4991-b85c-0bc86e780511

Server-generated request identifier for support and audit correlation.

Stepes-API-Version2.0.0

Effective Stepes API semantic version.

RateLimit-Policy120;w=60

Effective request limit and window for the authenticated key.

RateLimitlimit=120, remaining=119, reset=60

Current limit, remaining requests, and reset interval.

Idempotency-Replayedtrue

Present with value true when a stored mutation response is replayed.

Responses

201

Translation project created

401

Missing, malformed, expired, revoked, or disallowed API key

403

Missing API key permission or account access

409

Idempotency conflict or invalid lifecycle transition

422

Request validation failed

{
  "id": "proj_01JZ8K6N2W6RX4J9P7Y8K3M2Q1",
  "object": "project",
  "external_id": "SKU-1042-ES",
  "name": "Catalog SKU 1042",
  "status": "new",
  "progress": 0,
  "source_language": "EN-US",
  "target_languages": [
    "ES-ES"
  ],
  "source_files": [
    {
      "id": "file_01JZ8K6N2W6RX4J9P7Y8K3M2Q2",
      "object": "file",
      "filename": "catalog-sku-1042.json",
      "mime_type": "application/json",
      "size": 142,
      "status": "ready",
      "download_url": "https://apis.stepes.com/v2/files/file_01JZ8K6N2W6RX4J9P7Y8K3M2Q2/download",
      "content_url": "https://apis.stepes.com/v2/files/file_01JZ8K6N2W6RX4J9P7Y8K3M2Q2/content"
    }
  ],
  "due_at": null,
  "jobs": [],
  "delivery_ready": false,
  "invoice": {
    "status": "Unpaid",
    "currency": "USD",
    "total": 25,
    "due_at": "2026-09-08T00:00:00+00:00"
  },
  "created_at": "2026-08-10T12:00:00+00:00",
  "updated_at": "2026-08-10T12:00:00+00:00"
}