---
title: "Run Stage 3 refinement"
method: POST
path: "/api/v1/refine"
tags: ["Translation"]
---

# Run Stage 3 refinement

`POST /api/v1/refine`

## Request

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

Refines a previous output using targeted feedback. Requires the optimize:write scope and the iterativeRefinement feature.

## Request body

- RefineRequest
  - `originalInput` string, required
  - `previousOutput` string, required
  - `feedback` 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
  - `workspaceContext` string
  - `translationId` string

## Response `200`

Refined document

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