Skip to main content
POST https://api.humalike.com/v1/personas/actions/enhance
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

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

​
Request body

​
persona
string
required
The existing persona text to deepen. Must be a non-empty string.
​
grounding
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
{
  "persona": "Sam is a 30-year-old support main. Friendly. Plays Thresh.",
  "grounding": "off"
}

​
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.
​
id
string
The enhancement’s identifier. Use it to poll for the result.
​
status
string
Always pending in this response — the enhancement has been accepted and queued.
200 OK
{
  "id": "b06f6aae-bcf6-4157-b241-7e19c9182a70",
  "status": "pending"
}
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

GET https://api.humalike.com/v1/personas/repositories/Enhancement/by-id/{id}
Call GET with the returned id until status is succeeded or failed.
​
id
string
The enhancement’s identifier, the same value you started.
​
status
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.
​
source
string
The original persona text you sent, echoed back.
​
grounding
string
The grounding level the request ran with (off, web, or research).
​
persona
object
The enhanced persona, present only when status is succeeded. Its shape is described under The persona below.
​
error
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)
{
  "id": "b06f6aae-bcf6-4157-b241-7e19c9182a70",
  "status": "running",
  "source": "Sam is a 30-year-old support main. Friendly. Plays Thresh.",
  "grounding": "off",
  "persona": null
}

​
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.
​
persona_id
string
Stable identifier for this persona.
​
fields
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").
​
system_prompt
string
A prompt that makes a model role-play as this persona. Always present.
​
markdown
string
A formatted character sheet. Always present.
200 OK (succeeded)
{
  "id": "b06f6aae-bcf6-4157-b241-7e19c9182a70",
  "status": "succeeded",
  "source": "Sam is a 30-year-old support main. Friendly. Plays Thresh.",
  "grounding": "off",
  "persona": {
    "persona_id": "p_01",
    "fields": {
      "name": "Sam Okafor",
      "age": "30",
      "main_role": "support",
      "main_champion": "Thresh",
      "play_style": "warm but sharp, runs the map from the shadows",
      "backstory": "Fell for support after carrying a friend group through normals for years; has mained Thresh since release and shot-calls for a club team."
    },
    "system_prompt": "You are Sam Okafor, a warm-but-sharp Thresh support...",
    "markdown": "# Sam Okafor\n\n_Warm-but-sharp Thresh support..._"
  },
  "error": null
}

​
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)
{
  "id": "b06f6aae-bcf6-4157-b241-7e19c9182a70",
  "status": "failed",
  "error": "provider_error"
}
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:
StatusCodeWhen
401UNAUTHORIZEDThe bearer token is missing, invalid, or expired.
402PAYMENT_REQUIREDYour credit balance can’t cover the request. See Credits and billing.
422validation_failedpersona is missing or empty.
A rejected POST returns the standard error envelope. For example, an empty persona:
422 Unprocessable Entity
{
  "error": {
    "code": "validation_failed",
    "message": "request validation failed",
    "details": [{ "loc": ["persona"], "msg": "String should have at least 1 character", "type": "string_too_short" }]
  }
}
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. 
# Start the enhancement — returns 200 with an id.
curl https://api.humalike.com/v1/personas/actions/enhance \
  -H "Authorization: Bearer $HUMALIKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": "Sam is a 30-year-old support main. Friendly. Plays Thresh.",
    "grounding": "off"
  }'

# Poll the enhancement (repeat until status is "succeeded" or "failed").
curl https://api.humalike.com/v1/personas/repositories/Enhancement/by-id/b06f6aae-bcf6-4157-b241-7e19c9182a70 \
  -H "Authorization: Bearer $HUMALIKE_TOKEN"
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.