conversations

Direct conversations with other participants. (Currently, just threads containing a post with "direct" visibility.)

Show conversation

GET https://mastodon.example/api/v1/conversations

Returns: Array of Conversation OAuth: User token + read:statuses Version history: 2.6.0 - added

Query Parameters

Name	Type	Description
limit	string	Maximum number of results. Defaults to 20. Max 40.
max_id	string	Return results older than this ID. Use HTTP Link header to paginate.
since_id	string	Return results newer than this ID. Use HTTP Link header to paginate.
min_id	string	Return results immediately newer than this ID. Use HTTP Link header to paginate.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Truncated sample results of an API call with limit=2

[
  {
    "id": "418450",
    "unread": true,
    "accounts": [
      {
        "id": "482403",
        "username": "amic",
        "acct": "[e-mail]",
        ...
      }
    ],
    "last_status": {
      "id": "103196583826321184",
      "created_at": "2019-11-25T04:08:24.000Z",
      "in_reply_to_id": "103196540587943467",
      "in_reply_to_account_id": "14715",
      ...
    }
  },
  {
    "id": "418374",
    "unread": false,
    "accounts": [
      {
        "id": "464472",
        "username": "freon",
        "acct": "[e-mail]",
        ...
      }
    ],
    "last_status": {
      "id": "103195253010396431",
      "created_at": "2019-11-24T22:29:56.331Z",
      "in_reply_to_id": "103195239650546339",
      "in_reply_to_account_id": "14715",
      ...
    }
  }
]

401 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

Remove conversation

DELETE https://mastodon.example/api/v1/conversations/:id

Returns: empty object OAuth: User token + write:conversations Version history: 2.6.0 - added

Path Parameters

Name	Type	Description
:id	string	ID of the conversation in the database

Headers

Name	Type	Description
Authorization	string

200 An empty object will be returned.

{}

401 Invalid or missing Authentication header

{
  "error": "The access token is invalid"
}

404 The conversation does not exist, or is not owned by you.

{
  "error": "Record not found"
}

Mark as read

POST https://mastodon.example/api/v1/conversations/:id/read

Returns: Conversation OAuth: User token + write:conversations Version history: 2.6.0 - added

Path Parameters

Name	Type	Description
:id	string	ID of the conversation in the database

Headers

Name	Type	Description
Authorization	string

200 The value of unread has been changed to false.

{
  "id": "418450",
  "unread": false,
  "accounts": [
    {
      "id": "482403",
      ...
    }
  ],
  "last_status": {
    "id": "103196583826321184",
    ...
  }
}

401 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

404 The conversation does not exist, or is not owned by you.

{
  "error": "Record not found"
}