Personas

Personas are custom system prompts that shape the LLM's behavior per user. If a user has an active persona, its system_prompt is injected into every conversation automatically — no need to pass it in the messages array.

You can also override the active persona on a per-request basis by passing persona_id in the /v1/chat/completions request body. This uses the specified persona for that request only, without changing the user's active persona. If persona_id is omitted, the active persona is used. See Chat Completions for details.

If you need to override the agent's built-in prompt for a single request, send a system or developer message in /v1/chat/completions. Your message replaces the agent's base instructions, but the active persona and memory context are still injected.

All persona endpoints require a Bearer token from TIE Auth.

List Personas

Returns both preset personas (system-defined personas available to all users; these cannot be edited or deleted) and custom personas created by the current user. The is_active flag indicates which persona is currently selected.

GET https://your-tie-host/personas
Authorization: Bearer $TOKEN

Response:

[
  {
    "id": "preset-formal",
    "name": "Formal Writer",
    "description": "Writes in formal, professional tone",
    "system_prompt": "You always write in a formal, professional tone.",
    "is_preset": true,
    "is_active": false,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  {
    "id": "custom-abc123",
    "name": "My Coach",
    "description": "Life coaching persona",
    "system_prompt": "You are a supportive life coach...",
    "is_preset": false,
    "is_active": true,
    "created_at": "2026-03-20T10:00:00Z",
    "updated_at": "2026-03-20T10:00:00Z"
  }
]

Create a Custom Persona

POST https://your-tie-host/personas
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Formal Writer",
  "description": "Writes in formal tone",
  "system_prompt": "You always write in a formal, professional tone."
}

Returns the created persona object with HTTP status 201 Created. Only name and system_prompt are required; description is optional.

Set Active Persona

PUT https://your-tie-host/personas/active/{persona_id}
Authorization: Bearer $TOKEN

Response:

{ "status": "active", "persona_id": "preset-formal" }

Get Active Persona

GET https://your-tie-host/personas/active
Authorization: Bearer $TOKEN

Returns the active persona object, or 404 if no persona is active.

Clear Active Persona

Reverts to default behavior (no custom system prompt).

DELETE https://your-tie-host/personas/active
Authorization: Bearer $TOKEN

Response:

{ "status": "cleared" }

Update a Custom Persona

PUT https://your-tie-host/personas/{persona_id}
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Updated Name",
  "system_prompt": "Updated prompt..."
}

Returns the updated persona object, or 404 if the persona does not exist, is not owned by the current user, or is a preset.

Delete a Custom Persona

DELETE https://your-tie-host/personas/{persona_id}
Authorization: Bearer $TOKEN

Response:

{ "status": "deleted", "persona_id": "custom-abc123" }

Returns 404 if the persona does not exist, is not owned by the current user, or is a preset.