[PAE-06] Stories

Pixelfed ActivityPub Extension 06 describes methods to exchange ephemeral content via ActivityPub and APIs.

Stories API

This is a live document that is being actively updated.

All endpoints require authentication



About

Stories are a way to share ephemeral media (photos + videos) with your followers that expire after 24 hours.

Interacting with Stories is a bit different than other posts, they don’t appear in timelines or profiles as you would expect. The StoryViewer is a full screen mode that displays Stories like a slide show with a progress bar at the top of the screen.

For now, only local + logged-in followers will be able to view your Stories. We plan to support public and federated Stories in the future!


Endpoints

[GET] /api/stories/v1/me - My Stories

  • params: none
  • response:
{
    "id": "94959343757299712",
    "photo": "https://example.org/storage/avatars/avatar.jpeg",
    "name": "dansup",
    "link": "https://example.org/dansup",
    "lastUpdated": "1572396871",
    "seen": false,
    "items": [
        {
            "id": "94968856191307776",
            "type": "photo",
            "length": 3,
            "src": "https://example.org/public/dSLvzGBy.jpeg",
            "preview": null,
            "link": null,
            "linkText": null,
            "time": "1572399139",
            "expires_at": "1572485539",
            "seen": false
        }
    ]
}
  • rate limit: N/A

[GET] /api/stories/v1/recent - Friends Stories

TBA


[GET] /api/stories/v1/item/{id} - Story Item Object

TBA


[POST] /api/stories/v1/add - Add to Story

  • params:
name description required
file.* Array of File uploads :white_check_mark:
filter_name Media filter name :x:
  • response: 200
  • rate limit: 20 per hour, 50 per day

[POST] /api/stories/v1/viewed - Viewed a Story Item

  • params:
name description required
id Integer ID of Story Item :white_check_mark:
  • response: 200
  • rate limit: N/A

[DELETE] /api/stories/v1/delete - Delete Story Item

  • params:
name description required
id Integer ID of Story Item :white_check_mark:
  • response: 200
  • rate limit: 50 per day

Entities

Story

Attribute Type Nullable Description
id Integer :x: Story identifier
photo String (URL) :x: Profile Avatar URL
name String :x: Profile username
link String (URL) :x: Profile URL
lastUpdated String (Timestamp) :x: Last updated UNIX timestamp
seen Boolean :x: Has seen Story since lastUpdated
items Array of StoryItem :x: Collection of story content

StoryItem

Attribute Type Nullable Description
id Integer :x: Story identifier
type String (Enum) :x: StoryItem Media Type
length Integer :x: Duration in seconds
src String (URL) :x: Media source
preview String (URL) :white_check_mark: Media source thumbnail
link String (URL) :white_check_mark: Swipe up link
linkText String :white_check_mark: Swipe up link text
time String (Timestamp) :x: Created at UNIX timestamp
expires_at String (Timestamp) :x: Expires at UNIX timestamp
seen Boolean :x: Has seen Story since lastUpdated

Types

  • Photo (image/jpeg, image/png, image/gif)
  • Video (video/mp4)

Changelog

Added

  • Added v1 endpoints ()

Federation

TBA


Versioning

TBD


Rate Limits

Rate limits are in effect for specific endpoints, you can refer to them in the Endpoints section.

Web and Mobile APIs share the same limits.


Story Filters

The following filters are supported for Photos in Stories:

  • 1977
  • Aden
  • Amaro
  • Ashby
  • Brannan
  • Brooklyn
  • Charmes
  • Clarendon
  • Crema
  • Dogpatch
  • Earlybird
  • Gingham
  • Ginza
  • Hefe
  • Helena
  • Hudson
  • Inkwell
  • Kelvin
  • Kuno
  • Lark
  • Lo-Fi
  • Ludwig
  • Maven
  • Mayfair
  • Moon
  • Nashville
  • Perpetua
  • Poprocket
  • Reyes
  • Rise
  • Sierra
  • Skyline
  • Slumber
  • Stinson
  • Sutro
  • Toaster
  • Valencia
  • Vesper
  • Walden
  • Willow
  • X-Pro II

Story Links

Story Links give users the ability to add a link to Story Items. Swipe up to be redirected to the Story link.

Story Links are only available to admins and users with more than 100 local followers during the beta


Story Layers

TBA :wink:



2 Likes

all I’m seeing at the link is “This extension describes the ability to exchange ephemeral content with a public or followers-only audience.”—is more content coming?

Yes, the spec is still being worked out!

The above API Endpoints are outdated!

We are still working on the updated documentation for this feature, we will not deprecate the above endpoints for at least 1 year.

1 Like

We have implemented and shipped federated Stories. Will work on publishing the PAE document with more information. Since we’re using unconventional methods (bearcaps, custom types) we are only delivering to other Pixelfed instances for now.

2 Likes

Hi @dansup I’ve recently thinking of extending ActivityStreams to include this feature as well across multiple fediverse software.

However, there are still a lot of things I personally have to consider to make this cross-platform, like:

  • When attaching text content, the text metadata should be stored into the activity context as well—this is useful for command-line clients as well as for accessibility reasons
  • Combine links, poll, additional media attachments, as well as attributions for stickers and filters into a “story attachment list”, preferably as an expandable scrolling list that sits at the bottom of the StoryViewer