conversations

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

get
Show conversation

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

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

Request

Headers
Authorization
required
string
Bearer <user token>
Query Parameters
limit
optional
string
Maximum number of results. Defaults to 20. Max 40.
max_id
optional
string
Return results older than this ID. Use HTTP Link header to paginate.
since_id
optional
string
Return results newer than this ID. Use HTTP Link header to paginate.
min_id
optional
string
Return results immediately newer than this ID. Use HTTP Link header to paginate.

Response

200: Success

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",
      ...
    }
  }
]

401: Unauthorized

Invalid or missing Authorization header 

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

delete
Remove conversation

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

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

Request

Path Parameters
:id
required
string
ID of the conversation in the database
Headers
Authorization
required
string

Response

200: Success

An empty object will be returned. 

{}

401: Unauthorized

Invalid or missing Authentication 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"
}

post
Mark as read

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

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

Request

Path Parameters
:id
optional
string
ID of the conversation in the database
Headers
Authorization
required
string

Response

200: Success

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

Last updated December 27, 2020 · Improve this page