---
title: "Generate an AI subject line for one lead (synchronous)"
method: POST
path: "/v1/ai/subject"
tags: ["AI Personalization"]
---

# Generate an AI subject line for one lead (synchronous)

`POST /v1/ai/subject`

Identical contract to `POST /v1/ai/hook` but produces a subject line. Billed 3 credits (3p) per fresh success; cache hits and failures are never charged.

## Request body

- AiVariableGenerateRequest
  - `leadId` string, uuid, required — The lead to generate for. Must belong to the caller.
  - `locale` string — Output locale (one of the 8 supported locales).
  - `mode` 'native' | 'translate' — `native` generates directly in the target locale; `translate` generates in English then translates.

## Response `200`

Subject generated (or returned from cache)

- AiSubjectGenerateResponse
  - `success` boolean
  - `data` object
    - `leadId` string, uuid
    - `subject` string
    - `locale` string
    - `mode` 'native' | 'translate'
    - `model` string
    - `cached` boolean
    - `cost` AiCost
      - `credits` integer
      - `pence` integer

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `402` — Insufficient credit balance for the request (or whole batch).
- `404` — Resource not found (also returned for cross-customer leads — no enumeration).
- `422` — Generation could not produce a valid value (no source data, or failed format guardrails after retry). Never charged.
- `429` — Rate limit exceeded (1000 requests/hour/key).
- `503` — The AI provider timed out or is temporarily unavailable. Retry shortly.

---

[API](https://skmtc.net/meirra/apis/meirra-api.md) · [All operations](https://skmtc.net/meirra/apis/meirra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/meirra/meirra-api/revisions/d6c1805fc561/schema)