Posts

Video posts

video-service

Posts of a video, a GIF or an animated PNG, sent straight to storage in parts and made ready by a worker in several sizes; and replies with one (videos.md). Optional: off until the installation turns video on.

One video post

GET/videos/{id}

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode application/json
400
the request is not well formed, or a value in it is not one it may be
403
the viewer may not see it
404
there is no such post

Request

curl "https://api.example.org/videos/<id>"

const response = await fetch('https://api.example.org/videos/<id>', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/videos/<id>",
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change a video post's words

PATCH/videos/{id}

A video needs a title, and may have nothing more said of it.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Body application/json or application/x-www-form-urlencoded or multipart/form-data

contentstring
Its words, as Markdown. At most 8000 characters.
languagestring
The language it is written in, as a BCP 47 tag. At most 12 characters.
titlestring
Its title, if it has one. At most 100 characters.

Answers

200
OK
MediumNode application/json
400
language_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post

Request

curl -X PATCH "https://api.example.org/videos/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "string",
    "language": "en",
    "title": "string"
  }'

const response = await fetch('https://api.example.org/videos/<id>', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "content": "string",
    "language": "en",
    "title": "string"
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/videos/<id>",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "content": "string",
      "language": "en",
      "title": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Delete a video post

DELETE/videos/{id}

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
it is gone
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not delete it
404
there is no such post

Request

curl -X DELETE "https://api.example.org/videos/<id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/videos/<id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/videos/<id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Change who may see it

PATCH/videos/{id}/access

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Body application/x-www-form-urlencoded or multipart/form-data

accessstring
Who may see it: public, registered, followers, leaders, mutuals, admins or myself (permissions.md). The widest an installation allows when left out. One of public, registered, followers, leaders, mutuals, admins, myself. public unless given.

Answers

200
OK
MediumNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
access_not_allowed, with the audiences it may have; or reply_follows_its_thread: a reply has no setting of its own; its thread decides, without them
AudienceRefusal application/json

Request

curl -X PATCH "https://api.example.org/videos/<id>/access" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "access=public"

const form = new URLSearchParams();
form.append('access', "public");
const response = await fetch('https://api.example.org/videos/<id>/access', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/videos/<id>/access",
    headers={"Authorization": f"Bearer {token}"},
    data={"access": "public"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Open or close replies

PATCH/videos/{id}/comment-status

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Body application/x-www-form-urlencoded or multipart/form-data

statusboolean
Whether it takes replies.

Answers

200
OK
MediumNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/videos/<id>/comment-status" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "status=false"

const form = new URLSearchParams();
form.append('status', "false");
const response = await fetch('https://api.example.org/videos/<id>/comment-status', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/videos/<id>/comment-status",
    headers={"Authorization": f"Bearer {token}"},
    data={"status": "false"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Download it

GET/videos/{id}/download

A redirect to one size of it, named to be saved. For whoever may see the post, when it may be downloaded.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post's id.
sizeintegerin query
Which size, by its height: 720. The largest when left out.

Answers

302
the file is at the address in Location
403
it may not be downloaded
404
there is no such post or size that the viewer may see
429
too many downloads lately

Request

curl "https://api.example.org/videos/<id>/download"

const response = await fetch('https://api.example.org/videos/<id>/download', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/videos/<id>/download",
)
answer = response.json()

Change whether it may be downloaded

PATCH/videos/{id}/download

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Body application/json or application/x-www-form-urlencoded or multipart/form-data

allowboolean
Whether whoever can see it may download it.

Answers

200
OK
MediumNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post

Request

curl -X PATCH "https://api.example.org/videos/<id>/download" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow": false
  }'

const response = await fetch('https://api.example.org/videos/<id>/download', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "allow": false
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/videos/<id>/download",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "allow": False
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

A file of a video post

GET/videos/{id}/files/{name}

A redirect to it in storage, at an address good for a short while. Who may see the post is asked each time; nothing in between keeps it.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post's id.
namestringrequiredin path
Which file: one size of the video, by its height (720.mp4), or poster.jpg.

Answers

302
the file is at the address in Location
404
there is no such post or file that the viewer may see

Request

curl "https://api.example.org/videos/<id>/files/<name>"

const response = await fetch('https://api.example.org/videos/<id>/files/<name>', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/videos/<id>/files/<name>",
)
answer = response.json()

Pin it to the profile it is on

PUT/videos/{id}/pin

A profile has one pin: pinning another post moves it. For the profile and its administrators, and site administrators (permissions.md). Answers with the post.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not pin it
404
there is no such post
422
reply_cannot_be_pinned
Refusal application/json

Request

curl -X PUT "https://api.example.org/videos/<id>/pin" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/videos/<id>/pin', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.put(
    "https://api.example.org/videos/<id>/pin",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Take its pin off

DELETE/videos/{id}/pin

A profile has one pin: pinning another post moves it. For the profile and its administrators, and site administrators (permissions.md). Answers with the post.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not pin it
404
there is no such post
422
reply_cannot_be_pinned
Refusal application/json

Request

curl -X DELETE "https://api.example.org/videos/<id>/pin" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/videos/<id>/pin', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/videos/<id>/pin",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change who may quote it

PATCH/videos/{id}/quote-policy

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Body application/json or application/x-www-form-urlencoded or multipart/form-data

quote_policystringrequired
Who may quote it: anyone, followers or nobody. At most 16 characters.

Answers

200
OK
MediumNode application/json
400
quote_policy_invalid, or not well formed
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/videos/<id>/quote-policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_policy": "string"
  }'

const response = await fetch('https://api.example.org/videos/<id>/quote-policy', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "quote_policy": "string"
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/videos/<id>/quote-policy",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "quote_policy": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change who may reply

PATCH/videos/{id}/reply-access

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Body application/json or application/x-www-form-urlencoded or multipart/form-data

reply_accessstringrequired
Who may reply: anyone, nobody, or any of followers, following and mentioned joined by commas. At most 64 characters.

Answers

200
OK
MediumNode application/json
400
reply_access_invalid, or not well formed
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/videos/<id>/reply-access" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reply_access": "string"
  }'

const response = await fetch('https://api.example.org/videos/<id>/reply-access', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "reply_access": "string"
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/videos/<id>/reply-access",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "reply_access": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

A profile's video posts

GET/videos/{owner_id}/

Those the viewer may see.

Who: Anyone, signed in or not

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
orderingstringin query
What they are ordered by. At most 15 characters. One of updated_at, created_at, enabled. created_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
disabledbooleanin query
Disabled posts as well, for whoever may see them.
owner_idintegerrequiredin path
The profile whose posts are listed. At least 1.
librarybooleanin query
The viewer's own media library instead: all their photo or video posts on their own profile, with those they put up from inside the article editor, which no other list holds. The owner is then the viewer, whatever the path says.
draftsbooleanin query
The viewer's own drafts on this profile instead, articles or topics still being written, which no other list holds.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be

Request

curl "https://api.example.org/videos/<owner_id>/"

const response = await fetch('https://api.example.org/videos/<owner_id>/', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/videos/<owner_id>/",
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "comment_count": 1,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "link_previews": [
        null
      ],
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent_id": 42,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "repost_count": 1,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "uri": "https://example.org/",
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Begin a video post

POST/videos/{owner_id}/uploads

Everything about the post is settled here, as when any post is made, and the file is then sent straight to storage in parts (POST /videos/uploads/{id}/parts). With parent_id, a reply with a video, on its author's own profile.

Who: Somebody signed in, with media:write

Parameters

owner_idintegerrequiredin path
The profile the post will be on.

Body application/json or application/x-www-form-urlencoded or multipart/form-data

accessstring
Who may see it (permissions.md). One of public, registered, followers, leaders, mutuals, admins, myself.
allow_downloadboolean
Whether whoever can see it may download it. Left out, the post starts with what the profile it is on says.
contentstring
Its words, as Markdown. At most 8000 characters.
content_typestringrequired
What kind of file it is: video/mp4, video/quicktime, video/webm, image/gif or image/png. At most 100 characters.
languagestring
The language it is written in, as a BCP 47 tag. At most 12 characters.
library_onlyboolean
In the author's media library only: put up from inside the article editor to be shown in an article, and listed and announced nowhere. Only on the author's own profile, and never a reply.
parent_idinteger
What it answers, when it is a reply: then it is on its author's own profile, and what it is open to, who may answer it and quoting are its thread's, so those above are not read. At least 1.
quote_policystring
Who may quote it: anyone, followers or nobody. At most 16 characters.
reply_accessstring
Who may reply: anyone, nobody, or any of followers, following and mentioned joined by commas. At most 64 characters.
sizeintegerrequired
How large the file is, in bytes. At least 1.
titlestring
Its title, if it has one: neither a post nor a reply needs one. At most 100 characters.

Answers

201
Created
video.UploadResponse application/json
400
language_invalid, reply_access_invalid or quote_policy_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
uploads_off: this installation takes no video; or the viewer may not post or reply here, without a body
Refusal application/json
404
there is no such profile, or nothing it answers that the viewer may see
410
it answers a reply that was removed
413
Request Entity Too Large
video.UploadTooLarge application/json
415
not_a_video
Refusal application/json
422
Unprocessable Entity
AudienceRefusal application/json
429
too_many: as many as may be begun in a day
Refusal application/json

Request

curl -X POST "https://api.example.org/videos/<owner_id>/uploads" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access": "public",
    "allow_download": false,
    "content": "string",
    "content_type": "string",
    "language": "en",
    "library_only": false,
    "parent_id": 42,
    "quote_policy": "string",
    "reply_access": "string",
    "size": 1,
    "title": "string"
  }'

const response = await fetch('https://api.example.org/videos/<owner_id>/uploads', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "access": "public",
    "allow_download": false,
    "content": "string",
    "content_type": "string",
    "language": "en",
    "library_only": false,
    "parent_id": 42,
    "quote_policy": "string",
    "reply_access": "string",
    "size": 1,
    "title": "string"
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/videos/<owner_id>/uploads",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "access": "public",
      "allow_download": False,
      "content": "string",
      "content_type": "string",
      "language": "en",
      "library_only": False,
      "parent_id": 42,
      "quote_policy": "string",
      "reply_access": "string",
      "size": 1,
      "title": "string"
    },
)
answer = response.json()

Answer · 201

{
  "created_at": "2026-10-27T09:30:00Z",
  "error": "string",
  "id": "string",
  "node_id": 42,
  "owner_id": 42,
  "parent_id": 42,
  "part_count": 1,
  "part_size": 1,
  "size": 1,
  "status": "string",
  "title": "string"
}

The viewer's uploads

GET/videos/uploads

Those being sent or waiting for the worker, and those that failed in the last day, the latest first.

Who: Somebody signed in

Answers

200
OK
object application/json
401
no token, or one that has expired

Request

curl "https://api.example.org/videos/uploads" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/videos/uploads', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/videos/uploads",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "created_at": "2026-10-27T09:30:00Z",
      "error": "string",
      "id": "string",
      "node_id": 42,
      "owner_id": 42,
      "parent_id": 42,
      "part_count": 1,
      "part_size": 1,
      "size": 1,
      "status": "string",
      "title": "string"
    }
  ]
}

One upload

GET/videos/uploads/{id}

Asked again until it is ready, when node_id is the post, or failed, when error says why.

Who: Somebody signed in

Parameters

idstring (uuid)requiredin path
The upload's id, as its start answered.

Answers

200
OK
video.UploadResponse application/json
401
no token, or one that has expired
404
there is no such upload of the viewer's

Request

curl "https://api.example.org/videos/uploads/<id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/videos/uploads/<id>', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/videos/uploads/<id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "created_at": "2026-10-27T09:30:00Z",
  "error": "string",
  "id": "string",
  "node_id": 42,
  "owner_id": 42,
  "parent_id": 42,
  "part_count": 1,
  "part_size": 1,
  "size": 1,
  "status": "string",
  "title": "string"
}

Give an upload up

DELETE/videos/uploads/{id}

One being sent, waiting for the worker, or failed.

Who: Somebody signed in

Parameters

idstring (uuid)requiredin path
The upload's id, as its start answered.

Answers

204
given up
401
no token, or one that has expired
404
there is no such upload of the viewer's
409
finished: it is a post already
Refusal application/json

Request

curl -X DELETE "https://api.example.org/videos/uploads/<id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/videos/uploads/<id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/videos/uploads/<id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Say every part is sent

POST/videos/uploads/{id}/complete

The worker then makes the post. Said twice, the answer is how it stands.

Who: Somebody signed in

Parameters

idstring (uuid)requiredin path
The upload's id, as its start answered.

Answers

200
OK
video.UploadResponse application/json
401
no token, or one that has expired
404
there is no such upload of the viewer's
409
nothing_sent
Refusal application/json
413
too_large: what was sent is larger than it may be
Refusal application/json

Request

curl -X POST "https://api.example.org/videos/uploads/<id>/complete" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/videos/uploads/<id>/complete', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/videos/uploads/<id>/complete",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "created_at": "2026-10-27T09:30:00Z",
  "error": "string",
  "id": "string",
  "node_id": 42,
  "owner_id": 42,
  "parent_id": 42,
  "part_count": 1,
  "part_size": 1,
  "size": 1,
  "status": "string",
  "title": "string"
}

Where to send some parts

POST/videos/uploads/{id}/parts

Signed addresses, good for an hour, each part sent to its own with PUT.

Who: Somebody signed in

Parameters

idstringrequiredin path
The upload's id. Read by the handler from the path itself.

Body application/json

numberslist of integerrequired
Which parts to send, from 1: a few at a time, as they are needed. At least 1 of them. At most 100 of them.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
404
there is no such upload of the viewer's
409
not_uploading: it is not being sent any more
Refusal application/json

Request

curl -X POST "https://api.example.org/videos/uploads/<id>/parts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": [
      1
    ]
  }'

const response = await fetch('https://api.example.org/videos/uploads/<id>/parts', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "numbers": [
      1
    ]
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/videos/uploads/<id>/parts",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "numbers": [
        1
      ]
    },
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "number": 1,
      "url": "https://example.org/"
    }
  ]
}

Written by Claude, reviewed by Rastin Mehr · About this