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

PublicApiKey

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

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

get

/agents/{id}/sessions

HTTPcURLJavaScriptPython

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

PublicApiKey

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

application/json

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

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

post

/agents/{id}/sessions/history

HTTPcURLJavaScriptPython

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

PublicApiKey

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

application/json

keystringRequired

labelstring · max: 255 · nullableOptional

Responses

200

Session renamed

No content

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

post

/agents/{id}/sessions/rename

HTTPcURLJavaScriptPython

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

PublicApiKey

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

application/json

keystringRequired

Responses

200

Session archived

No content

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

post

/agents/{id}/sessions/archive

HTTPcURLJavaScriptPython

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

PublicApiKey

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

application/json

keystringRequired

Responses

200

Session deleted

No content

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

post

/agents/{id}/sessions/delete

HTTPcURLJavaScriptPython

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

PublicApiKey

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

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

get

/agents/{id}/archives

HTTPcURLJavaScriptPython

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

PublicApiKey

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

application/json

filenamestringRequired

labelstring · max: 255Optional

Responses

200

Session restored

No content

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

post

/agents/{id}/archives/restore

HTTPcURLJavaScriptPython

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

PublicApiKey

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

application/json

filenamestringRequired

Responses

200

Archive deleted

No content

401

Unauthorized — Invalid or missing API key

application/json

403

Forbidden — Key lacks the required scope

application/json

post

/agents/{id}/archives/delete

HTTPcURLJavaScriptPython

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