Skip to content
Median
Esc
↑↓navigate↵open⌘Jpreview

Get a conversation

The whole thread, up to the most recent 200 messages, team-only notes and system narration included.

GET/conversations/{id}
Authorization
AuthorizationBearer token · headerrequired
`MEDIAN_KEY` from Settings under API, or an MCP OAuth access token. A key acts as the organization; a token acts as the person who approved it.
Path parameters
idstringrequired
A conversation id.
Responses
200The conversation and its messages, oldest first.
conversationConversationSummary
Show properties
idstring
threadIdstring | null
W-12: the workspace's initial and the thread's number, which is how the team refers to it. Null for a thread from before numbers existed.
subjectstring
previewstring
statusstring
Allowed:openresolvedclosed
aiStatusstring
Allowed:handlingdraftingneeds a personpaused
channelstring
Allowed:widgetemaildiscordsite
assigneestring | null
The teammate holding it, by name, or null while the AI has it.
isUnreadboolean
isArchivedboolean
snoozedUntilinteger | null
lastMessageAtinteger
createdAtinteger
customerobject
Show properties
idstring | null
namestring | null
customerNumberinteger | null
emailstring | null
pageobject | any
Where the visitor was when they started it, or null.
Show properties
One of:
object
urlstring
titlestring
referrerstring
any
any
messagesMessage[]
Show properties
Array of Message
idstring
createdAtinteger
authorstring
`visitor` is the customer, `ai` the agent, `human` a teammate, `system` the thread narrating itself, `note` team-only.
Allowed:visitoraihumansystemnote
authorNamestring | null
bodystring
pendingboolean
attachmentsobject[]
Show properties
Array of object
idstring
namestring
sizeinteger
typestring
urlstring | null
toolCallsobject[]
Show properties
Array of object
namestring
inputstring
outputstring | null
aiErrorstring | null
401The bearer token is missing, revoked, or expired.
errorobject
Show properties
codestring
messagestring
404Not one of yours, or not there at all.
errorobject
Show properties
codestring
messagestring
429Too many requests. Wait the seconds in `Retry-After`. Limits depend on the plan. See [rate limits](/api/errors-and-limits#rate-limits).
errorobject
Show properties
codestring
messagestring
Request
curl -X GET "https://api.median.sh/v1/conversations/string" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "conversation": {
    "id": "string",
    "threadId": "string",
    "subject": "string",
    "preview": "string",
    "status": "open",
    "aiStatus": "handling",
    "channel": "widget",
    "assignee": "string",
    "isUnread": true,
    "isArchived": true,
    "snoozedUntil": 0,
    "lastMessageAt": 0,
    "createdAt": 0,
    "customer": {
      "id": "string",
      "name": "string",
      "customerNumber": 0,
      "email": "string"
    }
  },
  "page": {
    "url": "string",
    "title": "string",
    "referrer": "string"
  },
  "messages": [
    {
      "id": "string",
      "createdAt": 0,
      "author": "visitor",
      "authorName": "string",
      "body": "string",
      "pending": true,
      "attachments": [
        {
          "id": "string",
          "name": "string",
          "size": 0,
          "type": "string",
          "url": "string"
        }
      ],
      "toolCalls": [
        {
          "name": "string",
          "input": "string",
          "output": "string"
        }
      ],
      "aiError": "string"
    }
  ]
}