---
title: "Humanize reader-facing text"
method: POST
path: "/v1/tools/humanize"
---

# Humanize reader-facing text

`POST /v1/tools/humanize`

## Request

- Base URL: `https://api.counselorai.app`
- URL: `https://api.counselorai.app/v1/tools/humanize`
- Auth: HTTP bearer

Rewrite reader-facing prose so it sounds direct, specific, and personal without changing facts or inventing a voice. Use it for outreach, emails, letters, posts, and narrative copy. It preserves quoted text and checks the result against the source. It does not evade or promise to beat AI detectors. Do not use it for code, SQL, JSON, legal text, or technical specifications.

## Headers

- `Idempotency-Key` string
- `X-Max-Credits` integer

## Request body

- object
  - `text` string, required: The reader-facing prose to edit.
  - `audience` 'general' | 'cold_outreach' | 'parent' | 'student' | 'counselor' | 'leadership' | 'social': Who will read the text. This changes vocabulary and formality, not the facts.
  - `strength` 'light' | 'standard' | 'aggressive': light makes surface fixes, standard rewrites AI-sounding sentences, aggressive may rebuild paragraph flow.
  - `preserveFormatting` boolean: Keep headings, lists, paragraph breaks, links, and other formatting.

## Response `200`

Tool output

- object
  - `request_id` string
  - `tool` string
  - `output` object
    - `text` string, required: The generated output.
    - `meta` object: Pipeline metadata (pipeline, verify status, fix pass).
    - `verification` object: Whether a model verify pass checked this text, and its verdict.
      - `checked` boolean
      - `method` string, nullable
      - `status` 'PASS' | 'FAIL' | 'null', nullable
      - `score` integer, nullable
      - `fix_applied` boolean, nullable
    - `grounding` object: What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.
      - `fact_sheet` string, nullable
      - `fields_reflected_in_prompt` string[]
      - `fields_mapped_or_transformed` string[]
      - `fields_not_reflected` string[]
    - `input_fidelity` string: 'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent.
  - `billing` object
    - `status` 'settled' | 'pending'
    - `credits_charged` integer, nullable
    - `credits_remaining` integer, nullable

## Other responses

- `402`: Insufficient credits or approved spending limit exceeded. Inspect error.code.
- `429`: Rate limited. Retry after the Retry-After header.

---

[API](https://skmtc.dev/counselorai/apis/counselorai-api.md) · [All operations](https://skmtc.dev/counselorai/apis/counselorai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/counselorai/apis/counselorai-api/revisions/1d93eed35463?raw)