Skip to content
CCS Chat Docs

List conversations

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

Users: conversations they are a member of, plus PUBLIC channels. Machines: every conversation of the context. Most recently active first.

Conversations in the guides

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
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”
type
string
Allowed values: DIRECT GROUP CHANNEL
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
conversation_id
required
string
tenant_id
required

The Identity Server tenant id.

string
application_id
required

The Identity Server application id (the context).

string
type
required
string
Allowed values: DIRECT GROUP CHANNEL
visibility
required

CHANNEL only.

string
nullable
Allowed values: PUBLIC PRIVATE
name
required
string
nullable
description
required
string
nullable
status
required

ARCHIVED is read-only.

string
Allowed values: ACTIVE ARCHIVED DELETED
created_by_user_id
required
string
nullable
created_by_client_id
required

Set when a machine client created it.

string
nullable
last_activity_at
required
string format: date-time
created_at
required
string format: date-time
updated_at
required
string format: date-time
members

On list/get: ACTIVE members for DIRECT/GROUP (bounded), omitted for CHANNEL.

Array<object>
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
member_count
number
my_role

The caller’s membership role (users only).

string
nullable
Allowed values: OWNER ADMIN MEMBER
has_unread

Users only.

boolean
next_cursor
required

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

string
nullable

Example 

{
  "items": [
    {
      "conversation_id": "6b1f4c7e-3c52-4a0a-9a39-7d2e2f1f8a10",
      "tenant_id": "fitness",
      "application_id": "fitness-app",
      "type": "DIRECT",
      "visibility": null,
      "name": null,
      "description": null,
      "status": "ACTIVE",
      "created_by_user_id": null,
      "created_by_client_id": "2f1c9e5a-7f4d-4f0e-8c35-9b1a3d6e4c21",
      "last_activity_at": "2026-10-14T09:30:00.000Z",
      "created_at": "2026-10-14T09:00:00.000Z",
      "updated_at": "2026-10-14T09:30:00.000Z",
      "members": [
        {
          "user_id": "coach-ana",
          "display_name": "Ana Coach",
          "avatar_url": null
        },
        {
          "user_id": "client-john",
          "display_name": "John Client",
          "avatar_url": null
        }
      ],
      "member_count": 2,
      "my_role": "MEMBER",
      "has_unread": true
    }
  ],
  "next_cursor": null
}

400

Section titled “400”

Error. error is one of: invalid_request, 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_request",
  "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent",
  "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.

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.

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"
}