Skip to main content
Take a persona you already have — a sketch, a few lines, or a rough character note — and get back a full, rendered persona built from it: a flat fields map, a ready-to-use system_prompt, and a formatted markdown sheet. The API sharpens the voice, fills in concrete detail, and surfaces the fields implied by your text, without you specifying any structure. This endpoint is asynchronous, in the same shape as Personas: the POST returns 200 OK right away with an id, and you then GET the enhancement repository route with that id until the persona is ready. To generate a whole population from a prompt instead, see Personas. The returned persona is dynamic: the API infers which fields fit your text and returns exactly those as string values, so the keys differ from one input to the next.

Authorization

string
required
Your bearer token: Bearer <token>. See Authentication.

Request body

string
required
The existing persona text to deepen. Must be a non-empty string.
string
default:"off"
How hard to ground the result in real-world data before rewriting. One of:
  • off — work from your text alone, with no external lookups.
  • web — enrich the persona with a quick live lookup so details reflect current real-world data.
  • research — run deeper research for the strongest real-world grounding.
Request

Start an enhancement

The POST returns 200 OK straight away. It does not wait for the persona; it gives you an id used with the enhancement repository route.
string
The enhancement’s identifier. Use it to poll for the result.
string
Always pending in this response — the enhancement has been accepted and queued.
200 OK
Enhancement rewrites your text into a full persona, so it does not return on the POST. research grounding runs deeper lookups before rewriting and can take longer to finish. That is why this endpoint hands back an id to poll rather than holding the connection open. Poll on an interval of a few seconds, and prefer off or web grounding when you need a fast result.

Poll for the result

Call GET with the returned id until status is succeeded or failed.
string
The enhancement’s identifier, the same value you started.
string
Where the enhancement is in its lifecycle. One of:
  • pending — accepted and queued; rewriting has not started yet.
  • running — grounding and rewriting are under way.
  • succeeded — finished; persona holds the enhanced persona.
  • failed — finished; error contains a stable failure category.
pending and running are not terminal — keep polling. succeeded and failed are terminal — stop polling.
string
The original persona text you sent, echoed back.
string
The grounding level the request ran with (off, web, or research).
object
The enhanced persona, present only when status is succeeded. Its shape is described under The persona below.
string
A stable failure category such as provider_error. Present only when status is failed.
While the persona is still being rewritten, the poll reports pending or running and carries no persona yet:
200 OK (running)

The persona

When status is succeeded, the poll carries the enhanced persona under persona — the same shape as one entry in the Personas personas array.
string
Stable identifier for this persona.
object
A flat map of field name to string value. The keys are inferred from your input text; values are always strings, including numeric ones (for example "age": "30").
string
A prompt that makes a model role-play as this persona. Always present.
string
A formatted character sheet. Always present.
200 OK (succeeded)

When enhancement fails

If enhancement fails after the request is accepted, the poll still returns 200 OK with status: "failed" and an error instead of a persona:
200 OK (failed)
Branch on the poll’s status and error, not on the HTTP status of the poll — a failed enhancement is reported with 200 OK. Start a new enhancement to retry; do not keep polling a failed one.

Errors

Errors arrive in two places: a bad request is rejected at the POST, and a failure during rewriting surfaces on the poll. The POST returns one of these before any enhancement is started: A rejected POST returns the standard error envelope. For example, an empty persona:
422 Unprocessable Entity
Once the POST returns 200, a later failure appears on the poll as status: "failed" with error: "provider_error" (a stable, opaque failure category). Start a fresh enhancement to retry. See Errors for the full envelope shape.

Example

Start the enhancement, then poll its repository route until it reaches a terminal status and read the persona from persona.
Because the field set is inferred from your text, read the keys you need from the persona.fields map rather than assuming a fixed shape.

Next

  • Validate personas — score the enhanced persona against the quality gates.
  • Personas — generate a whole population from a prompt instead.
  • Errors — the full error model and how to recover.