---
title: "Run Stage 2 translation"
method: POST
path: "/api/v1/translate"
tags: ["Translation"]
---

# Run Stage 2 translation

`POST /api/v1/translate`

## Request

- Base URL: `https://www.devspeak.dev`
- URL: `https://www.devspeak.dev/api/v1/translate`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Transforms input into an audience-specific technical document. Requires the optimize:write scope and the apiAccess feature.

## Request body

- TranslateRequest
  - `input` string, required
  - `audience` 'Junior Dev' | 'Senior Dev' | 'Tech Lead' | 'SRE' | 'Data Engineer', required
  - `context` 'Backend' | 'Frontend' | 'Mobile' | 'Data/ML' | 'DevOps', required
  - `format` 'Technical Spec' | 'Jira Tickets' | 'API Design' | 'RFC' | 'Data Model' | 'Prompt' | 'Optimize', required
  - `tone` integer, required
  - `customInstructions` string
  - `workspaceContext` string
  - `translationId` string
  - `correctionsOnly` boolean: Only with format "Optimize", which returns the input improved in its own language instead of a document. true fixes spelling, grammar and punctuation only.

## Response `200`

Generated translation

- TranslationResponse
  - `success` true, required
  - `data` object, required
    - `output` string, required
    - `metadata` TranslationMetadata, required
      - `wordCount` integer, required
      - `latencyMs` integer, required
      - `model` string, required
      - `provider` string
      - `credentialSource` string
      - `endpointHost` string, nullable
      - `isOutOfScope` boolean
      - `inputTokens` integer, nullable
      - `outputTokens` integer, nullable
      - `thinkingTokens` integer, nullable

## Other responses

- `400`: Validation error
- `401`: Missing or invalid credentials
- `403`: Missing scope, feature, or plan access
- `429`: Rate limit exceeded
- `500`: Internal server error
- `504`: Upstream timeout

---

[API](https://skmtc.dev/devspeak/apis/devspeak-api-v1.md) · [All operations](https://skmtc.dev/devspeak/apis/devspeak-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/devspeak/apis/devspeak-api-v1/revisions/7000833a5bbf?raw)