> ## Documentation Index > Fetch the complete documentation index at: https://help.ciarem.ai/llms.txt > Use this file to discover all available pages before exploring further. # List a conversation's messages ## OpenAPI ````yaml /api-reference/openapi.json get /v1/conversations/{conversation_id}/messages openapi: 3.1.0 info: title: Ciarem API version: v1 description: > The Ciarem public API. Authenticate every request with an org-bound API key (created in Settings → API keys; Scale plan or free trial) sent as a bearer token: `Authorization: Bearer oak_…`. Compatibility: this is an early, fast-moving API. Most changes are additive (new endpoints, new optional params, new response fields, new enum/string values) — clients must tolerate unknown fields and unknown string values. Every contract change is listed in the changelog at help.ciarem.ai. servers: - url: https://api.ciarem.ai security: - apiKey: [] tags: - name: Account description: The organization behind the API key. - name: Contacts description: People in the CRM — create, read, update, delete. - name: CRM description: 'The shape of the CRM: custom properties and funnel stages.' - name: Conversations description: Read the message history of a conversation. - name: WhatsApp numbers description: The connected numbers a send can go out from. - name: WhatsApp templates description: Message templates, and what each one needs filled before it can be sent. - name: Broadcasts description: Send a template, and follow what happened to every recipient. paths: /v1/conversations/{conversation_id}/messages: get: tags: - Conversations summary: List a conversation's messages operationId: messages_endpoint_v1_conversations__conversation_id__messages_get parameters: - name: conversation_id in: path required: true schema: type: string title: Conversation Id - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 30 title: Limit - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PublicMessageListResponse' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '401': description: >- No usable credential: `missing_bearer_token` (no `Authorization: Bearer`) or `invalid_api_key` (unknown or revoked key). content: application/json: schema: $ref: '#/components/schemas/PublicError' '403': description: >- The credential is real but not allowed here: `api_key_required` (a session token rather than an `oak_` key), `scale_plan_required` (a live plan below Scale — upgrade to Scale), `trial_expired` (the free trial ended without a card — subscribe to keep the key working), or `subscription_required` (the subscription is canceled or suspended). content: application/json: schema: $ref: '#/components/schemas/PublicError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: >- Over the organization's request budget (`rate_limited`). `Retry-After` says how many seconds to wait. content: application/json: schema: $ref: '#/components/schemas/PublicError' headers: Retry-After: description: Seconds until the window resets. schema: type: integer X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' components: schemas: PublicMessageListResponse: properties: items: items: $ref: '#/components/schemas/PublicMessage' type: array title: Items next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor type: object required: - items - next_cursor title: PublicMessageListResponse PublicError: description: An error whose `detail` is a stable, machine-readable code. properties: detail: title: Detail type: string required: - detail title: PublicError type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PublicMessage: properties: id: type: string title: Id conversation_id: type: string title: Conversation Id direction: $ref: '#/components/schemas/MessageDirection' type: type: string title: Type status: $ref: '#/components/schemas/MessageStatus' text_body: anyOf: - type: string - type: 'null' title: Text Body media: anyOf: - $ref: '#/components/schemas/PublicMessageMedia' - type: 'null' link_url: anyOf: - type: string - type: 'null' title: Link Url reply_to_id: anyOf: - type: string - type: 'null' title: Reply To Id external_message_id: anyOf: - type: string - type: 'null' title: External Message Id sender: type: string enum: - contact - agent - ai - system title: Sender sender_display_name: anyOf: - type: string - type: 'null' title: Sender Display Name received_at: anyOf: - type: string format: date-time - type: 'null' title: Received At delivered_at: anyOf: - type: string format: date-time - type: 'null' title: Delivered At read_at: anyOf: - type: string format: date-time - type: 'null' title: Read At created_at: type: string format: date-time title: Created At error_code: anyOf: - type: integer - type: 'null' title: Error Code revoked_at: anyOf: - type: string format: date-time - type: 'null' title: Revoked At type: object required: - id - conversation_id - direction - type - status - text_body - media - link_url - reply_to_id - external_message_id - sender - sender_display_name - received_at - delivered_at - read_at - created_at - error_code - revoked_at title: PublicMessage ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError MessageDirection: type: string enum: - inbound - outbound - internal - system title: MessageDirection description: Direction of a stored message relative to the business. MessageStatus: type: string enum: - received - sending - sent - delivered - read - failed title: MessageStatus description: |- Delivery status. Inbound lands `received`; outbound walks sending → sent → delivered → read (or → failed). PublicMessageMedia: properties: media_id: anyOf: - type: string - type: 'null' title: Media Id mime_type: anyOf: - type: string - type: 'null' title: Mime Type caption: anyOf: - type: string - type: 'null' title: Caption filename: anyOf: - type: string - type: 'null' title: Filename type: object required: - media_id - mime_type - caption - filename title: PublicMessageMedia headers: X-RateLimit-Limit: description: Requests allowed per window, shared across the org's keys. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: When the window resets, as a Unix timestamp in seconds. schema: type: integer securitySchemes: apiKey: type: http scheme: bearer description: 'An org API key: `Authorization: Bearer oak_…`.' ````