documentation/content/en/methods/conversations.md

title	description	menu	aliases
conversations API methods	Direct conversations with other participants. (Currently, just threads containing a post with "direct" visibility.)	docs weight name parent identifier 10 conversations methods-timelines methods-conversations	/methods/conversations /api/methods/conversations /methods/timelines/conversations

View all conversations

GET /api/v1/conversations HTTP/1.1

Returns: Array of [Conversation]({{< relref "entities/conversation" >}})
OAuth: User token + read:statuses
Version history:
2.6.0 - added
3.3.0 - both min_id and max_id can be used at the same time now

Request

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Query parameters

max_id

Internal parameter. Use HTTP Link header for pagination.

since_id

Internal parameter. Use HTTP Link header for pagination.

min_id

Internal parameter. Use HTTP Link header for pagination.

limit

Integer. Maximum number of results to return. Defaults to 20 conversations. Max 40 conversations.

Response

200: OK

Truncated sample results of an API call with limit=2

[
  {
    "id": "418450",
    "unread": true,
    "accounts": [
      {
        "id": "482403",
        "username": "amic",
        "acct": "amic@nulled.red",
        // ...
      }
    ],
    "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": "freon@letsalllovela.in",
        // ...
      }
    ],
    "last_status": {
      "id": "103195253010396431",
      "created_at": "2019-11-24T22:29:56.331Z",
      "in_reply_to_id": "103195239650546339",
      "in_reply_to_account_id": "14715",
      // ...
    }
  }
]

Because AccountConversation IDs are generally not exposed via any API responses, you will have to parse the HTTP Link header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.

Link: <https://mastodon.example/api/v1/conversations?limit=2&max_id=108835003356700379>; rel="next", <https://mastodon.example/api/v1/conversations?limit=2&min_id=108888782724768580>; rel="prev"

401: Unauthorized

Invalid or missing Authorization header.

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

---

Remove a conversation

DELETE /api/v1/conversations/:id HTTP/1.1

Removes a conversation from your list of conversations.

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

Request

Path parameters

:id

{{}} String. The ID of the Conversation in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

{}

401: Unauthorized

Invalid or missing Authorization header.

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

404: Not found

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

{
  "error": "Record not found"
}

---

Mark a conversation as read

POST /api/v1/conversations/:id/read HTTP/1.1

Returns: [Conversation]({{< relref "entities/conversation" >}})
OAuth: User token + write:conversations
Version history:
2.6.0 - added

Request

Path parameters

:id

{{}} String. The ID of the Conversation in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

The value of unread has been changed to false.

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

401: Unauthorized

Invalid or missing Authorization header.

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

404: Not found

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

{
  "error": "Record not found"
}

---

See also

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/conversations_controller.rb" caption="app/controllers/api/v1/conversations_controller.rb" >}}