---
title: "Run Stage 1 optimization"
method: POST
path: "/api/v1/optimize"
tags: ["Translation"]
---

# Run Stage 1 optimization

`POST /api/v1/optimize`

## Request

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

Returns the input improved in the language it was written in. By default it improves the whole text (word choice, flow, clarity, sentence structure) while keeping meaning, voice, facts, code and line breaks; correctionsOnly: true fixes spelling, grammar and punctuation only. Task-context-free: attachments, per-request custom instructions, and context project grounding are not supported and are silently dropped. Requires the optimize:write scope.

## Request body

- OptimizeRequest: Stage 1 contract. Task-level context fields (attachments, customInstructions, contextProjectId) are dropped at the route boundary.
  - `input` string, required
  - `audience` 'Junior Dev' | 'Senior Dev' | 'Tech Lead' | 'SRE' | 'Data Engineer', required
  - `context` 'Backend' | 'Frontend' | 'Mobile' | 'Data/ML' | 'DevOps', required
  - `managedModel` string: Allowlisted managed model pin. Omit to use the fast Stage 1 default.
  - `translationId` string
  - `correctionsOnly` boolean: Write mode. false (default) improves the whole text in its own language (word choice, flow, clarity, sentence structure); true fixes spelling, grammar and punctuation only.

## Response `200`

Optimized text

- 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

---

[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)