{ "openapi": "3.1.0", "info": { "title": "Moekura API", "description": "Read and change a Moekura site: search and upload posts, edit tags, moderate. Responses are JSON; errors look like `{\"error\": {\"status\": 404, \"message\": \"Not found\"}}`.\n\nSend an API key (created in your account settings) as `Authorization: Bearer `. Without one, requests are made as a logged-out visitor and can do what visitors can on the site.", "license": { "name": "AGPL-3.0-only", "identifier": "AGPL-3.0-only" }, "version": "0.4.0" }, "servers": [ { "url": "/api/v1" } ], "paths": { "/bans": { "get": { "tags": [ "moderation" ], "summary": "List active bans.", "description": "Needs `ban_users`.", "operationId": "list_bans", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BanList" } } } }, "403": { "description": "You can't ban users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/comments": { "get": { "tags": [ "comments" ], "summary": "List comments.", "description": "Newest first, 50 at a time, on posts you can see. Needs `view_posts`.", "operationId": "list_comments", "parameters": [ { "name": "post_id", "in": "query", "description": "Only comments on this post.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "user", "in": "query", "description": "Only comments by this user (a name).", "required": false, "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Only comments older than this one, for the next page.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentList" } } } }, "404": { "description": "No such user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/comments/{id}": { "get": { "tags": [ "comments" ], "summary": "Get a comment.", "description": "Needs `view_posts`.", "operationId": "get_comment", "parameters": [ { "name": "id", "in": "path", "description": "Comment number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiComment" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "put": { "tags": [ "comments" ], "summary": "Change your comment.", "description": "Needs `comment`; only the author changes a comment.", "operationId": "update_comment", "parameters": [ { "name": "id", "in": "path", "description": "Comment number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentText" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiComment" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "delete": { "tags": [ "comments" ], "summary": "Delete your comment.", "description": "Needs `comment`; only the author deletes a comment this way (staff\nhide it instead).", "operationId": "delete_comment", "parameters": [ { "name": "id", "in": "path", "description": "Comment number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/comments/{id}/hide": { "post": { "tags": [ "moderation" ], "summary": "Hide a comment.", "description": "Needs `moderate_comments`. Upholds the comment's open reports; logged.", "operationId": "hide_comment", "parameters": [ { "name": "id", "in": "path", "description": "Comment number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiComment" } } } }, "400": { "description": "Already hidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/comments/{id}/report": { "post": { "tags": [ "comments" ], "summary": "Report a comment.", "description": "Needs `flag`. Staff find reported comments under Moderation.", "operationId": "report_comment", "parameters": [ { "name": "id", "in": "path", "description": "Comment number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "description": "No reason, or already reported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/comments/{id}/restore": { "post": { "tags": [ "moderation" ], "summary": "Restore a hidden or deleted comment.", "description": "Needs `moderate_comments`; logged.", "operationId": "restore_comment", "parameters": [ { "name": "id", "in": "path", "description": "Comment number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiComment" } } } }, "400": { "description": "Not hidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/comments/{id}/vote": { "put": { "tags": [ "comments" ], "summary": "Vote on a comment.", "description": "Needs `vote`; not on your own comments.", "operationId": "vote_on_comment", "parameters": [ { "name": "id", "in": "path", "description": "Comment number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentVote" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentScore" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/favorite-groups": { "get": { "tags": [ "users" ], "summary": "List a user's favorite groups.", "description": "Their public groups by name, or all of yours. Needs `view_posts`.", "operationId": "list_favorite_groups", "parameters": [ { "name": "user", "in": "query", "description": "Whose groups (a name); yours when left out.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiFavoriteGroup" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "post": { "tags": [ "users" ], "summary": "Create a favorite group.", "description": "Needs `favorite`; at most 100 each.", "operationId": "create_favorite_group", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInput" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFavoriteGroupWithPosts" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/favorite-groups/{id}": { "get": { "tags": [ "users" ], "summary": "Get a favorite group.", "description": "Public groups, and your own private ones. Needs `view_posts`.", "operationId": "get_favorite_group", "parameters": [ { "name": "id", "in": "path", "description": "Group number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFavoriteGroupWithPosts" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "put": { "tags": [ "users" ], "summary": "Change your favorite group.", "description": "Fields left out stay as they are.", "operationId": "update_favorite_group", "parameters": [ { "name": "id", "in": "path", "description": "Group number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInput" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFavoriteGroupWithPosts" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "delete": { "tags": [ "users" ], "summary": "Delete your favorite group.", "operationId": "delete_favorite_group", "parameters": [ { "name": "id", "in": "path", "description": "Group number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/favorite-groups/{id}/posts": { "post": { "tags": [ "users" ], "summary": "Add a post to the end of your favorite group.", "description": "Adding a post that's already there changes nothing.", "operationId": "add_favorite_group_post", "parameters": [ { "name": "id", "in": "path", "description": "Group number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupPost" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFavoriteGroupWithPosts" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/favorite-groups/{id}/posts/{post_id}": { "delete": { "tags": [ "users" ], "summary": "Take a post out of your favorite group.", "operationId": "remove_favorite_group_post", "parameters": [ { "name": "id", "in": "path", "description": "Group number", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "post_id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/flags": { "get": { "tags": [ "moderation" ], "summary": "List open flags.", "description": "Needs `approve_posts`. The posts whose flags have waited longest, by\npost number, each with its open flags.", "operationId": "list_flags", "parameters": [ { "name": "limit", "in": "query", "description": "Posts to return, up to 100.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FlaggedPost" } } } } }, "403": { "description": "You can't review flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/me": { "get": { "tags": [ "users" ], "summary": "Get your account.", "description": "Needs authentication.", "operationId": "get_me", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMe" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/moderation/log": { "get": { "tags": [ "moderation" ], "summary": "Read the moderation log.", "description": "Needs `view_audit_log`.", "operationId": "list_mod_actions", "parameters": [ { "name": "action", "in": "query", "description": "Only this kind of action (`post.delete`, `user.ban`, …).", "required": false, "schema": { "type": "string" } }, { "name": "actor", "in": "query", "description": "Only actions by this user.", "required": false, "schema": { "type": "string" } }, { "name": "post_id", "in": "query", "description": "Only actions on this post.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "user", "in": "query", "description": "Only actions on this user.", "required": false, "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Entries older than this id: a previous page's `next_before`.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/network-bans": { "post": { "tags": [ "moderation" ], "summary": "Ban a network.", "description": "Needs `ban_users`. Requests from the network can read but not change\nanything, and it can't register or log in.", "operationId": "ban_network", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewNetworkBan" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiNetworkBan" } } } }, "400": { "description": "The range isn't valid, is too wide, or includes your address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/network-bans/{id}": { "delete": { "tags": [ "moderation" ], "summary": "Lift a network ban.", "description": "Needs `ban_users`.", "operationId": "lift_network_ban", "parameters": [ { "name": "id", "in": "path", "description": "Network ban id", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Lifted" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/notes/{id}": { "get": { "tags": [ "notes" ], "summary": "Get a note.", "description": "Needs `view_posts`.", "operationId": "get_note", "parameters": [ { "name": "id", "in": "path", "description": "Note number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiNote" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "put": { "tags": [ "notes" ], "summary": "Change a note.", "description": "Needs `edit_notes`. Fields left out stay as they are.", "operationId": "update_note", "parameters": [ { "name": "id", "in": "path", "description": "Note number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteChanges" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiNote" } } } }, "409": { "description": "The note changed since `base_version`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "delete": { "tags": [ "notes" ], "summary": "Delete a note.", "description": "Needs `edit_notes`. It stays in the history and can be restored.", "operationId": "delete_note", "parameters": [ { "name": "id", "in": "path", "description": "Note number", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "base_version", "in": "query", "description": "Refuse with 409 if the note changed since this version.", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/notes/{id}/versions": { "get": { "tags": [ "notes" ], "summary": "A note's history.", "description": "Every version, newest first (at most 500). Needs `view_posts`.", "operationId": "list_note_versions", "parameters": [ { "name": "id", "in": "path", "description": "Note number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNoteVersion" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/pools": { "get": { "tags": [ "pools" ], "summary": "List pools.", "description": "Most recently changed first, 50 per page. Needs `view_posts`.", "operationId": "list_pools", "parameters": [ { "name": "name", "in": "query", "description": "A name prefix, or a pattern with `*` wildcards.", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "`series` or `collection`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "1-based.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "post": { "tags": [ "pools" ], "summary": "Create a pool.", "description": "Needs `edit_pools`.", "operationId": "create_pool", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPool" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPoolWithPosts" } } } }, "422": { "description": "A bad or taken name, or posts that don't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/pools/{id}": { "get": { "tags": [ "pools" ], "summary": "Get a pool.", "description": "Needs `view_posts`.", "operationId": "get_pool", "parameters": [ { "name": "id", "in": "path", "description": "Pool number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPoolWithPosts" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "put": { "tags": [ "pools" ], "summary": "Change a pool.", "description": "Needs `edit_pools`. Fields left out stay as they are.", "operationId": "update_pool", "parameters": [ { "name": "id", "in": "path", "description": "Pool number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolChanges" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPoolWithPosts" } } } }, "409": { "description": "The pool changed since `base_version`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "delete": { "tags": [ "pools" ], "summary": "Delete a pool.", "description": "Needs `delete_posts`; logged. It can be restored.", "operationId": "delete_pool", "parameters": [ { "name": "id", "in": "path", "description": "Pool number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/pools/{id}/posts": { "post": { "tags": [ "pools" ], "summary": "Add a post to the end of a pool.", "description": "Needs `edit_pools`.", "operationId": "add_pool_post", "parameters": [ { "name": "id", "in": "path", "description": "Pool number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolPost" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPoolWithPosts" } } } }, "422": { "description": "Already in the pool, deleted, or the pool is full", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/pools/{id}/restore": { "post": { "tags": [ "pools" ], "summary": "Restore a deleted pool.", "description": "Needs `delete_posts`; logged.", "operationId": "restore_pool", "parameters": [ { "name": "id", "in": "path", "description": "Pool number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/pools/{id}/versions": { "get": { "tags": [ "pools" ], "summary": "A pool's history.", "description": "Every version, newest first (at most 500). Needs `view_posts`.", "operationId": "list_pool_versions", "parameters": [ { "name": "id", "in": "path", "description": "Pool number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiPoolVersion" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts": { "get": { "tags": [ "posts" ], "summary": "Search posts.", "description": "Uses the same syntax as the site (see the search help). Blacklists\naren't applied: clients filter as they like. Needs `view_posts`.", "operationId": "search_posts", "parameters": [ { "name": "tags", "in": "query", "description": "A search, written as in the site's search box (`cat -dog\nrating:g order:score`).", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "A page number, or a cursor from a previous response's `next` or\n`previous`. Cursors keep working however deep the results go;\nnumbered pages stop at the site's limit.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Posts per page, up to the site's maximum. Defaults to the site's\npage size.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPage" } } } }, "400": { "description": "The search or page isn't valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "401": { "description": "The site is private: authenticate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "post": { "tags": [ "posts" ], "summary": "Upload a post.", "description": "Needs `upload`. The post is `pending` when the site reviews uploads and\nyou lack `upload_without_approval`. Thumbnails are made in the\nbackground: `file.processed` turns true when they're ready.", "operationId": "upload_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "headers": { "Location": { "schema": { "type": "string" }, "description": "The new post" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPost" } } } }, "409": { "description": "The file was already uploaded; `post_id` names that post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "413": { "description": "The request is larger than the site allows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "A field or the file isn't acceptable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}": { "get": { "tags": [ "posts" ], "summary": "Get a post.", "description": "Needs `view_posts`. Pending posts are visible to their uploader and to\nmoderators, deleted ones only to moderators.", "operationId": "get_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPost" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "patch": { "tags": [ "posts" ], "summary": "Edit a post.", "description": "Needs `edit_posts`. Tag changes are applied to the post's tags as they\nare when the change is saved, so edits made meanwhile by others are\nkept. Every change is recorded in the post's history.", "operationId": "update_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostChanges" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPost" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "A change isn't acceptable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/approve": { "post": { "tags": [ "moderation" ], "summary": "Approve a pending post.", "description": "Needs `approve_posts`.", "operationId": "approve_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPost" } } } }, "400": { "description": "The post isn't pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/comments": { "post": { "tags": [ "comments" ], "summary": "Comment on a post.", "description": "Needs `comment`. Rate limited; deleted posts can't be commented on.", "operationId": "create_comment", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentText" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiComment" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "The text is empty or too long, or the post is deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/delete": { "post": { "tags": [ "moderation" ], "summary": "Delete a post.", "description": "Needs `delete_posts`. Deleted posts stay visible to moderators and can\nbe restored; open flags on the post are upheld.", "operationId": "delete_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPost" } } } }, "400": { "description": "The post is already deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/favorite": { "put": { "tags": [ "posts" ], "summary": "Favorite a post.", "description": "Needs `favorite`. Favoriting twice is harmless.", "operationId": "favorite_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reactions" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "delete": { "tags": [ "posts" ], "summary": "Unfavorite a post.", "description": "Needs `favorite`.", "operationId": "unfavorite_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reactions" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/flags": { "post": { "tags": [ "posts" ], "summary": "Flag a post for deletion.", "description": "Needs `flag`. Moderators review flags; a post can't have two open flags\nfrom the same user.", "operationId": "flag_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewFlag" } } }, "required": true }, "responses": { "204": { "description": "Flagged" }, "400": { "description": "No reason, or the post can't be flagged now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/flags/dismiss": { "post": { "tags": [ "moderation" ], "summary": "Dismiss a post's flags.", "description": "Needs `approve_posts`. The post stays, and is no longer `flagged`.", "operationId": "dismiss_flags", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dismissed" } } } }, "400": { "description": "The post has no open flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/notes": { "get": { "tags": [ "notes" ], "summary": "A post's notes.", "description": "Oldest first. Needs `view_posts`.", "operationId": "list_post_notes", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_deleted", "in": "query", "description": "Deleted notes too (for those who may edit notes).", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiNote" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } }, "post": { "tags": [ "notes" ], "summary": "Add a note to a post.", "description": "Needs `edit_notes`. Not on deleted posts; at most 500 per post.", "operationId": "create_note", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewNote" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiNote" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Empty text, or a box outside the image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/purge": { "post": { "tags": [ "moderation" ], "summary": "Purge a deleted post.", "description": "Needs `purge_posts`. The post, its files and its history are removed\nfor good by a background job shortly after.", "operationId": "purge_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "The purge is queued" }, "400": { "description": "Only deleted posts can be purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/reject": { "post": { "tags": [ "moderation" ], "summary": "Reject a pending post.", "description": "Needs `approve_posts`. The post is deleted.", "operationId": "reject_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPost" } } } }, "400": { "description": "The post isn't pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/restore": { "post": { "tags": [ "moderation" ], "summary": "Restore a deleted post.", "description": "Needs `delete_posts`.", "operationId": "restore_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPost" } } } }, "400": { "description": "The post isn't deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/versions": { "get": { "tags": [ "posts" ], "summary": "List a post's history.", "description": "Newest first, at most 500 versions. Needs `view_posts`.", "operationId": "list_post_versions", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiVersion" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/posts/{id}/vote": { "put": { "tags": [ "posts" ], "summary": "Vote on a post.", "description": "Needs `vote`. A new vote replaces your earlier one.", "operationId": "vote_on_post", "parameters": [ { "name": "id", "in": "path", "description": "Post number", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vote" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reactions" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/saved-searches": { "get": { "tags": [ "users" ], "summary": "Your saved searches.", "description": "By query. Search them together with `search:all` or `search: