Skip to main content
GET
/
api
/
v1
/
agents
/
{agentId}
/
conversations
/
{convId}
/
messages
List messages in a conversation (paged by offset).
curl --request GET \
  --url https://openapi.beeos.ai/api/v1/agents/{agentId}/conversations/{convId}/messages \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "data": {
    "messages": [
      {
        "message_id": "<string>",
        "offset": 123,
        "type": "<string>",
        "publisher_id": "<string>",
        "in_reply_to": "<string>",
        "payload": "<unknown>",
        "created_at": "2023-11-07T05:31:56Z",
        "body": "<string>",
        "parts": [
          {
            "type": "<string>",
            "text": "<string>"
          }
        ],
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "latest_offset": 123
  }
}

Authorizations

​
Authorization
string
header
required

Pass a user JWT or a oag_ User API Key on the Authorization: Bearer <token> header. Both are validated by openapi-gateway against the Auth service.

Both credential types are user-scoped: every key (and every JWT) is bound to exactly one owner, and every route grants the caller full access to that owner's own resources. Cross-tenant access is denied by owner-ACL inside the handlers — there is no per-route scope vocabulary on this API.

Removed in v1.1.0: the legacy agents:* / tasks:* / files:* / instances:* scope set has been dropped together with the 403 insufficient_scope error. Existing oag_ keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passed scopes to createAPIKey should drop the argument. See the changelog at the bottom of this spec for the full migration note.

Path Parameters

​
agentId
string
required
Maximum string length: 128
​
convId
string
required
Maximum string length: 128

Query Parameters

​
since
integer<int64>

Return messages with offset > since. Combine with limit for paginated reads. Default is 0 (start of conversation).

Required range: x >= 0
​
limit
integer<int32>
Required range: 1 <= x <= 200
​
include_deltas
boolean
default:false

When true, include ephemeral streaming chunk rows (agent_reply_delta, agent_thought_chunk, agent_message_chunk) in the response. Default false. Accepts true|1|yes (case-insensitive); any other value is treated as false.

Response

Page of messages.

​
success
boolean
required
​
data
object
required