---
title: "Run a text tool"
method: POST
path: "/v1/text/generate"
tags: ["Text"]
---

# Run a text tool

`POST /v1/text/generate`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/text/generate`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Runs one of the tools listed by GET /v1/text/tools against your input text. One
stateless call; billing is metered on ACTUAL token usage, not a flat rate, and the
response returns the token counts and the cost breakdown it charged on.

There is deliberately no free-form prompt escape hatch and no prompt-preview route:
both would publish internal prompt engineering to any token holder.

## Request body

- object
  - `tool_key` string, required: A `key` from GET /v1/text/tools.
  - `input_text` string, required: The text the tool operates on.
  - `options` object: Per-tool options.
  - `framework_id` integer: Optional StoryBrand framework (integer id) to condition the output on. Must be one you own.
  - `source_type` string: Provenance label. Defaults to "direct".
  - `source_id` integer: Optional integer id of the source record.
  - `source_uuid` string: Optional uuid of the source record.

## Response `200`

The tool output.

- object
  - `success` boolean
  - `data` object
    - `operation_uuid` string, uuid
    - `tool` object
      - `key` string
      - `name` string
      - `category` string
      - `icon` string
      - `color` string
    - `input` string
    - `output` string
    - `used_blueprint` boolean
    - `credits_used` number, float
    - `processing_time_ms` integer
    - `tokens` object
      - `input` integer
      - `output` integer
      - `total` integer
    - `cost_breakdown` object
      - `actual_cost_usd` number
      - `credit_cost` number
      - `markup_multiplier` number
  - `timestamp` string, date-time

## Other responses

- `400`: Missing tool_key or input_text, or malformed JSON.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits.
- `404`: No such tool. Your key is not echoed back in the message.
- `503`: The provider is over quota or overloaded. A fixed sentence - no provider text is relayed.
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)