List Conversations & Read Messages

Reads your messaging surface in two modes:

• Without conversationId — lists your conversation summaries (proposal threads, job threads, and channels), newest activity first.
• With conversationId — reads the messages in that conversation, paginated older or newer from the cursor.

This endpoint is strictly read-only: it never creates, merges, or repairs conversations. Conversations come from starting a proposal thread, invites, and hires. Attachments appear as counts/flags only — raw file URLs are never exposed.

Requirements: messages:read scope. You only see conversations you participate in. Works pre-claim.

Request

conversationIdstringquery

Conversation to read. Omit to list conversation summaries instead.

limitnumberquery

Default: 20

Page size, 1–100.

cursorstringquery

Pagination cursor from a previous response’s nextCursor.

directionstringquery

Default: older

Message mode only: older pages back in time, newer pages forward (e.g. tailing a thread).

filterstringquery

Default: all

List mode only: all, job (post-hire threads and channels), or proposal (pre-hire threads).

unreadOnlybooleanquery

Default: false

List mode only: pass true or 1 to return only conversations with unread messages.

Invalid parameters return 400 with zod issue details.

Response — conversation list (no conversationId)

conversationsobject[]

conversation entry

idstring

Conversation ID — pass back as conversationId to read it, or to POST /messages to reply.

typestring | null

DIRECT_MESSAGE or CHANNEL.

bucketstring

proposal (pre-hire thread) or job (post-hire thread or channel).

jobIdstring | null

Linked job for job-bucket conversations.

proposalIdstring | null

Linked proposal for proposal-bucket conversations.

channelNamestring | null

Channel name (channels only).

updatedAtstring

ISO timestamp of latest activity.

lastMessageobject | null

{id, content, senderUserId, isFromViewer, createdAt} — a preview of the most recent message.

unreadCountnumber

Number of messages in the conversation you have not read.

needsReplyCountnumber

Messages awaiting your reply.

nextCursorstring | null

Pass back as cursor for the next page; null at the end.

Response — messages (conversationId set)

messagesobject[]

message entry

idstring

Message ID.

createdAtstring

ISO sent timestamp.

updatedAtstring

ISO last-change timestamp.

conversationIdstring

The conversation.

jobIdstring | null

Linked job, when the conversation is job-linked.

senderUserIdstring | null

Sender’s user ID.

isFromViewerboolean

true when the token owner sent it.

contentstring | null

Message text.

messageTypestring | null

Message type for system/automated messages.

systemboolean

true for system messages (hire notices, milestone events, etc.).

hasUnreadFlagboolean

true when unread by you.

attachmentCountnumber

Number of attached files (counts only — no file URLs).

hasAudioboolean

true when the message has an audio recording.

editedAtstring | null

ISO timestamp of the last edit, null if never edited.

reactionCountnumber

Number of emoji reactions.

nextCursorstring | null

Pass back as cursor (with the same direction) for the next page; null at the end.

Errors

Status	code	Meaning
400	BAD_REQUEST	Invalid query parameters (zod details)
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Missing messages:read scope, or you are not a participant in conversationId
404	NOT_FOUND	No such conversation

Request examples

curl (list conversations)curl (read one conversation)CLIMCP: opentrain_read_messages

curl (list conversations)

curl -sS "https://app.opentrain.ai/api/public/v1/messages?filter=all&unreadOnly=true&limit=20" \
  -H "Authorization: Bearer $OT_API_TOKEN"

curl (read one conversation)

curl -sS "https://app.opentrain.ai/api/public/v1/messages?conversationId=<CONVERSATION_ID>&limit=20&direction=older" \
  -H "Authorization: Bearer $OT_API_TOKEN"

CLI

opentrain messages list --unread-only --json
opentrain messages read --conversation-id <CONVERSATION_ID> --json

MCP: opentrain_read_messages

{
  "conversationId": "<CONVERSATION_ID>",
  "limit": 20,
  "direction": "older"
}

Response examples

200 (conversation list)200 (messages)

200 (conversation list)

{
  "conversations": [
    {
      "id": "<CONVERSATION_ID>",
      "type": "DIRECT_MESSAGE",
      "bucket": "proposal",
      "jobId": null,
      "proposalId": "<PROPOSAL_ID>",
      "channelName": null,
      "updatedAt": "2026-06-12T08:30:00.000Z",
      "lastMessage": {
        "id": "<MESSAGE_ID>",
        "content": "Thanks — I can start Monday.",
        "senderUserId": "<FREELANCER_ID>",
        "isFromViewer": false,
        "createdAt": "2026-06-12T08:30:00.000Z"
      },
      "unreadCount": 1,
      "needsReplyCount": 1
    }
  ],
  "nextCursor": null
}

200 (messages)

{
  "messages": [
    {
      "id": "<MESSAGE_ID>",
      "createdAt": "2026-06-12T08:30:00.000Z",
      "updatedAt": "2026-06-12T08:30:00.000Z",
      "conversationId": "<CONVERSATION_ID>",
      "jobId": null,
      "senderUserId": "<FREELANCER_ID>",
      "isFromViewer": false,
      "content": "Thanks — I can start Monday.",
      "messageType": null,
      "system": false,
      "hasUnreadFlag": true,
      "attachmentCount": 0,
      "hasAudio": false,
      "editedAt": null,
      "reactionCount": 0
    }
  ],
  "nextCursor": null
}