API reference

Personas API

Create, read, update and delete your AI personas.

A persona is a reusable bundle of instruction and sampling settings that shapes how the Krallo AI responds — a system_prompt that steers its behaviour plus the tuning knobs (temperature, max_tokens, top_p, and the two penalties). The /api/v1/personas endpoints let you manage your personas programmatically, so you can build, version and delete them from your own tooling. Attach a persona to an inference call to make the AI answer in that voice; see Chat completions.

The persona object

Every endpoint that returns a persona serializes it with exactly these fields:

The underlying model is deliberately not part of the persona object and cannot be set through this API — model selection is governed by Krallo’s server-side routing. Responses use the native Krallo envelope: successful bodies are wrapped as { "data": …, "meta": { "request_id": … } }, and errors as { "error": { "code", "message", … }, "meta": … }. See Errors for the full contract.

Scopes

Each persona operation requires the matching scope on your API key:

A request missing the required scope returns 403 insufficient_scope with the needed scope echoed in error.required_scope. Grant scopes when you mint a key in the Developer console; see Scopes and Authentication.

List personas

Returns your personas as a JSON array. Only personas you own are included; personas belonging to other owners (or bound to a guild rather than a user) are never returned. Requires personas:read. There are no query parameters — the full owned set is returned.

Request

curl https://exe.krallo.com/api/v1/personas \
  -H "Authorization: Bearer krallo_live_..."

Response

{
  "data": [
    {
      "id": 412,
      "name": "Release Notes Writer",
      "description": "Terse, factual changelog voice.",
      "system_prompt": "You write concise, factual release notes. No marketing language.",
      "icon_emoji": "📝",
      "temperature": 0.4,
      "max_tokens": 800,
      "top_p": 1,
      "frequency_penalty": 0,
      "presence_penalty": 0,
      "locked": false,
      "message_count": 37
    }
  ],
  "meta": { "request_id": "5f3a91c0-b2d4-4e16-9a58-c07d2f4b8e31" }
}

An owner with no personas receives "data": [] with a 200 status.

Create a persona

Creates a persona owned by your account and returns it. Requires personas:write. Responds 201 Created on success. Body is JSON. Unknown fields are ignored.

Body parameters

Omit any optional field to leave it unset (it will serialize as null, and the server default applies at inference time). The model is not accepted here.

Validation

Validation runs before the call is billed, so a rejected create costs nothing:

• name and system_prompt are required. A missing or blank value returns 400 invalid_request ("'name' is required." / "'system_prompt' is required.").
• Wrong types are rejected, not coerced. A present-but-non-numeric value for any sampling field returns 400 — e.g. "temperature": "hot" gives "'temperature' must be a number.", and a non-integer max_tokens gives "'max_tokens' must be an integer."
• Out-of-range numbers are rejected with a message naming the allowed bounds (see the ranges above).
• Over-length strings are rejected for name, system_prompt, description and icon_emoji.

Request

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 marketing language.",
    "description": "Terse, factual changelog voice.",
    "icon_emoji": "📝",
    "temperature": 0.4,
    "max_tokens": 800
  }'

Response

{
  "data": {
    "id": 412,
    "name": "Release Notes Writer",
    "description": "Terse, factual changelog voice.",
    "system_prompt": "You write concise, factual release notes. No marketing language.",
    "icon_emoji": "📝",
    "temperature": 0.4,
    "max_tokens": 800,
    "top_p": null,
    "frequency_penalty": null,
    "presence_penalty": null,
    "locked": false,
    "message_count": 0
  },
  "meta": { "request_id": "9c1e77aa-04f3-4b8d-a25c-6e19d0b74f82" }
}

Retrieve a persona

Returns one persona by id. Requires personas:read. An id you do not own, or one that does not exist, returns 404 not_found — the two cases are intentionally indistinguishable. A non-numeric path segment also returns 404.

Path parameters

Request

curl https://exe.krallo.com/api/v1/personas/412 \
  -H "Authorization: Bearer krallo_live_..."

Response

{
  "data": {
    "id": 412,
    "name": "Release Notes Writer",
    "description": "Terse, factual changelog voice.",
    "system_prompt": "You write concise, factual release notes. No marketing language.",
    "icon_emoji": "📝",
    "temperature": 0.4,
    "max_tokens": 800,
    "top_p": null,
    "frequency_penalty": null,
    "presence_penalty": null,
    "locked": false,
    "message_count": 37
  },
  "meta": { "request_id": "7a1d0e4b-83c2-4f61-95a8-d34e6b0c9f17" }
}

Update a persona

Applies a partial update and returns the full, updated persona. Requires personas:write. Send only the fields you want to change — any field you omit is left as-is. Responds 200 on success. PUT is accepted and behaves identically to PATCH (it is still a partial update, not a full replace).

Path parameters

Body parameters

All of the create fields are accepted, and all are optional here. Each is validated with the same rules and bounds as on create; a wrong-typed or out-of-range value returns 400 invalid_request and the persona is unchanged. The model is not accepted. An empty body is valid and is a no-op that returns the persona unchanged.

Request

curl -X PATCH https://exe.krallo.com/api/v1/personas/412 \
  -H "Authorization: Bearer krallo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "temperature": 0.2, "max_tokens": 1200 }'

Response

{
  "data": {
    "id": 412,
    "name": "Release Notes Writer",
    "description": "Terse, factual changelog voice.",
    "system_prompt": "You write concise, factual release notes. No marketing language.",
    "icon_emoji": "📝",
    "temperature": 0.2,
    "max_tokens": 1200,
    "top_p": null,
    "frequency_penalty": null,
    "presence_penalty": null,
    "locked": false,
    "message_count": 37
  },
  "meta": { "request_id": "c22f61a9-d04e-4b28-8c75-3a91e5f0d6b2" }
}

Delete a persona

Permanently deletes one persona by id. Requires personas:write. Deletion is owner-scoped: an id you do not own, or one that does not exist, returns 404 not_found. A locked persona cannot be deleted and returns 409 persona_locked.

Path parameters

Request

curl -X DELETE https://exe.krallo.com/api/v1/personas/412 \
  -H "Authorization: Bearer krallo_live_..."

Response

{
  "data": { "id": 412, "deleted": true },
  "meta": { "request_id": "e70b2c88-15d9-4a37-b642-90c1f5e8a3d4" }
}

Billing & rate limits

Every persona call — list, retrieve, create, update, and delete — is a flat metered request. Calls first draw down your app’s free daily allowance; once that is exhausted, and if wallet billing is enabled, each call debits a small, fixed number of credit units from the owner’s balance. If the wallet cannot cover a billable call, the request returns 402 insufficient_credits with required_units and balance in the error body, and nothing is changed. Validation failures on create/update are checked before billing, and refused or errored calls are refunded and do not burn quota. See Billing for the full model.

Requests are rate-limited per key by your app’s tier. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers (pre-auth 401/403 responses do not); exceeding the limit returns 429 with a Retry-After header. See Rate limits.

Errors

Persona endpoints can return the following errors, in addition to the standard bearer-auth failures:

Apart from the 429 noted above, all errors share the native envelope shape. For status semantics and retry guidance, see Errors. Related reading: Memories, Chat completions, and Authentication.