> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Export and retention
> Export a complete conversation for review, and know when conversation data is deleted and what is kept.
An **export** reconstructs one conversation as a single JSON document for a compliance reviewer or an auditor: every message on every branch, every config version that answered, every tool event, every guardrail decision, and every annotation that has not been retracted. **Retention** is the instance setting that deletes conversation content after a period of inactivity.
## Export a conversation
`GET /api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/export?end_user=...`
Credential: an organization API key, or a scoped key with `conversations:export`. `conversations:use` alone is not enough, because an export is a bulk disclosure rather than a conversational read. The `end_user` must match the conversation; a mismatch is `404 conversation_not_found`.
```bash curl theme={null}
curl "https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations/9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93/export?end_user=u_dana_ortiz" \
-H "Authorization: Bearer $NEXIO_API_KEY" \
-o conversation-export.json
```
```python Python theme={null}
import os
import json
import requests
resp = requests.get(
"https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations/9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93/export",
headers={"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]},
params={"end_user": "u_dana_ortiz"},
)
resp.raise_for_status()
with open("conversation-export.json", "w") as fh:
json.dump(resp.json(), fh, indent=2)
```
```typescript TypeScript theme={null}
import { writeFile } from "node:fs/promises"
const resp = await fetch(
"https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations/9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93/export?end_user=u_dana_ortiz",
{ headers: { Authorization: `Bearer ${process.env.NEXIO_API_KEY}` } },
)
if (!resp.ok) throw new Error(`export: ${resp.status}`)
await writeFile("conversation-export.json", JSON.stringify(await resp.json(), null, 2))
```
Response `200`:
```json theme={null}
{
"export_version": "1",
"generated_at": "2026-09-23T17:00:12.004381Z",
"conversation": {
"id": "9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93",
"org_id": "2c7e4a19-8d3b-4f60-a5e1-9b0d6c3f7a28",
"environment": "live",
"instance_id": "3b9d2f4e-8a1c-4e57-9f02-6c1d8e7a5b34",
"end_user": "u_dana_ortiz",
"title": "Getting started",
"status": "active",
"created_at": "2026-09-23T14:02:11.482913Z",
"updated_at": "2026-09-23T14:10:44.912305Z"
},
"messages": [
{
"id": "c7d1e5a3-2f84-4b6c-9e0a-1b3d5f7a9c28",
"role": "user",
"content": [{ "type": "text", "text": "Summarize the runs that failed today." }],
"turn_id": "5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75",
"config_version_hash": "4f1c9a7e2b8d3065",
"created_at": "2026-09-23T14:02:13.118402Z",
"parent_message_id": null
},
{
"id": "d91a6c38-4e2f-4b75-8a0d-5c3e7b1f2a96",
"role": "assistant",
"content": [{ "type": "tool_use", "id": "call_Rk3v8QmT2xLp", "name": "runs.list", "input": { "status": "FAILED" }, "execution": "platform" }],
"turn_id": "5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75",
"config_version_hash": "4f1c9a7e2b8d3065",
"created_at": "2026-09-23T14:02:15.640217Z",
"parent_message_id": "c7d1e5a3-2f84-4b6c-9e0a-1b3d5f7a9c28"
}
],
"config_versions": [
{ "hash": "4f1c9a7e2b8d3065", "released_version": "1" }
],
"tool_events": [
{
"id": "6b0e2d57-9a3c-4f18-b7e4-1c5a8d3f0e62",
"turn_id": "5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75",
"tool_name": "runs.list",
"execution": "platform",
"outcome": "ok",
"duration_ms": 184,
"created_at": "2026-09-23T14:02:15.829441Z"
}
],
"guardrail_events": [],
"annotations": []
}
```
The `messages` array above is shortened to two entries for this page; a real export holds every message.
### Document fields
| Field | Meaning |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `export_version` | Contract version of this document. Currently `"1"`. |
| `generated_at` | When the export was built. |
| `conversation` | The header: `id`, `org_id`, `environment`, `instance_id`, `end_user`, `title`, `status`, `created_at`, `updated_at`. |
| `messages` | Every message in insertion order, on every branch. Unlike the conversation GET, there is no 500-message window and no served-branch filter. `parent_message_id` shows how versions relate. Messages have no `branch` field here. |
| `config_versions` | Every config hash that answered a message, with `released_version` (the integer version as a string) when that hash was released. |
| `tool_events` | One row per recorded tool outcome, so a confirm-gated call has a `pending_confirmation` row and another row once the user decides. A call to a tool name the assistant does not have gets no row. Fields: `tool_name`, `execution` (`platform` or `client`), `outcome` (`ok`, `error`, `invalid_input`, `pending_confirmation`, `denied`, `approved`), `duration_ms`. |
| `guardrail_events` | Every guardrail decision: `rule_id`, `decision` (`refused`, `escalated`, `output_check_triggered`), and the `config_version_hash` in force. |
| `annotations` | Every annotation on the conversation that has not been retracted. |
Internal bookkeeping blocks never appear in message content, the same as on every other read.
Errors: `400 invalid_request` (missing `end_user`), `401 unauthorized`, `403 insufficient_capability`, `403 instance_archived`, `404 instance_not_found`, `404 conversation_not_found`.
## Retention
`retention.conversation_days` in the instance config sets how long an inactive conversation is kept. See [Instance configuration](/conversations/configuration#retention).
| Setting | Effect |
| ---------------------- | ------------------------------------------------------------------------ |
| `null` (default) | Conversations are kept. |
| A positive integer `N` | A conversation whose last activity is more than `N` days old is deleted. |
How deletion works:
* The policy is read from the instance's latest **published** version. An instance that has never been published has no policy in force. A follower uses the policy of the instance it follows.
* A deletion pass runs once a day.
* Deletion is permanent: the conversation and its messages are removed.
* Audit records are kept: tool events, guardrail events, usage records, and annotations survive the deletion of the conversation content.
* An archived conversation is still subject to retention.
Attachments have their own clock. `attachments.retention_days` removes a file after that many days; `null` makes it follow the conversation. After a conversation is deleted, its remaining attachments are swept right after, in the same daily pass. Stored bytes become eligible for removal one hour after an attachment is deleted, and the next daily pass removes them. See [Attachments](/conversations/attachments#retention).
The generated endpoint contract.
Where conversation data goes and why.