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
- Endpoints
- Entities
- Changelog
- Federation
- Versioning
- Rate limits
- Story Filters
- Story Links
- Story Layers
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 |  |
| filter_name | Media filter name |  |
- 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 | |
- response: 200
- rate limit: N/A
[DELETE] /api/stories/v1/delete - Delete Story Item
- params:
| name | description | required |
|---|---|---|
| id | Integer ID of Story Item | |
- response: 200
- rate limit: 50 per day
Entities
Story
| Attribute | Type | Nullable | Description |
|---|---|---|---|
| id | Integer | |
Story identifier |
| photo | String (URL) | |
Profile Avatar URL |
| name | String | |
Profile username |
| link | String (URL) | |
Profile URL |
| lastUpdated | String (Timestamp) | |
Last updated UNIX timestamp |
| seen | Boolean | |
Has seen Story since lastUpdated |
| items | Array of StoryItem | |
Collection of story content |
StoryItem
| Attribute | Type | Nullable | Description |
|---|---|---|---|
| id | Integer | |
Story identifier |
| type | String (Enum) | |
StoryItem Media Type |
| length | Integer | |
Duration in seconds |
| src | String (URL) | |
Media source |
| preview | String (URL) | |
Media source thumbnail |
| link | String (URL) | |
Swipe up link |
| linkText | String | |
Swipe up link text |
| time | String (Timestamp) | |
Created at UNIX timestamp |
| expires_at | String (Timestamp) | |
Expires at UNIX timestamp |
| seen | Boolean | |
Has seen Story since lastUpdated |
Types
- Photo (image/jpeg, image/png, image/gif)
- Video (video/mp4)
Changelog
Added
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 