List Conversations & Read Messages

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

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

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

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

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

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

GET

api

public

messages

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

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

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

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

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

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

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

conversationId

string

Conversation to read. Omit to list conversation summaries instead.

limit

number

default:"20"

Page size, 1–100.

cursor

string

Pagination cursor from a previous response’s nextCursor.

direction

string

default:"older"

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

filter

string

default:"all"

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

unreadOnly

boolean

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`)

conversations

object[]

Show conversation entry

string

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

type

string | null

DIRECT_MESSAGE or CHANNEL.

bucket

string

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

jobId

string | null

Linked job for job-bucket conversations.

proposalId

string | null

Linked proposal for proposal-bucket conversations.

channelName

string | null

Channel name (channels only).

updatedAt

string

ISO timestamp of latest activity.

lastMessage

object | null

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

unreadCount

number

Number of messages in the conversation you have not read.

needsReplyCount

number

Messages awaiting your reply.

nextCursor

string | null

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

Response — messages (`conversationId` set)

messages

object[]

Show message entry

string

Message ID.

createdAt

string

ISO sent timestamp.

updatedAt

string

ISO last-change timestamp.

conversationId

string

The conversation.

jobId

string | null

Linked job, when the conversation is job-linked.

senderUserId

string | null

Sender’s user ID.

isFromViewer

boolean

true when the token owner sent it.

content

string | null

Message text.

messageType

string | null

Message type for system/automated messages.

system

boolean

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

hasUnreadFlag

boolean

true when unread by you.

attachmentCount

number

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

hasAudio

boolean

true when the message has an audio recording.

editedAt

string | null

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

reactionCount

number

Number of emoji reactions.

nextCursor

string | 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

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

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

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

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

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

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

Get Freelancer Profile

Send Message

⌘I

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

List Conversations & Read Messages

Request

Response — conversation list (no `conversationId`)

Response — messages (`conversationId` set)

Errors

​Request

​Response — conversation list (no conversationId)

​Response — messages (conversationId set)

​Errors

Request

Response — conversation list (no `conversationId`)

Response — messages (`conversationId` set)

Errors