Skip to content
CCS Chat Docs

List messages

GET
/api/v1/tenants/{tenant_id}/applications/{application_id}/conversations/{conversation_id}/messages
curl --request GET \
  --url 'https://chat.centralcodestation.com/api/v1/tenants/example/applications/example/conversations/example/messages?limit=50' \
  --header 'Authorization: Bearer <token>'

Newest first. Deleted messages are tombstones (status DELETED, empty body).

Messages in the guides

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
conversation_id
required
string

A Chat conversation id (uuid).

tenant_id
required
string

The Identity Server tenant id.

application_id
required
string

The Identity Server id of a chat-enabled tenant application.

Query Parameters

Section titled “Query Parameters”
before
string

The next_cursor of the previous page.

limit
integer
default: 50 >= 1 <= 100

Responses

Section titled “Responses”

200

Section titled “200”

Success.

Media typeapplication/json
object
items
required
Array<object>
object
message_id
required
string
conversation_id
required
string
tenant_id
required
string
application_id
required
string
sender_user_id
required
string
nullable
sender_client_id
required

Set when a machine client sent it (on behalf of sender_user_id, or as SYSTEM).

string
nullable
sender
required
object
user_id
required
string
display_name
required

Falls back to the user id when Chat has no profile.

string
avatar_url
required
string
nullable
body
required

Empty for a deleted message (tombstone).

string
message_type
required
string
Allowed values: TEXT SYSTEM FILE
reply_to_message_id
required
string
nullable
attachments
required
Array<object>
object
file_id
required

A file id owned by a File/Media platform — Chat never stores bytes.

string
name
required
string
mime_type
required
string
size
required
number
url
required
string
nullable
status
required
string
Allowed values: ACTIVE EDITED DELETED
edited_at
required
string format: date-time
nullable
deleted_at
required
string format: date-time
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
reactions
required
Array<object>
object
emoji
required
string
count
required
number
reacted_by_me
required
boolean
mentioned_user_ids
required
Array<string>
next_cursor
required

Pass as before for the next (older) page; null on the last page.

string
nullable

Example 

{
  "items": [
    {
      "message_id": "0d9e6a52-8b0c-4c47-b1f2-5c9a2c1d7e33",
      "conversation_id": "6b1f4c7e-3c52-4a0a-9a39-7d2e2f1f8a10",
      "tenant_id": "fitness",
      "application_id": "fitness-app",
      "sender_user_id": "coach-ana",
      "sender_client_id": null,
      "sender": {
        "user_id": "coach-ana",
        "display_name": "Ana Coach",
        "avatar_url": null
      },
      "body": "See you at 9!",
      "message_type": "TEXT",
      "reply_to_message_id": null,
      "attachments": [],
      "status": "ACTIVE",
      "edited_at": null,
      "deleted_at": null,
      "created_at": "2026-10-14T09:30:00.000Z",
      "updated_at": "2026-10-14T09:30:00.000Z",
      "reactions": [
        {
          "emoji": "👍",
          "count": 1,
          "reacted_by_me": false
        }
      ],
      "mentioned_user_ids": []
    }
  ],
  "next_cursor": "0d9e6a52-8b0c-4c47-b1f2-5c9a2c1d7e32"
}

400

Section titled “400”

Error. error is one of: invalid_cursor, invalid_limit.

Media typeapplication/json
object
status_code
required
number
error
required

Stable snake_case error code.

string
Allowed values: invalid_request invalid_cursor invalid_limit body_too_long query_too_short query_too_long user_required invalid_json invalid_id_token invalid_redirect_uri too_many_attachments role_locked invalid_grant invalid_token token_revoked missing_capability insufficient_scope not_tenant_member no_application_access tenant_not_available not_conversation_member client_context_mismatch principal_not_allowed system_message_not_allowed chat_access_not_granted not_found application_not_found role_not_found payload_too_large target_user_not_eligible actor_not_member conversation_archived direct_conversation_immutable invalid_reply rate_limited server_error identity_unavailable
message
required
One of:
string
path
required
string
timestamp
required
string format: date-time

Example 

{
  "status_code": 400,
  "error": "invalid_cursor",
  "message": "The `before` cursor is not one this list issued.",
  "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations",
  "timestamp": "2026-10-14T09:30:00.000Z"
}

401

Section titled “401”

Error. error is one of: invalid_token, token_revoked.

Media typeapplication/json
object
status_code
required
number
error
required

Stable snake_case error code.

string
Allowed values: invalid_request invalid_cursor invalid_limit body_too_long query_too_short query_too_long user_required invalid_json invalid_id_token invalid_redirect_uri too_many_attachments role_locked invalid_grant invalid_token token_revoked missing_capability insufficient_scope not_tenant_member no_application_access tenant_not_available not_conversation_member client_context_mismatch principal_not_allowed system_message_not_allowed chat_access_not_granted not_found application_not_found role_not_found payload_too_large target_user_not_eligible actor_not_member conversation_archived direct_conversation_immutable invalid_reply rate_limited server_error identity_unavailable
message
required
One of:
string
path
required
string
timestamp
required
string format: date-time

Example 

{
  "status_code": 401,
  "error": "invalid_token",
  "message": "The bearer token is missing, malformed, expired, signed by an unknown key, has the wrong audience (`aud` must be `chat-api`), or lacks the required scope.",
  "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations",
  "timestamp": "2026-10-14T09:30:00.000Z"
}

403

Section titled “403”

Error. error is one of: not_tenant_member, no_application_access, tenant_not_available, insufficient_scope, client_context_mismatch, missing_capability, not_conversation_member.

Media typeapplication/json
object
status_code
required
number
error
required

Stable snake_case error code.

string
Allowed values: invalid_request invalid_cursor invalid_limit body_too_long query_too_short query_too_long user_required invalid_json invalid_id_token invalid_redirect_uri too_many_attachments role_locked invalid_grant invalid_token token_revoked missing_capability insufficient_scope not_tenant_member no_application_access tenant_not_available not_conversation_member client_context_mismatch principal_not_allowed system_message_not_allowed chat_access_not_granted not_found application_not_found role_not_found payload_too_large target_user_not_eligible actor_not_member conversation_archived direct_conversation_immutable invalid_reply rate_limited server_error identity_unavailable
message
required
One of:
string
path
required
string
timestamp
required
string format: date-time

Example 

{
  "status_code": 403,
  "error": "not_tenant_member",
  "message": "The user is not an active member of the tenant in the URL.",
  "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations",
  "timestamp": "2026-10-14T09:30:00.000Z"
}

404

Section titled “404”

Error. error is one of: application_not_found, not_found.

Media typeapplication/json
object
status_code
required
number
error
required

Stable snake_case error code.

string
Allowed values: invalid_request invalid_cursor invalid_limit body_too_long query_too_short query_too_long user_required invalid_json invalid_id_token invalid_redirect_uri too_many_attachments role_locked invalid_grant invalid_token token_revoked missing_capability insufficient_scope not_tenant_member no_application_access tenant_not_available not_conversation_member client_context_mismatch principal_not_allowed system_message_not_allowed chat_access_not_granted not_found application_not_found role_not_found payload_too_large target_user_not_eligible actor_not_member conversation_archived direct_conversation_immutable invalid_reply rate_limited server_error identity_unavailable
message
required
One of:
string
path
required
string
timestamp
required
string format: date-time

Example 

{
  "status_code": 404,
  "error": "application_not_found",
  "message": "The application does not exist in the tenant, or Chat is not enabled for it.",
  "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations",
  "timestamp": "2026-10-14T09:30:00.000Z"
}

429

Section titled “429”

Error. error is one of: rate_limited.

Media typeapplication/json
object
status_code
required
number
error
required

Stable snake_case error code.

string
Allowed values: invalid_request invalid_cursor invalid_limit body_too_long query_too_short query_too_long user_required invalid_json invalid_id_token invalid_redirect_uri too_many_attachments role_locked invalid_grant invalid_token token_revoked missing_capability insufficient_scope not_tenant_member no_application_access tenant_not_available not_conversation_member client_context_mismatch principal_not_allowed system_message_not_allowed chat_access_not_granted not_found application_not_found role_not_found payload_too_large target_user_not_eligible actor_not_member conversation_archived direct_conversation_immutable invalid_reply rate_limited server_error identity_unavailable
message
required
One of:
string
path
required
string
timestamp
required
string format: date-time

Example 

{
  "status_code": 429,
  "error": "rate_limited",
  "message": "The caller exceeded a rate limit",
  "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations",
  "timestamp": "2026-10-14T09:30:00.000Z"
}

503

Section titled “503”

Error. error is one of: identity_unavailable.

Media typeapplication/json
object
status_code
required
number
error
required

Stable snake_case error code.

string
Allowed values: invalid_request invalid_cursor invalid_limit body_too_long query_too_short query_too_long user_required invalid_json invalid_id_token invalid_redirect_uri too_many_attachments role_locked invalid_grant invalid_token token_revoked missing_capability insufficient_scope not_tenant_member no_application_access tenant_not_available not_conversation_member client_context_mismatch principal_not_allowed system_message_not_allowed chat_access_not_granted not_found application_not_found role_not_found payload_too_large target_user_not_eligible actor_not_member conversation_archived direct_conversation_immutable invalid_reply rate_limited server_error identity_unavailable
message
required
One of:
string
path
required
string
timestamp
required
string format: date-time

Example 

{
  "status_code": 503,
  "error": "identity_unavailable",
  "message": "Chat could not reach the Identity Server and has no fresh cached answer.",
  "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations",
  "timestamp": "2026-10-14T09:30:00.000Z"
}

default

Section titled “default”

Error — see error for the code.

Media typeapplication/json
object
status_code
required
number
error
required

Stable snake_case error code.

string
Allowed values: invalid_request invalid_cursor invalid_limit body_too_long query_too_short query_too_long user_required invalid_json invalid_id_token invalid_redirect_uri too_many_attachments role_locked invalid_grant invalid_token token_revoked missing_capability insufficient_scope not_tenant_member no_application_access tenant_not_available not_conversation_member client_context_mismatch principal_not_allowed system_message_not_allowed chat_access_not_granted not_found application_not_found role_not_found payload_too_large target_user_not_eligible actor_not_member conversation_archived direct_conversation_immutable invalid_reply rate_limited server_error identity_unavailable
message
required
One of:
string
path
required
string
timestamp
required
string format: date-time

Example 

{
  "status_code": 403,
  "error": "invalid_request",
  "message": "Missing Chat capability messages.send",
  "path": "/api/v1/tenants/t1/applications/a1/conversations"
}