> ## 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.

# Conversations

> Server-owned conversations: HASP holds the transcript, so multi-turn context, PHI mode, and the audit trail live on the server rather than in your application.

A **server-owned conversation** moves custody of the transcript to HASP. Instead of replaying the full message history on every request, you open a conversation, reference it, and HASP stores and retrieves the turns — with the transcript inside the compliance boundary and every content read recorded as a disclosure.

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

<Note>
  Ownership is per-credential, not per-org. A conversation opened by one API key or agent credential is not readable by another, even within the same org. The capability makes the resource reachable; ownership decides which rows you can touch.
</Note>

## Open a conversation

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

### Body

| Field              | Type   | Description                                                                                                                                                                 |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`            | string | Optional human-readable label.                                                                                                                                              |
| `phi_mode`         | string | Whether PHI is permitted in this conversation. Resolved against the org's policy — a request for a mode the org does not allow is rejected rather than silently downgraded. |
| `agent_version_id` | string | Optional agent version to bind the conversation to, fixing the persona for its lifetime.                                                                                    |

## List conversations

```
GET https://api.usehasp.com/v1/conversations
Authorization: Bearer hasp_api_live_...
```

Returns the caller's own conversations, most recently updated first, cursor-paginated. Metadata only — no transcript content.

## Fetch and update metadata

```
GET   https://api.usehasp.com/v1/conversations/{conversation}
PATCH https://api.usehasp.com/v1/conversations/{conversation}
```

`PATCH` accepts the same fields as create; send only what you want to change. Raising `phi_mode` to allow PHI is permanent for that conversation — once a transcript may have contained PHI, it is treated as PHI-bearing for retention and disclosure purposes even if the mode is lowered again.

## Read the transcript

```
GET https://api.usehasp.com/v1/conversations/{conversation}/messages
Authorization: Bearer hasp_api_live_...
```

Returns turns oldest-first, cursor-paginated. **This is a content read and emits an audit event** — unlike the metadata endpoints above.

## Export a transcript

```
GET https://api.usehasp.com/v1/conversations/{conversation}/export
Authorization: Bearer hasp_api_live_...
```

Returns the whole transcript in one response. Export decrypts and serialises every message at once, so it is capped; a capped response reports `truncated: true` alongside the real `total_message_count` rather than looking complete. Page through `/messages` when a conversation exceeds the cap.

## List attachments

```
GET https://api.usehasp.com/v1/conversations/{conversation}/attachments
Authorization: Bearer hasp_api_live_...
```

Metadata for the [files](/ai-api/control/files) bound to the conversation — no bytes and no transcript text, so this sits on the metadata side of the disclosure boundary and does not emit a disclosure event.

## Errors

| Code                          | HTTP | Meaning                                                             |
| ----------------------------- | ---- | ------------------------------------------------------------------- |
| `CONVERSATION_OWNER_REQUIRED` | 403  | The conversation belongs to a different credential.                 |
| `NOT_FOUND`                   | 404  | No such conversation for this caller.                               |
| `VALIDATION_FAILED`           | 422  | Unknown `phi_mode`, or an `agent_version_id` that does not resolve. |