List conversations

The newest 200 conversations on one side of the archive, filters applied within that page. The same page the inbox reads.

GET/conversations

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.

Query parameters

archivedboolean

`true` for the archive instead of the inbox.

statusstring

Allowed:openresolvedclosed

channelstring

Allowed:widgetemaildiscordsite

needsHumanboolean

`true` for only conversations waiting on a person.

limitinteger

Up to 200. Default 50.

Responses

200The matching conversations, newest first.

conversationsConversationSummary[]

Show properties

Array of ConversationSummary

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

401The bearer token is missing, revoked, or expired.

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" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.median.sh/v1/conversations", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

Response

{
  "conversations": [
    {
      "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"
      }
    }
  ]
}