Stories

GET/api/v1.2/stories/carousel

Get the stories carousel

Pixelfed only User token

Returns

curl "https://pixelfed.social/api/v1.2/stories/carousel" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

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

const carousel = await res.json();

import requests

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

carousel = res.json()

use Illuminate\Support\Facades\Http;

$carousel = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.2/stories/carousel')
    ->json();

Response

{
  "nodes": [{
    "id": "self:2",
    "username": "dansup",
    "username_acct": "dansup",
    "profile_id": "2",
    "avatar": "https://pixelfed.social/storage/avatars/2/avatar.jpg",
    "is_author": true,
    "stories": [{
      "id": "731056220419686400",
      "type": "photo",
      "url": "https://pixelfed.social/storage/_esm.t3/Kq9y/xN4bRe2/17aQ3kTz/Ab_t7Lw2nR.jpg",
      "overlays": [{
        "type": "text",
        "content": "Low tide again",
        "color": "#FFFFFF",
        "fontSize": 42,
        "x": 540,
        "y": 1500,
        "rotation": 0,
        "scale": 1
      }],
      "duration": 10000,
      "viewed": true,
      "created_at": "2026-10-17T07:12:44+00:00",
      "view_count": 23
    }],
    "url": "https://pixelfed.social/stories/dansup",
    "hasViewed": true
  }, {
    "id": "pfs:412760184563377",
    "username": "jonas",
    "username_acct": "jonas",
    "profile_id": "412760184563377",
    "avatar": "https://pixelfed.social/storage/avatars/412760184563377/avatar.jpg",
    "is_author": false,
    "stories": [{
      "id": "731061790234124288",
      "type": "photo",
      "url": "https://pixelfed.social/storage/_esm.t3/Kq9y/pL0dWe8/17Hc8mYr/Qe_s91Kd2.jpg",
      "overlays": [],
      "duration": 10000,
      "viewed": false,
      "created_at": "2026-10-17T08:34:02+00:00"
    }],
    "url": "https://pixelfed.social/stories/jonas",
    "hasViewed": false
  }]
}

{
  "error": "Record not found"
}

GET/api/v1.1/stories/carousel

Get the stories carousel (v1.1)

Pixelfed only User token

Returns

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

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

const carousel = await res.json();

import requests

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

carousel = res.json()

use Illuminate\Support\Facades\Http;

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

Response

{
  "self": {
    "user": {
      "id": "2",
      "username": "dansup",
      "avatar": "https://pixelfed.social/storage/avatars/2/avatar.jpg",
      "local": true,
      "is_author": true
    },
    "nodes": [{
      "id": "731056220419686400",
      "type": "photo",
      "src": "https://pixelfed.social/storage/_esm.t3/Kq9y/xN4bRe2/17aQ3kTz/Ab_t7Lw2nR.jpg",
      "duration": 5,
      "seen": true,
      "created_at": "2026-10-17T07:12:44+00:00"
    }]
  },
  "nodes": [{
    "id": "pfs:412760184563377",
    "user": {
      "id": "412760184563377",
      "username": "jonas",
      "username_acct": "jonas",
      "avatar": "https://pixelfed.social/storage/avatars/412760184563377/avatar.jpg",
      "local": true,
      "is_author": false
    },
    "nodes": [{
      "id": "731061790234124288",
      "pid": "412760184563377",
      "type": "photo",
      "src": "https://pixelfed.social/storage/_esm.t3/Kq9y/pL0dWe8/17Hc8mYr/Qe_s91Kd2.jpg",
      "duration": 3,
      "seen": false,
      "created_at": "2026-10-17T08:34:02+00:00"
    }],
    "url": "https://pixelfed.social/stories/jonas",
    "seen": false
  }]
}

{
  "error": "Record not found"
}

POST/api/v1.2/stories/publish

Publish a story

Pixelfed only User token

Body parameters

imagefilerequired

overlays[]array of objects

overlays[][content]string

overlays[][backgroundColor]string

overlays[][fontFamily]string

Returns

curl -X POST "https://pixelfed.social/api/v1.2/stories/publish" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@low-tide.jpg" \
  -F "overlays[0][type]=text" \
  -F "overlays[0][content]=Low tide again" \
  -F "overlays[0][color]=#FFFFFF" \
  -F "overlays[0][fontSize]=42" \
  -F "overlays[0][x]=540" \
  -F "overlays[0][y]=1500"

const form = new FormData();
form.append("image", fileInput.files[0]);
form.append("overlays[0][type]", "text");
form.append("overlays[0][content]", "Low tide again");
form.append("overlays[0][color]", "#FFFFFF");
form.append("overlays[0][fontSize]", "42");
form.append("overlays[0][x]", "540");
form.append("overlays[0][y]", "1500");

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

const story = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.2/stories/publish",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    files={"image": open("low-tide.jpg", "rb")},
    data={
        "overlays[0][type]": "text",
        "overlays[0][content]": "Low tide again",
        "overlays[0][color]": "#FFFFFF",
        "overlays[0][fontSize]": "42",
        "overlays[0][x]": "540",
        "overlays[0][y]": "1500",
    },
)

story = res.json()

use Illuminate\Support\Facades\Http;

$story = Http::acceptJson()
    ->withToken($token)
    ->attach('image', fopen('low-tide.jpg', 'r'), 'low-tide.jpg')
    ->post('https://pixelfed.social/api/v1.2/stories/publish', [
        'overlays[0][type]' => 'text',
        'overlays[0][content]' => 'Low tide again',
        'overlays[0][color]' => '#FFFFFF',
        'overlays[0][fontSize]' => '42',
        'overlays[0][x]' => '540',
        'overlays[0][y]' => '1500',
    ])
    ->json();

Response

{
  "code": 200,
  "msg": "Successfully added"
}

{
  "code": 418,
  "error": "You’ve reached your daily limit of 20 Stories."
}

{
  "message": "The image field has invalid image dimensions.",
  "errors": {
    "image": ["The image field has invalid image dimensions."]
  }
}

GET/api/v1.2/stories/mention-autocomplete

Autocomplete mentions

Pixelfed only User token

Query parameters

qstringrequired

Returns

curl "https://pixelfed.social/api/v1.2/stories/mention-autocomplete?q=@jo" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.2/stories/mention-autocomplete?q=@jo", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const accounts = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1.2/stories/mention-autocomplete",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    params={
        "q": "@jo",
    },
)

accounts = res.json()

use Illuminate\Support\Facades\Http;

$accounts = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.2/stories/mention-autocomplete', [
        'q' => '@jo',
    ])
    ->json();

Response

[{
  "id": "412760184563377",
  "username": "jonas",
  "acct": "jonas",
  "display_name": "Jonas Berg",
  "locked": false,
  "followers_count": 318,
  "following_count": 204,
  "statuses_count": 96,
  "url": "https://pixelfed.social/jonas",
  "avatar": "https://pixelfed.social/storage/avatars/412760184563377/avatar.jpg",
  "local": true,
  "has_story": true
}]

{
  "message": "The q field is required.",
  "errors": {
    "q": ["The q field is required."]
  }
}

POST/api/v1.1/stories/add

Upload story media (v1.1)

Pixelfed only User token

Body parameters

filefilerequired

durationinteger

Returns

curl -X POST "https://pixelfed.social/api/v1.1/stories/add" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@harbour.mp4" \
  -F "duration=8"

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

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

const upload = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/stories/add",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    files={"file": open("harbour.mp4", "rb")},
    data={
        "duration": "8",
    },
)

upload = res.json()

use Illuminate\Support\Facades\Http;

$upload = Http::acceptJson()
    ->withToken($token)
    ->attach('file', fopen('harbour.mp4', 'r'), 'harbour.mp4')
    ->post('https://pixelfed.social/api/v1.1/stories/add', [
        'duration' => '8',
    ])
    ->json();

Response

{
  "code": 200,
  "msg": "Successfully added",
  "media_id": "731070114392444928",
  "media_url": "https://pixelfed.social/storage/_esm.t3/Kq9y/xN4bRe2/17Zp2cVb/Lm_c8Qe1.mp4?v=1792226184",
  "media_type": "video"
}

{
  "error": "You have reached your limit for new Stories today."
}

POST/api/v1.1/stories/publish

Publish a story (v1.1)

Pixelfed only User token

Body parameters

media_idstringrequired

durationintegerrequired

can_replybooleanrequired

can_reactbooleanrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/stories/publish" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "media_id": "731070114392444928",
    "duration": 8,
    "can_reply": true,
    "can_react": true
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/stories/publish", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    media_id: "731070114392444928",
    duration: 8,
    can_reply: true,
    can_react: true,
  }),
});

const story = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/stories/publish",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "media_id": "731070114392444928",
        "duration": 8,
        "can_reply": True,
        "can_react": True,
    },
)

story = res.json()

use Illuminate\Support\Facades\Http;

$story = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/stories/publish', [
        'media_id' => '731070114392444928',
        'duration' => 8,
        'can_reply' => true,
        'can_react' => true,
    ])
    ->json();

Response

{
  "code": 200,
  "msg": "Successfully published"
}

{
  "error": "Record not found"
}

{
  "message": "The can reply field is required.",
  "errors": {
    "can_reply": ["The can reply field is required."]
  }
}

POST/api/v1.1/stories/seen

Mark a story as seen

Pixelfed only User token

Body parameters

idstringrequired

Returns

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

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

const result = await res.json();

import requests

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

result = res.json()

use Illuminate\Support\Facades\Http;

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

Response

{
  "code": 200
}

{
  "error": "Invalid permission"
}

{
  "error": "Record not found"
}

GET/api/v1.2/stories/viewers

List story viewers

Pixelfed only User token

Query parameters

sidstringrequired

cursorstring

Returns

curl "https://pixelfed.social/api/v1.2/stories/viewers?sid=731056220419686400" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.2/stories/viewers?sid=731056220419686400", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const viewers = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1.2/stories/viewers",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    params={
        "sid": "731056220419686400",
    },
)

viewers = res.json()

use Illuminate\Support\Facades\Http;

$viewers = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1.2/stories/viewers', [
        'sid' => '731056220419686400',
    ])
    ->json();

Response

{
  "data": [{
    "id": "412760184563377",
    "username": "jonas",
    "acct": "jonas",
    "display_name": "Jonas Berg",
    "avatar": "https://pixelfed.social/storage/avatars/412760184563377/avatar.jpg",
    "local": true,
    "viewed_at": "2026-10-17T08:41:19+00:00"
  }],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "https://pixelfed.social/api/v1.2/stories/viewers?sid=731056220419686400&cursor=eyJpZCI6NzMxMDU5MDAyLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
  },
  "meta": {
    "path": "https://pixelfed.social/api/v1.2/stories/viewers",
    "per_page": 10,
    "next_cursor": "eyJpZCI6NzMxMDU5MDAyLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prev_cursor": null
  }
}

{
  "error": "Record not found"
}

POST/api/v1.1/stories/comment

Reply to a story

Pixelfed only User token

Body parameters

sidstringrequired

captionstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/stories/comment" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sid": "731061790234124288",
    "caption": "Is that the old ferry dock?"
  }'

const res = await fetch("https://pixelfed.social/api/v1.1/stories/comment", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sid: "731061790234124288",
    caption: "Is that the old ferry dock?",
  }),
});

const result = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/stories/comment",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "sid": "731061790234124288",
        "caption": "Is that the old ferry dock?",
    },
)

result = res.json()

use Illuminate\Support\Facades\Http;

$result = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/stories/comment', [
        'sid' => '731061790234124288',
        'caption' => 'Is that the old ferry dock?',
    ])
    ->json();

Response

{
  "code": 200,
  "msg": "Sent!"
}

{
  "error": "Invalid permission"
}

{
  "error": ""
}

POST/api/v1.1/stories/self-expire/{id}

Delete a story

Pixelfed only User token

Path parameters

idstringrequired

Returns

curl -X POST "https://pixelfed.social/api/v1.1/stories/self-expire/731056220419686400" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1.1/stories/self-expire/731056220419686400", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const result = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1.1/stories/self-expire/731056220419686400",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

result = res.json()

use Illuminate\Support\Facades\Http;

$result = Http::acceptJson()
    ->withToken($token)
    ->post('https://pixelfed.social/api/v1.1/stories/self-expire/731056220419686400')
    ->json();

Response

{
  "code": 200,
  "msg": "Successfully deleted"
}

{
  "error": "Record not found"
}

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