> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-reference/sessions.md).

# Sessions

Manage conversation sessions and archives. Requires `agent:manage` scope.

## List agent sessions

> Returns active chat sessions for an agent. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Session":{"type":"object","properties":{"key":{"type":"string"},"sessionId":{"type":"string","format":"uuid"},"sessionFile":{"type":"string"},"label":{"type":"string","nullable":true},"updatedAt":{"type":"integer","description":"Unix timestamp in milliseconds"},"chatType":{"type":"string"},"lastChannel":{"type":"string"},"origin":{"type":"object"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/sessions":{"get":{"tags":["Sessions"],"summary":"List agent sessions","description":"Returns active chat sessions for an agent. Requires `agent:manage` scope.\n","responses":{"200":{"description":"List of sessions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Session"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Get session history

> Returns message history for a specific session. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"ChatMessage":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"content":{"description":"String or array of content blocks","oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}]},"timestamp":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/sessions/history":{"post":{"tags":["Sessions"],"summary":"Get session history","description":"Returns message history for a specific session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionKey"],"properties":{"sessionKey":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":1000}}}}}},"responses":{"200":{"description":"Session message history","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Rename a session

> Renames a chat session. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/sessions/rename":{"post":{"tags":["Sessions"],"summary":"Rename a session","description":"Renames a chat session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"label":{"type":"string","maxLength":255,"nullable":true}}}}}},"responses":{"200":{"description":"Session renamed"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Archive a session

> Archives a chat session. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/sessions/archive":{"post":{"tags":["Sessions"],"summary":"Archive a session","description":"Archives a chat session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}}}}},"responses":{"200":{"description":"Session archived"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Delete a session

> Permanently deletes a chat session. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/sessions/delete":{"post":{"tags":["Sessions"],"summary":"Delete a session","description":"Permanently deletes a chat session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}}}}},"responses":{"200":{"description":"Session deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## List archived sessions

> Returns archived chat sessions for an agent. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Archive":{"type":"object","properties":{"filename":{"type":"string"},"label":{"type":"string","nullable":true},"archivedAt":{"type":"string"},"sessionId":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/archives":{"get":{"tags":["Sessions"],"summary":"List archived sessions","description":"Returns archived chat sessions for an agent. Requires `agent:manage` scope.\n","responses":{"200":{"description":"List of archived sessions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Archive"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Restore an archived session

> Restores an archived session back to active. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/archives/restore":{"post":{"tags":["Sessions"],"summary":"Restore an archived session","description":"Restores an archived session back to active. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename"],"properties":{"filename":{"type":"string"},"label":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"Session restored"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Delete an archived session

> Permanently deletes an archived session. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/archives/delete":{"post":{"tags":["Sessions"],"summary":"Delete an archived session","description":"Permanently deletes an archived session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename"],"properties":{"filename":{"type":"string"}}}}}},"responses":{"200":{"description":"Archive deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```
