---
title: "AI content: \"Improve all texts\" of a page or the site, as proposals. Metered in Build Credits (DeepSeek, a few hundredths of a credit for a short text); the answer includes usage."
method: POST
path: "/builder/sessions/{sessionId}/content/improve"
tags: ["Builder"]
---

# AI content: "Improve all texts" of a page or the site, as proposals. Metered in Build Credits (DeepSeek, a few hundredths of a credit for a short text); the answer includes usage.

`POST /builder/sessions/{sessionId}/content/improve`

## Request

- Base URL: `https://hostingsurge.com/api/v1`
- URL: `https://hostingsurge.com/api/v1/builder/sessions/{sessionId}/content/improve`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-hs_session`

## Path parameters

- `sessionId` string, uuid, required

## Request body

- object
  - `lang` string, required
  - `route` string: One page; all pages when omitted
  - `tone` 'friendly' | 'professional' | 'luxurious' | 'playful' | 'straightforward' | 'warm-local' | 'brand'
  - `noteLang` string: The language the AI says why in (the dashboard language); English when omitted

## Response `200`

The proposals

- object
  - `proposals` object[], required
    - `keyPath` string, required
    - `lang` string, required
    - `label` string, required
    - `route` string, nullable, required
    - `before` string, required
    - `after` string, required
    - `why` string, required
  - `usage` object, required
    - `model` string, required
    - `calls` integer, required
    - `inputTokens` integer, required
    - `outputTokens` integer, required
    - `cachedInputTokens` integer, required
    - `costMicros` integer, required: Model cost, micro-USD
    - `millicredits` integer, required
    - `credits` number, required
    - `charge` 'charged' | 'duplicate' | 'skipped' | 'failed' | 'none', required: What billing did with it (skipped: billing is off or the team is unlimited)

## Other responses

- `400`: Invalid request (code invalid_request; details.reason: invalid, unmappable, not_found, secret_detected)
- `401`: Missing or invalid session/token (code unauthorized)
- `402`: No Build Credits left, the team's daily credits are used (code limit_reached), or multilingual sites need a plan or credits (code upgrade_required, details.feature site.multilingual)
- `403`: Not permitted, or the AI builder is in private beta (code forbidden)
- `404`: Not found or not visible to the caller (code not_found)
- `409`: Refused for now (code conflict; details.reason turn_running, archived, language_exists, no_content, stale)
- `429`: Too many AI actions (code rate_limited; details.reason content_rate or capacity); see Retry-After
- `501`: The AI is not available on this server right now (code not_configured)
- `503`: The AI could not finish (code provider_unavailable); nothing was changed

---

[API](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api.md) · [All operations](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/revisions/4d08337cdff1?raw)