> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personas

> Personas are named, versioned system-prompt layers — authored privately, published, and optionally promoted into the org library.

A **persona** is a named, versioned instruction layer applied on top of HASP's own base behaviour. Personas move through an explicit draft → published lifecycle so that what a caller gets is always a specific, auditable version rather than whatever the prompt happened to say today.

Requires the `persona.read` / `persona.write` capabilities.

## Lifecycle

```
create ──► draft ──publish──► published ──revise──► draft (new version)
                                   │
                                promote ──► org-library persona (admin only)
```

* **Draft** — private to its creator and editable in place.
* **Published** — immutable. Editing a published persona means calling `revise` to open a fresh draft, not `PATCH`.
* **Promoted** — an admin lifts a private persona into the org library, where it becomes selectable by other members.

## Create

```
POST https://api.usehasp.com/v1/personas
Authorization: Bearer hasp_api_live_...
Content-Type: application/json
```

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| `name`        | string | **Required.** Display name.                          |
| `persona`     | string | **Required.** The instruction text.                  |
| `description` | string | Optional short description shown alongside the name. |

Created personas start private and in draft.

## List and retrieve

```
GET https://api.usehasp.com/v1/personas
GET https://api.usehasp.com/v1/personas/{persona_id}
```

The list returns personas visible to the caller — their own, plus published org-library personas. Retrieval follows the same visibility rule.

## Update a draft

```
PATCH https://api.usehasp.com/v1/personas/{persona_id}
```

Takes the same fields as create. Fails with `PERSONA_ALREADY_DRAFT` or `PERSONA_NO_DRAFT` when the persona is not in a state that accepts an in-place edit — call `revise` first if the current version is published.

## Publish, revise, promote

```
POST https://api.usehasp.com/v1/personas/{persona_id}/publish
POST https://api.usehasp.com/v1/personas/{persona_id}/revise
POST https://api.usehasp.com/v1/personas/{persona_id}/promote
```

* **`publish`** freezes the current draft as a published version.
* **`revise`** opens a new draft from the currently published version.
* **`promote`** is admin-only and requires the persona to be private; it returns `PERSONA_NOT_PRIVATE` otherwise and `ORG_ADMIN_REQUIRED` for non-admins.

## Delete

```
DELETE https://api.usehasp.com/v1/personas/{persona_id}
```

Only private personas can be deleted.

## Org default persona

```
GET https://api.usehasp.com/v1/assistant/persona
PUT https://api.usehasp.com/v1/assistant/persona
```

Reads and sets the organization's default persona, applied when a caller has not selected one explicitly. `PUT` takes a single `persona` field.

## Errors

| Code                    | HTTP | Meaning                                             |
| ----------------------- | ---- | --------------------------------------------------- |
| `PERSONA_NO_DRAFT`      | 422  | The action needs a draft version and there is none. |
| `PERSONA_ALREADY_DRAFT` | 422  | The action would create a second draft.             |
| `PERSONA_NOT_PRIVATE`   | 422  | Promotion requires a private persona.               |
| `ORG_ADMIN_REQUIRED`    | 403  | Promotion is admin-only.                            |