Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sessions

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

List agent sessions

get

Returns active chat sessions for an agent. Requires agent:manage scope.

Authorizations
AuthorizationstringRequired

API key sent as Bearer token. Two types:

  • Master key (g_master_...): full access to all agents and endpoints.
  • Agent key (g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Responses
200

List of sessions

application/json
keystringOptional
sessionIdstring · uuidOptional
sessionFilestringOptional
labelstring · nullableOptional
updatedAtintegerOptional

Unix timestamp in milliseconds

chatTypestringOptional
lastChannelstringOptional
originobjectOptional
get/agents/{id}/sessions
GET /api/v1/agents/{id}/sessions HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "key": "text",
    "sessionId": "123e4567-e89b-12d3-a456-426614174000",
    "sessionFile": "text",
    "label": "text",
    "updatedAt": 1,
    "chatType": "text",
    "lastChannel": "text",
    "origin": {}
  }
]

Get session history

post

Returns message history for a specific session. Requires agent:manage scope.

Authorizations
AuthorizationstringRequired

API key sent as Bearer token. Two types:

  • Master key (g_master_...): full access to all agents and endpoints.
  • Agent key (g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Body
sessionKeystringRequired
limitinteger · min: 1 · max: 1000Optional
Responses
200

Session message history

application/json
idstringOptional
rolestring · enumOptionalPossible values:
contentone ofOptional

String or array of content blocks

stringOptional
or
timestampintegerOptional
post/agents/{id}/sessions/history
POST /api/v1/agents/{id}/sessions/history HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "sessionKey": "text",
  "limit": 1
}
[
  {
    "id": "text",
    "role": "user",
    "content": "text",
    "timestamp": 1
  }
]

Rename a session

post

Renames a chat session. Requires agent:manage scope.

Authorizations
AuthorizationstringRequired

API key sent as Bearer token. Two types:

  • Master key (g_master_...): full access to all agents and endpoints.
  • Agent key (g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Body
keystringRequired
labelstring · max: 255 · nullableOptional
Responses
200

Session renamed

No content
post/agents/{id}/sessions/rename
POST /api/v1/agents/{id}/sessions/rename HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "key": "text",
  "label": "text"
}
No content

Archive a session

post

Archives a chat session. Requires agent:manage scope.

Authorizations
AuthorizationstringRequired

API key sent as Bearer token. Two types:

  • Master key (g_master_...): full access to all agents and endpoints.
  • Agent key (g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Body
keystringRequired
Responses
200

Session archived

No content
post/agents/{id}/sessions/archive
POST /api/v1/agents/{id}/sessions/archive HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "key": "text"
}
No content

Delete a session

post

Permanently deletes a chat session. Requires agent:manage scope.

Authorizations
AuthorizationstringRequired

API key sent as Bearer token. Two types:

  • Master key (g_master_...): full access to all agents and endpoints.
  • Agent key (g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Body
keystringRequired
Responses
200

Session deleted

No content
post/agents/{id}/sessions/delete
POST /api/v1/agents/{id}/sessions/delete HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "key": "text"
}
No content

List archived sessions

get

Returns archived chat sessions for an agent. Requires agent:manage scope.

Authorizations
AuthorizationstringRequired

API key sent as Bearer token. Two types:

  • Master key (g_master_...): full access to all agents and endpoints.
  • Agent key (g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Responses
200

List of archived sessions

application/json
filenamestringOptional
labelstring · nullableOptional
archivedAtstringOptional
sessionIdstringOptional
get/agents/{id}/archives
GET /api/v1/agents/{id}/archives HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "filename": "text",
    "label": "text",
    "archivedAt": "text",
    "sessionId": "text"
  }
]

Restore an archived session

post

Restores an archived session back to active. Requires agent:manage scope.

Authorizations
AuthorizationstringRequired

API key sent as Bearer token. Two types:

  • Master key (g_master_...): full access to all agents and endpoints.
  • Agent key (g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Body
filenamestringRequired
labelstring · max: 255Optional
Responses
200

Session restored

No content
post/agents/{id}/archives/restore
POST /api/v1/agents/{id}/archives/restore HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "filename": "text",
  "label": "text"
}
No content

Delete an archived session

post

Permanently deletes an archived session. Requires agent:manage scope.

Authorizations
AuthorizationstringRequired

API key sent as Bearer token. Two types:

  • Master key (g_master_...): full access to all agents and endpoints.
  • Agent key (g_agent_...): scoped to a single agent with specific permissions.
Path parameters
idstring · uuidRequired
Body
filenamestringRequired
Responses
200

Archive deleted

No content
post/agents/{id}/archives/delete
POST /api/v1/agents/{id}/archives/delete HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "filename": "text"
}
No content
PreviousChat
NextBilling

Last updated