Build with the AI

Personas

Attach one of your AI personas to completions, and manage personas over the API.

A persona is a named, reusable system prompt (plus optional sampling defaults) that shapes how the model responds. There are two things you can do with personas through the API:

• Use a persona in chat completions — its system_prompt is prepended to every request, so you don’t have to resend a long system message each time.
• Manage personas programmatically — create, read, update, and delete them under /api/v1/personas.

Attach a persona to completions

When a persona is in effect, its system_prompt is inserted as a leading system message ahead of the messages you send to /api/v1/chat/completions. The persona text is only ever sent upstream to the model — it is never echoed back in the response body. There are two ways to select the persona for a request, in priority order.

Pin a persona to your app

Open the Developer console at /ops/dev, edit your app, and set its AI persona. Once pinned, that persona is applied to every /chat/completions call made with any key belonging to that app — no per-request field required. Leave it unset for no persona (the default).

Override per request

Add a persona field to the completion body, set to the integer id of the persona. A per-request persona overrides whatever is pinned to the app for that one call.

curl https://exe.krallo.com/api/v1/chat/completions \
  -H "Authorization: Bearer krallo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krallo-chat",
    "persona": 42,
    "messages": [{"role": "user", "content": "Draft a one-line release note."}]
  }'

The response is a standard OpenAI chat.completion object, unchanged in shape whether or not a persona is attached. See Chat completions for the full request and response reference.

Which personas you can use

A persona is usable in a completion only if it is one of the following:

• Your own — a persona you created (matched across all of your linked identities, not just the app’s canonical owner id).
• A built-in SYSTEM persona — the platform’s shared personas, available to everyone.
• An owner-less global persona.

Guild-scoped personas (owned by a server rather than a user) are deliberately not usable through the developer API. If you send a persona id that doesn’t exist or isn’t one of the above, the request returns 400 and the model is never run (and you are not billed for it):

{
  "error": {
    "message": "Persona '42' was not found or does not belong to you.",
    "type": "invalid_request_error"
  }
}

What attaching a persona changes

Attaching a persona affects only the system prompt. Specifically:

Manage personas over the API

The native /api/v1/personas resource is standard REST returning the Krallo envelope ({ "data": …, "meta": { "request_id": … } }), not the OpenAI wire format. Reads require the personas:read scope; writes require personas:write. Each call is flat-metered against your wallet — see Billing & quotas.

The persona object

Every persona endpoint returns objects with this shape:

{
  "id": 128,
  "name": "Release Notes Writer",
  "description": "House voice for changelog entries",
  "system_prompt": "You write concise, factual release notes...",
  "icon_emoji": "📝",
  "temperature": 0.4,
  "max_tokens": 1200,
  "top_p": null,
  "frequency_penalty": null,
  "presence_penalty": null,
  "locked": false,
  "message_count": 0
}

Create a persona

name and system_prompt are required; every other field is optional. The request is validated before it is billed, so a rejected create costs nothing. On success you get 201 with the full persona object.

curl https://exe.krallo.com/api/v1/personas \
  -H "Authorization: Bearer krallo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Release Notes Writer",
    "system_prompt": "You write concise, factual release notes. No hype.",
    "description": "House voice for changelog entries",
    "icon_emoji": "📝",
    "temperature": 0.4,
    "max_tokens": 1200
  }'

{
  "data": {
    "id": 128,
    "name": "Release Notes Writer",
    "description": "House voice for changelog entries",
    "system_prompt": "You write concise, factual release notes. No hype.",
    "icon_emoji": "📝",
    "temperature": 0.4,
    "max_tokens": 1200,
    "top_p": null,
    "frequency_penalty": null,
    "presence_penalty": null,
    "locked": false,
    "message_count": 0
  },
  "meta": { "request_id": "req_..." }
}

Update a persona

Updates are partial: send only the fields you want to change, and any field you omit is left unchanged. (There is no way to reset an advanced field back to null through the API — omitting it means “keep the current value.”) The same length and range rules as create apply to whatever you do send. PUT behaves identically. On success you get 200 with the updated object.

curl -X PATCH https://exe.krallo.com/api/v1/personas/128 \
  -H "Authorization: Bearer krallo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "temperature": 0.2, "system_prompt": "You write terse, factual release notes." }'

List, retrieve, and delete

GET /api/v1/personas returns an array (in data) of the personas you own; GET /api/v1/personas/{id} returns a single object, or 404 if the id is unknown or not yours. Deleting returns a small confirmation:

{
  "data": { "id": 128, "deleted": true },
  "meta": { "request_id": "req_..." }
}

Locked personas

A persona with "locked": true is protected. A PATCH/PUT or DELETE against it returns 409 with code persona_locked and leaves the persona untouched. Locked personas are still usable in completions.

Field limits and validation

Validation runs before billing on both create and update. A violation returns 400 with code invalid_request and a message naming the offending field. A present-but-wrong-typed value (for example a string where a number is expected) is rejected rather than silently dropped.

Errors

Persona endpoints can return the following. See Errors for the full catalog and envelope details.

Related pages

• Personas API reference — full parameter tables per endpoint.
• Chat completions — the endpoint personas attach to.
• Scopes — personas:read and personas:write.
• Memories — the other half of programmatic AI configuration.
• Billing & quotas — how metered calls are charged.