openapi-directory
Version:
Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS
1 lines • 200 kB
JSON
{"openapi":"3.0.0","servers":[{"description":"Live Test Server (live data - latest nightly version)","url":"https://peertube2.cpy.re"},{"description":"Live Test Server (live data - latest RC version)","url":"https://peertube3.cpy.re"},{"description":"Live Test Server (live data - stable version)","url":"https://peertube.cpy.re"}],"info":{"contact":{"name":"PeerTube Community","url":"https://joinpeertube.org"},"description":"The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite\nHTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with\n[openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)\nwhich generates a client SDK in the language of your choice - we generate some client SDKs automatically:\n\n- [Python](https://framagit.org/framasoft/peertube/clients/python)\n- [Go](https://framagit.org/framasoft/peertube/clients/go)\n- [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)\n\nSee the [REST API quick start](https://docs.joinpeertube.org/api/rest-getting-started) for a few\nexamples of using the PeerTube API.\n\n# Authentication\n\nWhen you sign up for an account on a PeerTube instance, you are given the possibility\nto generate sessions on it, and authenticate there using an access token. Only __one\naccess token can currently be used at a time__.\n\n## Roles\n\nAccounts are given permissions based on their role. There are three roles on\nPeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin/managing-users#roles) for a detail of their permissions.\n\n# Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure\nof the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.\n\n```\nHTTP 1.1 404 Not Found\nContent-Type: application/problem+json; charset=utf-8\n\n{\n \"detail\": \"Video not found\",\n \"docs\": \"https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo\",\n \"status\": 404,\n \"title\": \"Not Found\",\n \"type\": \"about:blank\"\n}\n```\n\nWe provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),\nbut it is still optional. Types are used to disambiguate errors that bear the same status code\nand are non-obvious:\n\n```\nHTTP 1.1 403 Forbidden\nContent-Type: application/problem+json; charset=utf-8\n\n{\n \"detail\": \"Cannot get this video regarding follow constraints\",\n \"docs\": \"https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo\",\n \"status\": 403,\n \"title\": \"Forbidden\",\n \"type\": \"https://docs.joinpeertube.org/api/rest-reference.html#section/Errors/does_not_respect_follow_constraints\"\n}\n```\n\nHere a 403 error could otherwise mean that the video is private or blocklisted.\n\n### Validation errors\n\nEach parameter is evaluated on its own against a set of rules before the route validator\nproceeds with potential testing involving parameter combinations. Errors coming from validation\nerrors appear earlier and benefit from a more detailed error description:\n\n```\nHTTP 1.1 400 Bad Request\nContent-Type: application/problem+json; charset=utf-8\n\n{\n \"detail\": \"Incorrect request parameters: id\",\n \"docs\": \"https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo\",\n \"instance\": \"/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180\",\n \"invalid-params\": {\n \"id\": {\n \"location\": \"params\",\n \"msg\": \"Invalid value\",\n \"param\": \"id\",\n \"value\": \"9c9de5e8-0a1e-484a-b099-e80766180\"\n }\n },\n \"status\": 400,\n \"title\": \"Bad Request\",\n \"type\": \"about:blank\"\n}\n```\n\nWhere `id` is the name of the field concerned by the error, within the route definition.\n`invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and\n`invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`\nis about.\n\n### Deprecated error fields\n\nSome fields could be included with previous versions. They are still included but their use is deprecated:\n- `error`: superseded by `detail`\n- `code`: superseded by `type` (which is now an URI)\n\n# Rate limits\n\nWe are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:\n\n| Endpoint (prefix: `/api/v1`) | Calls | Time frame |\n|------------------------------|---------------|--------------|\n| `/*` | 50 | 10 seconds |\n| `POST /users/token` | 15 | 5 minutes |\n| `POST /users/register` | 2<sup>*</sup> | 5 minutes |\n| `POST /users/ask-send-verify-email` | 3 | 5 minutes |\n\nDepending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service\nlimit is announced by a `429 Too Many Requests` status code.\n\nYou can get details about the current state of your rate limit by reading the\nfollowing headers:\n\n| Header | Description |\n|-------------------------|------------------------------------------------------------|\n| `X-RateLimit-Limit` | Number of max requests allowed in the current time period |\n| `X-RateLimit-Remaining` | Number of remaining requests in the current time period |\n| `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |\n| `Retry-After` | Seconds to delay after the first `429` is received |\n\n# CORS\n\nThis API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),\nallowing cross-domain communication from the browser for some routes:\n\n| Endpoint |\n|------------------------- ---|\n| `/api/*` |\n| `/download/*` |\n| `/lazy-static/*` |\n| `/.well-known/webfinger` |\n\nIn addition, all routes serving ActivityPub are CORS-enabled for all origins.\n","license":{"name":"AGPLv3.0","url":"https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE"},"title":"PeerTube","version":"5.1.0","x-apisguru-categories":["social"],"x-logo":{"altText":"PeerTube Project Homepage","url":"https://joinpeertube.org/img/brand.png"},"x-origin":[{"converter":{"url":"https://github.com/mermade/oas-kit","version":"7.0.4"},"format":"openapi","url":"https://raw.githubusercontent.com/Chocobozzz/PeerTube/develop/support/doc/api/openapi.yaml","version":"3.0"}],"x-providerName":"cpy.re","x-serviceName":"peertube"},"externalDocs":{"url":"https://docs.joinpeertube.org/api/rest-reference.html"},"tags":[{"description":"As a visitor, you can use this API to open an account (if registrations are open on\nthat PeerTube instance). As an admin, you should use the dedicated [User creation\nAPI](#operation/addUser) instead.\n","name":"Register"},{"description":"Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.\n","name":"Session","x-displayName":"Login/Logout"},{"description":"Accounts encompass remote accounts discovered across the federation, and correspond to the main Actor, along with video channels a user can create, which are also Actors.\nWhen a comment is posted, it is done with your Account's Actor.\n","name":"Accounts"},{"description":"Using some features of PeerTube require authentication, for which User provide different levels of permission as well as associated user information. Each user has a corresponding local Account for federation.\n","name":"Users"},{"description":"Operations related to your own User, when logged-in.\n","name":"My User"},{"description":"Operations related to your subscriptions to video channels, their new videos, and how to keep up to date with their latest publications!\n","name":"My Subscriptions"},{"description":"Operations related to your watch history.\n","name":"My History"},{"description":"Notifications following new videos, follows or reports. They allow you to keep track of the interactions and overall important information that concerns you. You MAY set per-notification type delivery preference, to receive the info either by mail, by in-browser notification or both.\n","name":"My Notifications"},{"description":"Each server exposes public information regarding supported videos and options.\n","name":"Config"},{"description":"Jobs are long-running tasks enqueued and processed by the instance itself. No additional worker registration is currently available.\n","name":"Job"},{"description":"Managing servers which the instance interacts with is crucial to the concept of federation in PeerTube and external video indexation. The PeerTube server then deals with inter-server ActivityPub operations and propagates information across its social graph by posting activities to actors' inbox endpoints.\n","externalDocs":{"url":"https://docs.joinpeertube.org/admin/following-instances#instances-follows"},"name":"Instance Follows"},{"description":"Redundancy is part of the inter-server solidarity that PeerTube fosters. Manage the list of instances you wish to help by seeding their videos according to the policy of video selection of your choice. Note that you have a similar functionality to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).\n","externalDocs":{"url":"https://docs.joinpeertube.org/admin/following-instances#instances-redundancy"},"name":"Instance Redundancy"},{"description":"Managing plugins installed from a local path or from NPM, or search for new ones.\n","externalDocs":{"url":"https://docs.joinpeertube.org/api/plugins"},"name":"Plugins"},{"description":"Abuses deal with reports of local or remote videos/comments/accounts alike.\n","name":"Abuses"},{"description":"Operations dealing with listing, uploading, fetching or modifying videos.\n","name":"Video"},{"description":"Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.\n\n### Upload\n\n- [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request\n- [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks\n\nYou can upload videos more reliably by using the resumable variant. Its protocol lets\nyou resume an upload operation after a network interruption or other transmission failure,\nsaving time and bandwidth in the event of network failures.\n\nFavor using resumable uploads in any of the following cases:\n- You are transferring large files\n- The likelihood of a network interruption is high\n- Uploads are originating from a device with a low-bandwidth or unstable Internet connection,\n such as a mobile device\n\n### Import\n\n- _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)\n- _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file\n- _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file\n\nThe import function is practical when the desired video/audio is available online. It makes PeerTube\ndownload it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.\n","name":"Video Upload"},{"description":"Operations dealing with listing, adding and removing video imports.","name":"Video Imports"},{"description":"Operations dealing with synchronizing PeerTube user's channel with channels of other platforms","name":"Channels Sync"},{"description":"Operations dealing with listing, adding and removing closed captions of a video.","name":"Video Captions"},{"description":"Operations dealing with the creation, modification and listing of videos within a channel.","name":"Video Channels"},{"description":"Operations dealing with comments to a video. Comments are organized in threads: adding a comment in response to the video starts a thread, adding a reply to a comment adds it to its root comment thread.\n","name":"Video Comments"},{"description":"Operations dealing with blocking videos (removing them from view and preventing interactions).","name":"Video Blocks"},{"description":"Like/dislike a video.","name":"Video Rates"},{"description":"Operations dealing with playlists of videos. Playlists are bound to users and/or channels.","name":"Video Playlists"},{"description":"Operations on video files","name":"Video Files"},{"description":"Video transcoding related operations","name":"Video Transcoding"},{"description":"Video statistics","name":"Video stats"},{"description":"Server syndication feeds of videos","name":"Video Feeds"},{"description":"The search helps to find _videos_ or _channels_ from within the instance and beyond.\nVideos from other instances federated by the instance (that is, instances\nfollowed by the instance) can be found via keywords and other criteria of\nthe advanced search.\n\nAdministrators can also enable the use of a remote search system, indexing\nvideos and channels not could be not federated by the instance.\n","name":"Search"},{"description":"Get and update the custom homepage","name":"Homepage"},{"description":"PeerTube instances can mirror videos from one another, and help distribute some videos.\n\nFor importing videos as your own, refer to [video imports](#operation/importVideo).\n","name":"Video Mirroring"},{"description":"Statistics\n","name":"Stats"}],"paths":{"/api/v1/abuses":{"get":{"operationId":"getAbuses","parameters":[{"description":"only list the report with this id","in":"query","name":"id","schema":{"type":"integer"}},{"description":"predefined reason the listed reports should contain","in":"query","name":"predefinedReason","schema":{"$ref":"#/components/schemas/PredefinedAbuseReasons"}},{"description":"plain search that will match with video titles, reporter names and more","in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"state","schema":{"$ref":"#/components/schemas/AbuseStateSet"}},{"description":"only list reports of a specific reporter","in":"query","name":"searchReporter","schema":{"type":"string"}},{"description":"only list reports of a specific reportee","in":"query","name":"searchReportee","schema":{"type":"string"}},{"description":"only list reports of a specific video","in":"query","name":"searchVideo","schema":{"type":"string"}},{"description":"only list reports of a specific video channel","in":"query","name":"searchVideoChannel","schema":{"type":"string"}},{"description":"only list deleted or blocklisted videos","in":"query","name":"videoIs","schema":{"enum":["deleted","blacklisted"],"type":"string"}},{"description":"only list account, comment or video reports","in":"query","name":"filter","schema":{"enum":["video","comment","account"],"type":"string"}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/abusesSort"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Abuse"},"type":"array"},"total":{"example":1,"type":"integer"}},"type":"object"}}},"description":"successful operation"}},"security":[{"OAuth2":["admin","moderator"]}],"summary":"List abuses","tags":["Abuses"]},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"account":{"properties":{"id":{"description":"Account id to report","type":"integer"}},"type":"object"},"comment":{"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/id"}],"description":"Comment id to report"}},"type":"object"},"predefinedReasons":{"$ref":"#/components/schemas/PredefinedAbuseReasons"},"reason":{"description":"Reason why the user reports this video","maxLength":3000,"minLength":2,"type":"string"},"video":{"properties":{"endAt":{"description":"Timestamp in the video that marks the ending of the report","format":"seconds","minimum":0,"type":"integer"},"id":{"allOf":[{"$ref":"#/components/schemas/Video/properties/id"}],"description":"Video id to report"},"startAt":{"description":"Timestamp in the video that marks the beginning of the report","format":"seconds","minimum":0,"type":"integer"}},"type":"object"}},"required":["reason"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"abuse":{"properties":{"id":{"$ref":"#/components/schemas/id"}},"type":"object"}},"type":"object"}}},"description":"successful operation"},"400":{"description":"incorrect request parameters"}},"security":[{"OAuth2":[]}],"summary":"Report an abuse","tags":["Abuses"]}},"/api/v1/abuses/{abuseId}":{"delete":{"parameters":[{"$ref":"#/components/parameters/abuseId"}],"responses":{"204":{"description":"successful operation"},"404":{"description":"block not found"}},"security":[{"OAuth2":["admin","moderator"]}],"summary":"Delete an abuse","tags":["Abuses"]},"put":{"parameters":[{"$ref":"#/components/parameters/abuseId"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"moderationComment":{"description":"Update the report comment visible only to the moderation team","maxLength":3000,"minLength":2,"type":"string"},"state":{"$ref":"#/components/schemas/AbuseStateSet"}},"type":"object"}}}},"responses":{"204":{"description":"successful operation"},"404":{"description":"abuse not found"}},"security":[{"OAuth2":["admin","moderator"]}],"summary":"Update an abuse","tags":["Abuses"]}},"/api/v1/abuses/{abuseId}/messages":{"get":{"parameters":[{"$ref":"#/components/parameters/abuseId"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AbuseMessage"},"type":"array"},"total":{"example":1,"type":"integer"}},"type":"object"}}},"description":"successful operation"}},"security":[{"OAuth2":[]}],"summary":"List messages of an abuse","tags":["Abuses"]},"post":{"parameters":[{"$ref":"#/components/parameters/abuseId"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"message":{"description":"Message to send","maxLength":3000,"minLength":2,"type":"string"}},"required":["message"],"type":"object"}}},"required":true},"responses":{"200":{"description":"successful operation"},"400":{"description":"incorrect request parameters"}},"security":[{"OAuth2":[]}],"summary":"Add message to an abuse","tags":["Abuses"]}},"/api/v1/abuses/{abuseId}/messages/{abuseMessageId}":{"delete":{"parameters":[{"$ref":"#/components/parameters/abuseId"},{"$ref":"#/components/parameters/abuseMessageId"}],"responses":{"204":{"description":"successful operation"}},"security":[{"OAuth2":[]}],"summary":"Delete an abuse message","tags":["Abuses"]}},"/api/v1/accounts":{"get":{"operationId":"getAccounts","parameters":[{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Account"},"type":"array"}}},"description":"successful operation"}},"summary":"List accounts","tags":["Accounts"]}},"/api/v1/accounts/{name}":{"get":{"operationId":"getAccount","parameters":[{"$ref":"#/components/parameters/name"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"successful operation"},"404":{"description":"account not found"}},"summary":"Get an account","tags":["Accounts"]}},"/api/v1/accounts/{name}/followers":{"get":{"operationId":"getAccountFollowers","parameters":[{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/followersSort"},{"$ref":"#/components/parameters/search"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Follow"},"type":"array"},"total":{"example":1,"type":"integer"}},"type":"object"}}},"description":"successful operation"}},"security":[{"OAuth2":[]}],"summary":"List followers of an account","tags":["Accounts"]}},"/api/v1/accounts/{name}/ratings":{"get":{"parameters":[{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"},{"description":"Optionally filter which ratings to retrieve","in":"query","name":"rating","required":false,"schema":{"enum":["like","dislike"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/VideoRating"},"type":"array"}}},"description":"successful operation"}},"security":[{"OAuth2":[]}],"summary":"List ratings of an account","tags":["Accounts"]}},"/api/v1/accounts/{name}/video-channel-syncs":{"get":{"parameters":[{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoChannelSyncList"}}},"description":"successful operation"}},"summary":"List the synchronizations of video channels of an account","tags":["Video Channels","Channels Sync","Accounts"]}},"/api/v1/accounts/{name}/video-channels":{"get":{"parameters":[{"$ref":"#/components/parameters/name"},{"description":"include daily view statistics for the last 30 days and total views (only if authentified as the account user)","in":"query","name":"withStats","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoChannelList"}}},"description":"successful operation"}},"summary":"List video channels of an account","tags":["Video Channels","Accounts"]}},"/api/v1/accounts/{name}/video-playlists":{"get":{"parameters":[{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/search"},{"$ref":"#/components/parameters/videoPlaylistType"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/VideoPlaylist"},"type":"array"},"total":{"example":1,"type":"integer"}},"type":"object"}}},"description":"successful operation"}},"summary":"List playlists of an account","tags":["Video Playlists","Accounts"]}},"/api/v1/accounts/{name}/videos":{"get":{"operationId":"getAccountVideos","parameters":[{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/categoryOneOf"},{"$ref":"#/components/parameters/isLive"},{"$ref":"#/components/parameters/tagsOneOf"},{"$ref":"#/components/parameters/tagsAllOf"},{"$ref":"#/components/parameters/licenceOneOf"},{"$ref":"#/components/parameters/languageOneOf"},{"$ref":"#/components/parameters/nsfw"},{"$ref":"#/components/parameters/isLocal"},{"$ref":"#/components/parameters/include"},{"$ref":"#/components/parameters/privacyOneOf"},{"$ref":"#/components/parameters/hasHLSFiles"},{"$ref":"#/components/parameters/hasWebtorrentFiles"},{"$ref":"#/components/parameters/skipCount"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/videosSort"},{"$ref":"#/components/parameters/excludeAlreadyWatched"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoListResponse"}}},"description":"successful operation"}},"summary":"List videos of an account","tags":["Accounts","Video"],"x-codeSamples":[{"lang":"JavaScript","source":"fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')\n.then(function(response) {\n return response.json()\n}).then(function(data) {\n console.log(data)\n})\n"},{"lang":"Shell","source":"## DEPENDENCIES: jq\ncurl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq\n"},{"lang":"Ruby","source":"require 'net/http'\nrequire 'json'\n\nuri = URI.parse(\"https://peertube2.cpy.re/api/v1/accounts/{name}/videos\")\n\nhttp = Net::HTTP.new(uri.host, uri.port)\nhttp.use_ssl = true\n\nresponse = http.get(uri.request_uri)\n\nputs JSON.parse(response.read_body)\n"},{"lang":"Python","source":"import requests\n\nr = requests.get(\"https://peertube2.cpy.re/api/v1//accounts/{name}/videos\")\njson = r.json()\n\nprint(json)\n"}]}},"/api/v1/blocklist/status":{"get":{"parameters":[{"description":"Check if these accounts are blocked","example":["goofy@example.com","donald@example.com"],"in":"query","name":"accounts","schema":{"items":{"type":"string"},"type":"array"}},{"description":"Check if these hosts are blocked","example":["example.com"],"in":"query","name":"hosts","schema":{"items":{"type":"string"},"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockStatus"}}},"description":"successful operation"}},"summary":"Get block status of accounts/hosts","tags":["Account Blocks","Server Blocks"]}},"/api/v1/config":{"get":{"operationId":"getConfig","responses":{"200":{"content":{"application/json":{"examples":{"nightly":{"externalValue":"https://peertube2.cpy.re/api/v1/config"}},"schema":{"$ref":"#/components/schemas/ServerConfig"}}},"description":"successful operation"}},"summary":"Get instance public configuration","tags":["Config"]}},"/api/v1/config/about":{"get":{"operationId":"getAbout","responses":{"200":{"content":{"application/json":{"examples":{"nightly":{"externalValue":"https://peertube2.cpy.re/api/v1/config/about"}},"schema":{"$ref":"#/components/schemas/ServerConfigAbout"}}},"description":"successful operation"}},"summary":"Get instance \"About\" information","tags":["Config"]}},"/api/v1/config/custom":{"delete":{"operationId":"delCustomConfig","responses":{"200":{"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"Delete instance runtime configuration","tags":["Config"]},"get":{"operationId":"getCustomConfig","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerConfigCustom"}}},"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"Get instance runtime configuration","tags":["Config"]},"put":{"operationId":"putCustomConfig","responses":{"200":{"description":"successful operation"},"400":{"description":"Arises when:\n - the emailer is disabled and the instance is open to registrations\n - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled\n","x-summary":"field inconsistencies"}},"security":[{"OAuth2":["admin"]}],"summary":"Set instance runtime configuration","tags":["Config"]}},"/api/v1/custom-pages/homepage/instance":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomHomepage"}}},"description":"successful operation"},"404":{"description":"No homepage set"}},"summary":"Get instance custom homepage","tags":["Homepage"]},"put":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"content":{"description":"content of the homepage, that will be injected in the client","type":"string"}},"type":"object"}}}},"responses":{"204":{"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"Set instance custom homepage","tags":["Homepage"]}},"/api/v1/jobs/pause":{"post":{"responses":{"204":{"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"Pause job queue","tags":["Job"]}},"/api/v1/jobs/resume":{"post":{"responses":{"204":{"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"Resume job queue","tags":["Job"]}},"/api/v1/jobs/{state}":{"get":{"operationId":"getJobs","parameters":[{"description":"The state of the job ('' for for no filter)","in":"path","name":"state","required":true,"schema":{"enum":["","active","completed","failed","waiting","delayed"],"type":"string"}},{"$ref":"#/components/parameters/jobType"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Job"},"maxItems":100,"type":"array"},"total":{"example":1,"type":"integer"}},"type":"object"}}},"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"List instance jobs","tags":["Job"]}},"/api/v1/metrics/playback":{"post":{"description":"These metrics are exposed by OpenTelemetry metrics exporter if enabled.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaybackMetricCreate"}}}},"responses":{"204":{"description":"successful operation"}},"summary":"Create playback metrics","tags":["Stats"]}},"/api/v1/oauth-clients/local":{"get":{"description":"You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).","operationId":"getOAuthClient","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClient"}}},"description":"successful operation","links":{"UseOAuthClientToLogin":{"operationId":"getOAuthToken","parameters":{"client_id":"$response.body#/client_id","client_secret":"$response.body#/client_secret"}}}}},"summary":"Login prerequisite","tags":["Session"],"x-codeSamples":[{"lang":"Shell","source":"API=\"https://peertube2.cpy.re/api/v1\"\n\n## AUTH\ncurl -s \"$API/oauth-clients/local\"\n"}]}},"/api/v1/plugins":{"get":{"operationId":"getPlugins","parameters":[{"in":"query","name":"pluginType","schema":{"type":"integer"}},{"in":"query","name":"uninstalled","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginResponse"}}},"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"List plugins","tags":["Plugins"]}},"/api/v1/plugins/available":{"get":{"operationId":"getAvailablePlugins","parameters":[{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"pluginType","schema":{"type":"integer"}},{"in":"query","name":"currentPeerTubeEngine","schema":{"type":"string"}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginResponse"}}},"description":"successful operation"},"503":{"description":"plugin index unavailable"}},"security":[{"OAuth2":["admin"]}],"summary":"List available plugins","tags":["Plugins"]}},"/api/v1/plugins/install":{"post":{"operationId":"addPlugin","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"additionalProperties":false,"properties":{"npmName":{"example":"peertube-plugin-auth-ldap","type":"string"}},"required":["npmName"],"type":"object"},{"additionalProperties":false,"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"}]}}}},"responses":{"204":{"description":"successful operation"},"400":{"description":"should have either `npmName` or `path` set"}},"security":[{"OAuth2":["admin"]}],"summary":"Install a plugin","tags":["Plugins"]}},"/api/v1/plugins/uninstall":{"post":{"operationId":"uninstallPlugin","requestBody":{"content":{"application/json":{"schema":{"properties":{"npmName":{"description":"name of the plugin/theme in its package.json","example":"peertube-plugin-auth-ldap","type":"string"}},"required":["npmName"],"type":"object"}}}},"responses":{"204":{"description":"successful operation"},"404":{"description":"existing plugin not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Uninstall a plugin","tags":["Plugins"]}},"/api/v1/plugins/update":{"post":{"operationId":"updatePlugin","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"additionalProperties":false,"properties":{"npmName":{"example":"peertube-plugin-auth-ldap","type":"string"}},"required":["npmName"],"type":"object"},{"additionalProperties":false,"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"}]}}}},"responses":{"204":{"description":"successful operation"},"400":{"description":"should have either `npmName` or `path` set"},"404":{"description":"existing plugin not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Update a plugin","tags":["Plugins"]}},"/api/v1/plugins/{npmName}":{"get":{"operationId":"getPlugin","parameters":[{"$ref":"#/components/parameters/npmName"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plugin"}}},"description":"successful operation"},"404":{"description":"plugin not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Get a plugin","tags":["Plugins"]}},"/api/v1/plugins/{npmName}/public-settings":{"get":{"parameters":[{"$ref":"#/components/parameters/npmName"}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"successful operation"},"404":{"description":"plugin not found"}},"summary":"Get a plugin's public settings","tags":["Plugins"]}},"/api/v1/plugins/{npmName}/registered-settings":{"get":{"parameters":[{"$ref":"#/components/parameters/npmName"}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"successful operation"},"404":{"description":"plugin not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Get a plugin's registered settings","tags":["Plugins"]}},"/api/v1/plugins/{npmName}/settings":{"put":{"parameters":[{"$ref":"#/components/parameters/npmName"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"settings":{"additionalProperties":true,"type":"object"}},"type":"object"}}}},"responses":{"204":{"description":"successful operation"},"404":{"description":"plugin not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Set a plugin's settings","tags":["Plugins"]}},"/api/v1/search/video-channels":{"get":{"callbacks":{"searchTarget === search-index":{"$ref":"#/components/callbacks/searchIndex"}},"operationId":"searchChannels","parameters":[{"description":"String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete channel information and interact with it.\n","in":"query","name":"search","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/searchTarget"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoChannelList"}}},"description":"successful operation"},"500":{"description":"search index unavailable"}},"summary":"Search channels","tags":["Search"]}},"/api/v1/search/video-playlists":{"get":{"callbacks":{"searchTarget === search-index":{"$ref":"#/components/callbacks/searchIndex"}},"operationId":"searchPlaylists","parameters":[{"description":"String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete playlist information and interact with it.\n","in":"query","name":"search","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/searchTarget"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/VideoPlaylist"},"type":"array"},"total":{"example":1,"type":"integer"}},"type":"object"}}},"description":"successful operation"},"500":{"description":"search index unavailable"}},"summary":"Search playlists","tags":["Search"]}},"/api/v1/search/videos":{"get":{"callbacks":{"searchTarget === search-index":{"$ref":"#/components/callbacks/searchIndex"}},"operationId":"searchVideos","parameters":[{"allowEmptyValue":false,"description":"String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete video information and interact with it.\n","in":"query","name":"search","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/categoryOneOf"},{"$ref":"#/components/parameters/isLive"},{"$ref":"#/components/parameters/tagsOneOf"},{"$ref":"#/components/parameters/tagsAllOf"},{"$ref":"#/components/parameters/licenceOneOf"},{"$ref":"#/components/parameters/languageOneOf"},{"$ref":"#/components/parameters/nsfw"},{"$ref":"#/components/parameters/isLocal"},{"$ref":"#/components/parameters/include"},{"$ref":"#/components/parameters/privacyOneOf"},{"$ref":"#/components/parameters/uuids"},{"$ref":"#/components/parameters/hasHLSFiles"},{"$ref":"#/components/parameters/hasWebtorrentFiles"},{"$ref":"#/components/parameters/skipCount"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/searchTarget"},{"$ref":"#/components/parameters/videosSearchSort"},{"$ref":"#/components/parameters/excludeAlreadyWatched"},{"description":"Get videos that are published after this date","in":"query","name":"startDate","schema":{"format":"date-time","type":"string"}},{"description":"Get videos that are published before this date","in":"query","name":"endDate","schema":{"format":"date-time","type":"string"}},{"description":"Get videos that are originally published after this date","in":"query","name":"originallyPublishedStartDate","schema":{"format":"date-time","type":"string"}},{"description":"Get videos that are originally published before this date","in":"query","name":"originallyPublishedEndDate","schema":{"format":"date-time","type":"string"}},{"description":"Get videos that have this minimum duration","in":"query","name":"durationMin","schema":{"type":"integer"}},{"description":"Get videos that have this maximum duration","in":"query","name":"durationMax","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoListResponse"}}},"description":"successful operation"},"500":{"description":"search index unavailable"}},"summary":"Search videos","tags":["Search"]}},"/api/v1/server/audit-logs":{"get":{"operationId":"getInstanceAuditLogs","responses":{"200":{"content":{"application/json":{"schema":{"items":{"type":"string"},"type":"array"}}},"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"Get instance audit logs","tags":["Logs"]}},"/api/v1/server/blocklist/accounts":{"get":{"parameters":[{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"List account blocks","tags":["Account Blocks"]},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"accountName":{"description":"account to block, in the form `username@domain`","example":"chocobozzz@example.org","type":"string"}},"required":["accountName"],"type":"object"}}}},"responses":{"200":{"description":"successful operation"},"409":{"description":"self-blocking forbidden"}},"security":[{"OAuth2":["admin"]}],"summary":"Block an account","tags":["Account Blocks"]}},"/api/v1/server/blocklist/accounts/{accountName}":{"delete":{"parameters":[{"description":"account to unblock, in the form `username@domain`","in":"path","name":"accountName","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"successful operation"},"404":{"description":"account or account block does not exist"}},"security":[{"OAuth2":["admin"]}],"summary":"Unblock an account by its handle","tags":["Account Blocks"]}},"/api/v1/server/blocklist/servers":{"get":{"parameters":[{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"List server blocks","tags":["Server Blocks"]},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"host":{"description":"server domain to block","format":"hostname","type":"string"}},"required":["host"],"type":"object"}}}},"responses":{"204":{"description":"successful operation"},"409":{"description":"self-blocking forbidden"}},"security":[{"OAuth2":["admin"]}],"summary":"Block a server","tags":["Server Blocks"]}},"/api/v1/server/blocklist/servers/{host}":{"delete":{"parameters":[{"description":"server domain to unblock","in":"path","name":"host","required":true,"schema":{"format":"hostname","type":"string"}}],"responses":{"204":{"description":"successful operation"},"404":{"description":"account block does not exist"}},"security":[{"OAuth2":["admin"]}],"summary":"Unblock a server by its domain","tags":["Server Blocks"]}},"/api/v1/server/followers":{"get":{"parameters":[{"$ref":"#/components/parameters/followState"},{"$ref":"#/components/parameters/actorType"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Follow"},"type":"array"},"total":{"example":1,"type":"integer"}},"type":"object"}}},"description":"successful operation"}},"summary":"List instances following the server","tags":["Instance Follows"]}},"/api/v1/server/followers/{nameWithHost}":{"delete":{"parameters":[{"description":"The remote actor handle to remove from your followers","in":"path","name":"nameWithHost","required":true,"schema":{"format":"email","type":"string"}}],"responses":{"204":{"description":"successful operation"},"404":{"description":"follower not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Remove or reject a follower to your server","tags":["Instance Follows"]}},"/api/v1/server/followers/{nameWithHost}/accept":{"post":{"parameters":[{"description":"The remote actor handle to remove from your followers","in":"path","name":"nameWithHost","required":true,"schema":{"format":"email","type":"string"}}],"responses":{"204":{"description":"successful operation"},"404":{"description":"follower not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Accept a pending follower to your server","tags":["Instance Follows"]}},"/api/v1/server/followers/{nameWithHost}/reject":{"post":{"parameters":[{"description":"The remote actor handle to remove from your followers","in":"path","name":"nameWithHost","required":true,"schema":{"format":"email","type":"string"}}],"responses":{"204":{"description":"successful operation"},"404":{"description":"follower not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Reject a pending follower to your server","tags":["Instance Follows"]}},"/api/v1/server/following":{"get":{"parameters":[{"$ref":"#/components/parameters/followState"},{"$ref":"#/components/parameters/actorType"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Follow"},"type":"array"},"total":{"example":1,"type":"integer"}},"type":"object"}}},"description":"successful operation"}},"summary":"List instances followed by the server","tags":["Instance Follows"]},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"handles":{"items":{"type":"string"},"type":"array","uniqueItems":true},"hosts":{"items":{"format":"hostname","type":"string"},"type":"array","uniqueItems":true}},"type":"object"}}}},"responses":{"204":{"description":"successful operation"},"500":{"description":"cannot follow a non-HTTPS server"}},"security":[{"OAuth2":["admin"]}],"summary":"Follow a list of actors (PeerTube instance, channel or account)","tags":["Instance Follows"]}},"/api/v1/server/following/{hostOrHandle}":{"delete":{"parameters":[{"description":"The hostOrHandle to unfollow","in":"path","name":"hostOrHandle","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"successful operation"},"404":{"description":"host or handle not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Unfollow an actor (PeerTube instance, channel or account)","tags":["Instance Follows"]}},"/api/v1/server/logs":{"get":{"operationId":"getInstanceLogs","responses":{"200":{"content":{"application/json":{"schema":{"items":{"type":"string"},"type":"array"}}},"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"Get instance logs","tags":["Logs"]}},"/api/v1/server/logs/client":{"post":{"operationId":"sendClientLog","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendClientLog"}}}},"responses":{"204":{"description":"successful operation"}},"summary":"Send client log","tags":["Logs"]}},"/api/v1/server/redundancy/videos":{"get":{"operationId":"getMirroredVideos","parameters":[{"description":"direction of the mirror","in":"query","name":"target","required":true,"schema":{"enum":["my-videos","remote-videos"],"type":"string"}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/videoRedundanciesSort"}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/VideoRedundancy"},"type":"array"}}},"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"List videos being mirrored","tags":["Video Mirroring"]},"post":{"operationId":"putMirroredVideo","requestBody":{"content":{"application/json":{"schema":{"properties":{"videoId":{"$ref":"#/components/schemas/Video/properties/id"}},"required":["videoId"],"type":"object"}}}},"responses":{"204":{"description":"successful operation"},"400":{"description":"cannot mirror a local video"},"404":{"description":"video does not exist"},"409":{"description":"video is already mirrored"}},"security":[{"OAuth2":["admin"]}],"summary":"Mirror a video","tags":["Video Mirroring"]}},"/api/v1/server/redundancy/videos/{redundancyId}":{"delete":{"operationId":"delMirroredVideo","parameters":[{"description":"id of an existing redundancy on a video","in":"path","name":"redundancyId","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"successful operation"},"404":{"description":"video redundancy not found"}},"security":[{"OAuth2":["admin"]}],"summary":"Delete a mirror done on a video","tags":["Video Mirroring"]}},"/api/v1/server/redundancy/{host}":{"put":{"parameters":[{"description":"server domain to mirror","in":"path","name":"host","required":true,"schema":{"format":"hostname","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"redundancyAllowed":{"description":"allow mirroring of the host's local videos","type":"boolean"}},"required":["redundancyAllowed"],"type":"object"}}}},"responses":{"204":{"description":"successful operation"},"404":{"description":"server is not already known"}},"security":[{"OAuth2":["admin"]}],"summary":"Update a server redundancy policy","tags":["Instance Redundancy"]}},"/api/v1/server/stats":{"get":{"description":"Get instance public statistics. This endpoint is cached.","operationId":"getInstanceStats","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerStats"}}},"description":"successful operation"}},"summary":"Get instance stats","tags":["Stats"]}},"/api/v1/users":{"get":{"operationId":"getUsers","parameters":[{"$ref":"#/components/parameters/usersSearch"},{"$ref":"#/components/parameters/usersBlocked"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/count"},{"$ref":"#/components/parameters/usersSort"}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/User"},"type":"array"}}},"description":"successful operation"}},"security":[{"OAuth2":["admin"]}],"summary":"List users","tags":["Users"]},"post":{"operationId":"addUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddUser"}}},"description":"If the smtp server is configured, you can leave the password empty and an email will be sent\nasking the user to set it first.\n","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddUserResponse"}}},"description":"user created","links":{"DelUser":{"operationId":"delUser","parameters":{"id":"$response.body#/user/id"}},"GetUser":{"operationId":"getUser","parameters":{"id":"$response.body#/user/id"}},"PutUser":{"operationId":"putUser","parameters":{"id":"$response.body#/user/id"}}}},"403":{"description":"insufficient authority to create an admin or moderator"}},"security":[{"OAuth2":["admin"]}],"summary":"Create a user","tags":["Users"]}},"/api/v1/users/ask-send-verify-email":{"post":{"operationId":"resendEmailToVerifyUser","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"description":"User email","type":"string"}},"required":["email"],"type":"object"}}}},"responses":{"204":{"description":"successful operation"}},"summary":"Resend user verification link","tags":["Users","Register"]}},"/api/v1/users/me":{"get":{"operationId":"getUserInfo","responses":{"200":{"content":{"app