Direct messages

GET/api/v1.1/direct/unread_count

Get unread counts

Pixelfed only User token Scope read

Returns

curl "https://pixelfed.social/api/v1.1/direct/unread_count" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/unread_count", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const counts = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1.1/direct/unread_count",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

counts = res.json()

use Illuminate\Support\Facades\Http;

$counts = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.1/direct/unread_count')
    ->json();

Response

{
  "primary": 2,
  "requests": 1
}

{
  "error": "Missing required scope: read"
}

GET/api/v1.1/direct/conversations

List conversations

Pixelfed only User token Scope read

Query parameters

filterstring

limitinteger

cursorstring

Returns

curl "https://pixelfed.social/api/v1.1/direct/conversations?filter=primary&limit=20" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations?filter=primary&limit=20", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const conversations = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1.1/direct/conversations",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    params={
        "filter": "primary",
        "limit": 20,
    },
)

conversations = res.json()

use Illuminate\Support\Facades\Http;

$conversations = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.1/direct/conversations', [
        'filter' => 'primary',
        'limit' => 20,
    ])
    ->json();

Response

{
  "data": [{
    "id": "731902455120183296",
    "type": "dm",
    "name": null,
    "participants": [{
      "id": "412760184563377",
      "username": "jonas",
      "acct": "jonas",
      "display_name": "Jonas Berg",
      "locked": false,
      "url": "https://pixelfed.social/jonas",
      "avatar": "https://pixelfed.social/storage/avatars/412/760/jonas.jpg",
      "local": true
    }],
    "participant_count": 2,
    "state": "active",
    "unread_count": 1,
    "muted": false,
    "hidden": false,
    "last_read_message_id": "731902611844546560",
    "last_message": {
      "id": "731907388210487296",
      "conversation_id": "731902455120183296",
      "sender_id": "412760184563377",
      "is_author": false,
      "type": "text",
      "text": "Are you shooting the harbour again on Saturday?",
      "media": [],
      "meta": null,
      "sensitive": false,
      "in_reply_to_id": null,
      "edited_at": null,
      "created_at": "2026-10-16T19:04:22.000Z"
    },
    "created_at": "2026-10-14T08:12:09.000Z",
    "updated_at": "2026-10-16T19:04:22.000Z"
  }],
  "meta": {
    "filter": "primary",
    "next_cursor": "eyJsYXN0X2FjdGl2aXR5X2F0IjoiMjAyNi0xMC0xNCAwODoxMjowOSIsImlkIjo4ODIxLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prev_cursor": null
  }
}

{
  "message": "The selected filter is invalid.",
  "errors": {
    "filter": ["The selected filter is invalid."]
  }
}

POST/api/v1.1/direct/conversations

Start a conversation

Pixelfed only User token Scope write

Body parameters

recipient_idsarray of stringsrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_ids": ["412760184563377", "412760184563412"]
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    recipient_ids: ["412760184563377", "412760184563412"],
  }),
});

const conversation = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "recipient_ids": ["412760184563377", "412760184563412"],
    },
)

conversation = res.json()

use Illuminate\Support\Facades\Http;

$conversation = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations', [
        'recipient_ids' => ['412760184563377', '412760184563412'],
    ])
    ->json();

Response

{
  "id": "731911020536471552",
  "type": "group",
  "name": null,
  "participants": [{
    "id": "412760184563377",
    "username": "jonas",
    "acct": "jonas",
    "display_name": "Jonas Berg",
    "avatar": "https://pixelfed.social/storage/avatars/412/760/jonas.jpg",
    "local": true
  }, {
    "id": "412760184563412",
    "username": "ines",
    "acct": "ines",
    "display_name": "Ines Kask",
    "avatar": "https://pixelfed.social/storage/avatars/412/760/ines.jpg",
    "local": true
  }],
  "participant_count": 3,
  "state": "active",
  "unread_count": 0,
  "muted": false,
  "hidden": false,
  "last_read_message_id": null,
  "last_message": null,
  "created_at": "2026-10-17T09:30:51.000Z",
  "updated_at": "2026-10-17T09:30:51.000Z"
}

{
  "error": "You need to wait a bit before you can DM another account"
}

{
  "error": "Group conversations are not enabled."
}

GET/api/v1.1/direct/conversations/{id}

Get a conversation

Pixelfed only User token Scope read

Path parameters

idstringrequired

Returns

curl "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const conversation = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

conversation = res.json()

use Illuminate\Support\Facades\Http;

$conversation = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296')
    ->json();

Response

{
  "id": "731902455120183296",
  "type": "dm",
  "name": null,
  "participants": [{
    "id": "412760184563377",
    "username": "jonas",
    "acct": "jonas",
    "display_name": "Jonas Berg",
    "avatar": "https://pixelfed.social/storage/avatars/412/760/jonas.jpg",
    "local": true
  }],
  "participant_count": 2,
  "state": "active",
  "unread_count": 1,
  "muted": false,
  "hidden": false,
  "last_read_message_id": "731902611844546560",
  "last_message": {
    "id": "731907388210487296",
    "sender_id": "412760184563377",
    "is_author": false,
    "type": "text",
    "text": "Are you shooting the harbour again on Saturday?",
    "created_at": "2026-10-16T19:04:22.000Z"
  },
  "created_at": "2026-10-14T08:12:09.000Z",
  "updated_at": "2026-10-16T19:04:22.000Z"
}

{
  "error": "Record not found"
}

GET/api/v1.1/direct/conversations/{id}/messages

List messages

Pixelfed only User token Scope read

Path parameters

idstringrequired

Query parameters

limitinteger

max_idstring

min_idstring

Returns

curl "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages?limit=20" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages?limit=20", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const messages = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    params={
        "limit": 20,
    },
)

messages = res.json()

use Illuminate\Support\Facades\Http;

$messages = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages', [
        'limit' => 20,
    ])
    ->json();

Response

{
  "data": [{
    "id": "731907388210487296",
    "conversation_id": "731902455120183296",
    "sender_id": "412760184563377",
    "is_author": false,
    "type": "text",
    "text": "Are you shooting the harbour again on Saturday?",
    "media": [],
    "meta": null,
    "sensitive": false,
    "in_reply_to_id": null,
    "edited_at": null,
    "created_at": "2026-10-16T19:04:22.000Z"
  }, {
    "id": "731902611844546560",
    "conversation_id": "731902455120183296",
    "sender_id": "2",
    "is_author": true,
    "type": "photo",
    "text": "Fog came in right after this one",
    "media": [{
      "id": "731902598120783872",
      "type": "image",
      "url": "https://pixelfed.social/storage/m/_v2/2/fog.jpg",
      "preview_url": "https://pixelfed.social/storage/m/_v2/2/fog_thumb.jpg",
      "description": null,
      "mime": "image/jpeg",
      "blurhash": "U9C%8]of00WB~qj[M{ay4nof%Mj["
    }],
    "meta": null,
    "sensitive": false,
    "in_reply_to_id": null,
    "edited_at": null,
    "created_at": "2026-10-14T08:12:09.000Z"
  }],
  "meta": {
    "has_more": false,
    "newest_id": "731907388210487296",
    "oldest_id": "731902611844546560"
  }
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/conversations/{id}/messages

Send a message

Pixelfed only User token Scope write

Path parameters

idstringrequired

Body parameters

messagestring

media_idsarray of strings

in_reply_to_idstring

sensitiveboolean

typestring

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Yes, meet at the pier at 7?"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Yes, meet at the pier at 7?",
  }),
});

const message = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "message": "Yes, meet at the pier at 7?",
    },
)

message = res.json()

use Illuminate\Support\Facades\Http;

$message = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages', [
        'message' => 'Yes, meet at the pier at 7?',
    ])
    ->json();

Response

{
  "id": "731911388741324800",
  "conversation_id": "731902455120183296",
  "sender_id": "2",
  "is_author": true,
  "type": "text",
  "text": "Yes, meet at the pier at 7?",
  "media": [],
  "meta": null,
  "sensitive": false,
  "in_reply_to_id": null,
  "edited_at": null,
  "created_at": "2026-10-17T09:32:18.000Z"
}

{
  "error": "You can send more messages once your request is accepted."
}

{
  "error": "Invalid media_ids."
}

DELETE/api/v1.1/direct/conversations/{id}/messages/{messageId}

Delete a message

Pixelfed only User token Scope write

Path parameters

idstringrequired

messageIdstringrequired

Returns

curl -X DELETE "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages/731911388741324800" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages/731911388741324800", {
  method: "DELETE",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const result = await res.json();

import requests

res = requests.delete(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages/731911388741324800",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

result = res.json()

use Illuminate\Support\Facades\Http;

$result = Http::acceptJson()
    ->withToken($token)
    ->delete('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/messages/731911388741324800')
    ->json();

Response

{
  "deleted": true
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/conversations/{id}/read

Mark a conversation read

Pixelfed only User token Scope write

Path parameters

idstringrequired

Body parameters

message_idstring

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/read" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "731907388210487296"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/read", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message_id: "731907388210487296",
  }),
});

const state = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/read",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "message_id": "731907388210487296",
    },
)

state = res.json()

use Illuminate\Support\Facades\Http;

$state = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/read', [
        'message_id' => '731907388210487296',
    ])
    ->json();

Response

{
  "id": "731902455120183296",
  "state": "active",
  "unread_count": 0,
  "muted": false,
  "hidden": false,
  "last_read_message_id": "731907388210487296"
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/conversations/{id}/accept

Accept a message request

Pixelfed only User token Scope write

Path parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/accept" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/accept", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const state = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/accept",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

state = res.json()

use Illuminate\Support\Facades\Http;

$state = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/accept')
    ->json();

Response

{
  "id": "731902455120183296",
  "state": "active",
  "unread_count": 1,
  "muted": false,
  "hidden": false,
  "last_read_message_id": null
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/conversations/{id}/mute

Mute a conversation

Pixelfed only User token Scope write

Path parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/mute" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/mute", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const state = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/mute",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

state = res.json()

use Illuminate\Support\Facades\Http;

$state = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/mute')
    ->json();

Response

{
  "id": "731902455120183296",
  "state": "active",
  "unread_count": 0,
  "muted": true,
  "hidden": false,
  "last_read_message_id": "731907388210487296"
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/conversations/{id}/unmute

Unmute a conversation

Pixelfed only User token Scope write

Path parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/unmute" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/unmute", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const state = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/unmute",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

state = res.json()

use Illuminate\Support\Facades\Http;

$state = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/unmute')
    ->json();

Response

{
  "id": "731902455120183296",
  "state": "active",
  "unread_count": 0,
  "muted": false,
  "hidden": false,
  "last_read_message_id": "731907388210487296"
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/conversations/{id}/hide

Hide a conversation

Pixelfed only User token Scope write

Path parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/hide" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/hide", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const state = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/hide",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

state = res.json()

use Illuminate\Support\Facades\Http;

$state = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/hide')
    ->json();

Response

{
  "id": "731902455120183296",
  "state": "active",
  "unread_count": 0,
  "muted": false,
  "hidden": true,
  "last_read_message_id": "731907388210487296"
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/conversations/{id}/unhide

Unhide a conversation

Pixelfed only User token Scope write

Path parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/unhide" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/unhide", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const state = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/unhide",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

state = res.json()

use Illuminate\Support\Facades\Http;

$state = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations/731902455120183296/unhide')
    ->json();

Response

{
  "id": "731902455120183296",
  "state": "active",
  "unread_count": 0,
  "muted": false,
  "hidden": false,
  "last_read_message_id": "731907388210487296"
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/conversations/{id}/leave

Leave a group

Pixelfed only User token Scope write

Path parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/conversations/731911020536471552/leave" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/conversations/731911020536471552/leave", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const state = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/conversations/731911020536471552/leave",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

state = res.json()

use Illuminate\Support\Facades\Http;

$state = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/conversations/731911020536471552/leave')
    ->json();

Response

{
  "id": "731911020536471552",
  "state": "left",
  "unread_count": 0,
  "muted": false,
  "hidden": false,
  "last_read_message_id": "731911388741324800"
}

{
  "error": "Only group conversations can be left."
}

GET/api/v1.1/direct/compose/mutuals

List mutuals to message

Pixelfed only User token

Query parameters

cursorinteger

Returns

curl "https://pixelfed.social/api/v1.1/direct/compose/mutuals" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/compose/mutuals", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const mutuals = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1.1/direct/compose/mutuals",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

mutuals = res.json()

use Illuminate\Support\Facades\Http;

$mutuals = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.1/direct/compose/mutuals')
    ->json();

Response

{
  "data": [{
    "id": "412760184563377",
    "username": "jonas",
    "acct": "jonas",
    "display_name": "Jonas Berg",
    "locked": false,
    "followers_count": 208,
    "following_count": 190,
    "url": "https://pixelfed.social/jonas",
    "avatar": "https://pixelfed.social/storage/avatars/412/760/jonas.jpg",
    "local": true
  }],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

{
  "message": "The cursor field must be an integer.",
  "errors": {
    "cursor": ["The cursor field must be an integer."]
  }
}

POST/api/v1.1/direct/lookup

Look up a recipient

Pixelfed only Supports _pe User token

Query parameters

_peboolean

Body parameters

qstringrequired

remoteboolean

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/lookup" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "jon"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/lookup", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "jon",
  }),
});

const results = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/lookup",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "q": "jon",
    },
)

results = res.json()

use Illuminate\Support\Facades\Http;

$results = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/lookup', [
        'q' => 'jon',
    ])
    ->json();

Response

[{
  "local": true,
  "id": "412760184563377",
  "name": "jonas",
  "privacy": true,
  "avatar": "https://pixelfed.social/storage/avatars/412/760/jonas.jpg",
  "account": {
    "id": "412760184563377",
    "username": "jonas",
    "acct": "jonas",
    "display_name": "Jonas Berg",
    "url": "https://pixelfed.social/jonas",
    "avatar": "https://pixelfed.social/storage/avatars/412/760/jonas.jpg",
    "local": true
  }
}]

{
  "message": "The q field must be at least 2 characters.",
  "errors": {
    "q": ["The q field must be at least 2 characters."]
  }
}

GET/api/v1.1/direct/thread

Get a 1:1 thread (legacy)

Pixelfed only User token

Query parameters

pidstringrequired

max_idstring

min_idstring

Returns

curl "https://pixelfed.social/api/v1.1/direct/thread?pid=412760184563377" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/direct/thread?pid=412760184563377", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const thread = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1.1/direct/thread",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    params={
        "pid": "412760184563377",
    },
)

thread = res.json()

use Illuminate\Support\Facades\Http;

$thread = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.1/direct/thread', [
        'pid' => '412760184563377',
    ])
    ->json();

Response

{
  "id": "412760184563377",
  "name": "Jonas Berg",
  "username": "jonas",
  "avatar": "https://pixelfed.social/storage/avatars/412/760/jonas.jpg",
  "url": "https://pixelfed.social/jonas",
  "muted": false,
  "isLocal": true,
  "domain": null,
  "created_at": "2020-05-19T11:02:44+00:00",
  "updated_at": "2026-10-01T16:20:05+00:00",
  "timeAgo": "6y",
  "lastMessage": "",
  "messages": [{
    "id": "731907388210487296",
    "hidden": false,
    "isAuthor": false,
    "type": "text",
    "text": "Are you shooting the harbour again on Saturday?",
    "media": null,
    "carousel": [],
    "created_at": "2026-10-16T19:04:22+00:00",
    "timeAgo": "14h ago",
    "seen": true,
    "reportId": "731907388210487296",
    "meta": null
  }],
  "conversation_id": "731902455120183296"
}

{
  "error": "Invalid permissions for this action"
}

{
  "error": "Record not found"
}

POST/api/v1.1/direct/thread/send

Send a 1:1 message (legacy)

Pixelfed only User token

Body parameters

to_idstringrequired

messagestringrequired

typestringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/thread/send" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to_id": "412760184563377",
    "message": "Yes, meet at the pier at 7?",
    "type": "text"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/thread/send", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to_id: "412760184563377",
    message: "Yes, meet at the pier at 7?",
    type: "text",
  }),
});

const message = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/thread/send",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "to_id": "412760184563377",
        "message": "Yes, meet at the pier at 7?",
        "type": "text",
    },
)

message = res.json()

use Illuminate\Support\Facades\Http;

$message = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/thread/send', [
        'to_id' => '412760184563377',
        'message' => 'Yes, meet at the pier at 7?',
        'type' => 'text',
    ])
    ->json();

Response

{
  "id": "731911388741324800",
  "hidden": false,
  "isAuthor": true,
  "type": "text",
  "text": "Yes, meet at the pier at 7?",
  "media": null,
  "carousel": [],
  "created_at": "2026-10-17T09:32:18+00:00",
  "timeAgo": "1s ago",
  "seen": false,
  "reportId": "731911388741324800",
  "meta": null
}

{
  "error": "You need to wait a bit before you can DM another account"
}

{
  "error": "You can send more messages once your request is accepted."
}

POST/api/v1.1/direct/thread/media

Send a photo or video (legacy)

Pixelfed only User token

Body parameters

filefilerequired

to_idstringrequired

messagestring

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/thread/media" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@fog.jpg" \
  -F "to_id=412760184563377"

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("to_id", "412760184563377");

const res = await fetch("https://pixelfed.social/api/v1.1/direct/thread/media", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: form,
});

const message = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/thread/media",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    files={"file": open("fog.jpg", "rb")},
    data={
        "to_id": "412760184563377",
    },
)

message = res.json()

use Illuminate\Support\Facades\Http;

$message = Http::acceptJson()
    ->withToken($token)
    ->attach('file', fopen('fog.jpg', 'r'), 'fog.jpg')
    ->post('https://pixelfed.social/api/v1.1/direct/thread/media', [
        'to_id' => '412760184563377',
    ])
    ->json();

Response

{
  "id": "731902611844546560",
  "reportId": "731902611844546560",
  "type": "photo",
  "url": "https://pixelfed.social/storage/m/_v2/2/fog.jpg"
}

{
  "error": "Account size limit reached."
}

{
  "error": ""
}

POST/api/v1.1/direct/thread/read

Mark a 1:1 thread read (legacy)

Pixelfed only User token

Body parameters

pidstringrequired

sidstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/thread/read" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pid": "412760184563377",
    "sid": "731907388210487296"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/thread/read", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    pid: "412760184563377",
    sid: "731907388210487296",
  }),
});

const ids = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/thread/read",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "pid": "412760184563377",
        "sid": "731907388210487296",
    },
)

ids = res.json()

use Illuminate\Support\Facades\Http;

$ids = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/thread/read', [
        'pid' => '412760184563377',
        'sid' => '731907388210487296',
    ])
    ->json();

Response

["731907388210487296"]

{
  "error": "Invalid permissions for this action"
}

DELETE/api/v1.1/direct/thread/message

Delete a message (legacy)

Pixelfed only User token

Body parameters

idstringrequired

Returns

curl -X DELETE "https://pixelfed.social/api/v1.1/direct/thread/message" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "731911388741324800"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/thread/message", {
  method: "DELETE",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "731911388741324800",
  }),
});

const result = await res.json();

import requests

res = requests.delete(
    "https://pixelfed.social/api/v1.1/direct/thread/message",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "id": "731911388741324800",
    },
)

result = res.json()

use Illuminate\Support\Facades\Http;

$result = Http::acceptJson()
    ->withToken($token)
    ->delete('https://pixelfed.social/api/v1.1/direct/thread/message', [
        'id' => '731911388741324800',
    ])
    ->json();

Response

[200]

{
  "error": "Record not found"
}

POST/api/v1.1/direct/thread/mute

Mute a 1:1 thread (legacy)

Pixelfed only User token

Body parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/thread/mute" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "412760184563377"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/thread/mute", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "412760184563377",
  }),
});

const result = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/thread/mute",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "id": "412760184563377",
    },
)

result = res.json()

use Illuminate\Support\Facades\Http;

$result = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/thread/mute', [
        'id' => '412760184563377',
    ])
    ->json();

Response

[200]

{
  "error": "Record not found"
}

POST/api/v1.1/direct/thread/unmute

Unmute a 1:1 thread (legacy)

Pixelfed only User token

Body parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/direct/thread/unmute" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "412760184563377"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/direct/thread/unmute", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "412760184563377",
  }),
});

const result = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/direct/thread/unmute",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "id": "412760184563377",
    },
)

result = res.json()

use Illuminate\Support\Facades\Http;

$result = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/direct/thread/unmute', [
        'id' => '412760184563377',
    ])
    ->json();

Response

[200]

{
  "error": "Record not found"
}

Pixelfed is free and open source software. Edit this page Report a docs issue