openapi: 3.0.1 info: title: Hangar API description: |- This page describes the format for the current Hangar REST API as well as general usage guidelines.
Note that all routes **not** listed here should be considered **internal**, and can change at a moment's notice. **Do not use them**. ## Authentication and Authorization There are two ways to consume the API: Authenticated or anonymous. ### Anonymous When using anonymous authentication, you only have access to public information, but you don't need to worry about creating and storing an API key or handing JWTs. ### Authenticated If you need access to non-public content or actions, you need to create and use API keys. These can be created by going to the API keys page via the profile dropdown or by going to your user page and clicking on the key icon. API keys allow you to impersonate yourself, so they should be handled like passwords. **Do not share them with anyone else!** #### Getting and Using a JWT Once you have an API key, you need to authenticate yourself: Send a `POST` request with your API key identifier to `/api/v1/authenticate?apiKey=yourKey`. The response will contain your JWT as well as an expiration time. Put this JWT into the `Authorization` header of every request and make sure to request a new JWT after the expiration time has passed. Please also set a meaningful `User-Agent` header. This allows us to better identify loads and needs for potentially new endpoints. ## Misc ### Date Formats Standard ISO types. Where possible, we use the [OpenAPI format modifier](https://swagger.io/docs/specification/data-models/data-types/#format). ### Rate Limits and Caching The default rate limit is set at 20 requests every 5 seconds with an initial overdraft for extra leniency. Individual endpoints, such as version creation, may have stricter rate limiting. If applicable, always cache responses. The Hangar API itself is cached by CloudFlare and internally. version: "1.0" servers: - url: https://hangar.papermc.io description: Generated server url paths: /api/v1/projects/{slug}/upload: post: tags: - Versions summary: Creates a new version and returns parts of its metadata description: |- Creates a new version for a project. Requires the `create_version` permission in the project or owning organization. Make sure you provide the contents of this request as multipart/form-data. You can find a simple example implementation written in Java here: https://gist.github.com/kennytv/a227d82249f54e0ad35005330256fee2 operationId: uploadVersion parameters: - name: slug in: path description: The slug of the project to return versions for required: true schema: type: string requestBody: content: multipart/form-data: schema: required: - versionUpload type: object properties: files: type: array description: "The version files in order of selected platforms,\ \ if any" items: type: string format: binary versionUpload: $ref: '#/components/schemas/VersionUpload' encoding: versionUpload: contentType: application/json responses: "201": description: Ok content: application/json: schema: $ref: '#/components/schemas/UploadedVersion' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/UploadedVersion' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/UploadedVersion' security: - HangarAuth: - create_version /api/v1/projects/{author}/{slug}/upload: post: tags: - Versions operationId: uploadVersion_1 parameters: - name: author in: path description: The author of the project to return versions for required: true schema: type: string - name: slug in: path description: The slug of the project to return versions for required: true schema: type: string requestBody: content: multipart/form-data: schema: required: - versionUpload type: object properties: files: type: array description: "The version files in order of selected platforms,\ \ if any" items: type: string format: binary versionUpload: $ref: '#/components/schemas/VersionUpload' responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/UploadedVersion' deprecated: true /api/v1/keys: get: tags: - API Keys summary: Fetches a list of API Keys description: Fetches a list of API Keys. Requires the `edit_api_keys` permission. operationId: getKeys responses: "403": description: Not enough permissions to use this endpoint content: application/json: schema: type: array items: $ref: '#/components/schemas/ApiKey' "401": description: "Api session missing, invalid or expired" content: application/json: schema: type: array items: $ref: '#/components/schemas/ApiKey' "200": description: Key created content: application/json: schema: $ref: '#/components/schemas/ApiKey' security: - HangarAuth: - edit_api_keys post: tags: - API Keys summary: Creates an API key description: Creates an API key. Requires the `edit_api_keys` permission. operationId: createKey requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAPIKeyForm' required: true responses: "403": description: Not enough permissions to use this endpoint content: text/plain: schema: type: string "201": description: Key created content: text/plain: schema: type: string "401": description: "Api session missing, invalid or expired" content: text/plain: schema: type: string security: - HangarAuth: - edit_api_keys delete: tags: - API Keys summary: Deletes an API key description: Deletes an API key. Requires the `edit_api_keys` permission. operationId: deleteKey parameters: - name: name in: query description: The name of the key to delete required: true schema: type: string responses: "204": description: Key deleted "403": description: Not enough permissions to use this endpoint "401": description: "Api session missing, invalid or expired" security: - HangarAuth: - edit_api_keys /api/v1/authenticate: post: tags: - Authentication summary: Creates an API JWT description: "`Log-in` with your API key in order to be able to call other endpoints\ \ authenticated. The returned JWT should be specified as a header in all following\ \ requests: `Authorization: HangarAuth your.jwt`" operationId: authenticate parameters: - name: apiKey in: query description: JWT required: true schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/ApiSession' "401": description: Api key missing or invalid content: application/json: schema: $ref: '#/components/schemas/ApiSession' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiSession' /api/v1/pages/editmain/{slug}: patch: tags: - Pages summary: Edits the main page of a project description: Edits the main page of a project. Requires the `edit_page` permission in the project or owning organization. operationId: editMainPage parameters: - name: slug in: path description: The slug of the project to change the page for required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/StringContent' required: true responses: "200": description: Ok "403": description: Not enough permissions to use this endpoint "401": description: "Api session missing, invalid or expired" security: - HangarAuth: - edit_page /api/v1/pages/edit/{slug}: patch: tags: - Pages summary: Edits a page of a project description: Edits a page of a project. Requires the `edit_page` permission in the project or owning organization. operationId: editPage parameters: - name: slug in: path description: The slug of the project to change the page for required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PageEditForm' required: true responses: "200": description: Ok "403": description: Not enough permissions to use this endpoint "401": description: "Api session missing, invalid or expired" security: - HangarAuth: - edit_page /api/v1/users: get: tags: - Users summary: Searches for users description: Returns a list of users based on a search query. Requires the `view_public_info` permission. operationId: showUsers parameters: - name: query in: query description: The search query required: true schema: type: string - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' - name: sort in: query description: Used to sort the result style: form schema: type: string enum: - name - createdAt - projectCount - locked - org - roles responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' security: - HangarAuth: - view_public_info /api/v1/users/{user}: get: tags: - Users summary: Returns a specific user description: Returns a specific user. Requires the `view_public_info` permission. operationId: getUser parameters: - name: user in: path description: The name of the user to return required: true schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/User' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/User' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/User' security: - HangarAuth: - view_public_info /api/v1/users/{user}/watching: get: tags: - Users summary: Returns the watched projects for a specific user description: Returns the watched projects for a specific user. Requires the `view_public_info` permission. operationId: getUserWatching parameters: - name: user in: path description: The user to return watched projects for required: true schema: type: string - name: sort in: query description: How to sort the projects required: false schema: $ref: '#/components/schemas/ProjectSortingStrategy' - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' - name: sort in: query description: Used to sort the result style: form schema: type: string enum: - name - createdAt - projectCount - locked - org - roles responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectCompact' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectCompact' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectCompact' security: - HangarAuth: - view_public_info /api/v1/users/{user}/starred: get: tags: - Users summary: Returns the starred projects for a specific user description: Returns the starred projects for a specific user. Requires the `view_public_info` permission. operationId: showStarred parameters: - name: user in: path description: The user to return starred projects for required: true schema: type: string - name: sort in: query description: How to sort the projects required: false schema: $ref: '#/components/schemas/ProjectSortingStrategy' - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' - name: sort in: query description: Used to sort the result style: form schema: type: string enum: - name - createdAt - projectCount - locked - org - roles responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectCompact' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectCompact' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectCompact' security: - HangarAuth: - view_public_info /api/v1/users/{user}/pinned: get: tags: - Users summary: Returns the pinned projects for a specific user description: Returns the pinned projects for a specific user. Requires the `view_public_info` permission. operationId: getUserPinnedProjects parameters: - name: user in: path description: The user to return pinned projects for required: true schema: type: string responses: "200": description: Ok content: application/json: schema: type: array items: $ref: '#/components/schemas/ProjectCompact' "403": description: Not enough permissions to use this endpoint content: application/json: schema: type: array items: $ref: '#/components/schemas/ProjectCompact' "401": description: "Api session missing, invalid or expired" content: application/json: schema: type: array items: $ref: '#/components/schemas/ProjectCompact' security: - HangarAuth: - view_public_info /api/v1/staff: get: tags: - Users summary: Returns Hangar staff description: Returns Hanagr staff. Requires the `view_public_info` permission. operationId: getStaff parameters: - name: query in: query description: The search query required: true schema: type: string - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' - name: sort in: query description: Used to sort the result style: form schema: type: string enum: - name - createdAt - roles responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' security: - HangarAuth: - view_public_info /api/v1/projects: get: tags: - Projects summary: Searches the projects on Hangar description: "Searches all the projects on Hangar, or for a single user. Requires\ \ the `view_public_info` permission." operationId: getProjects parameters: - name: prioritizeExactMatch in: query description: Whether to prioritize the project with an exact name match if present required: false schema: type: boolean default: true - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' - name: sort in: query description: Used to sort the result style: form schema: type: string enum: - views - downloads - newest - stars - updated - recent_downloads - recent_views - slug - name: category in: query description: A category to filter for style: form schema: type: string - name: platform in: query description: A platform to filter for style: form schema: type: string - name: owner in: query description: The author of the project style: form schema: type: string - name: q in: query description: "Deprecated: Use 'query' instead" deprecated: true style: form schema: type: string - name: query in: query description: The query to use when searching style: form schema: type: string - name: license in: query description: A license to filter for style: form schema: type: string - name: version in: query description: A Minecraft version to filter for style: form schema: type: string - name: tag in: query description: A tag to filter for style: form schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProject' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProject' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProject' security: - HangarAuth: - view_public_info /api/v1/projects/{slug}: get: tags: - Projects summary: Returns info on a specific project description: Returns info on a specific project. Requires the `view_public_info` permission. operationId: getProject parameters: - name: slug in: path description: The slug of the project to return required: true schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/Project' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/Project' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/Project' security: - HangarAuth: - view_public_info /api/v1/projects/{slug}/watchers: get: tags: - Projects summary: Returns the watchers of a project description: Returns the watchers of a project. Requires the `view_public_info` permission. operationId: getProjectWatchers parameters: - name: slug in: path description: The slug of the project to return watchers for required: true schema: type: string - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' security: - HangarAuth: - view_public_info /api/v1/projects/{slug}/versions: get: tags: - Versions summary: Returns all versions of a project description: Returns all versions of a project. Requires the `view_public_info` permission in the project or owning organization. operationId: listVersions parameters: - name: slug in: path description: The slug of the project to return versions for required: true schema: type: string - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' - name: channel in: query description: A name of a version channel to filter for style: form schema: type: string - name: platform in: query description: A platform name to filter for style: form schema: type: string - name: platformVersion in: query description: A platform version to filter for style: form schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultVersion' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultVersion' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultVersion' security: - HangarAuth: - view_public_info /api/v1/projects/{slug}/versions/{name}: get: tags: - Versions summary: Returns a specific version of a project description: Returns a specific version of a project. Requires the `view_public_info` permission in the project or owning organization. operationId: showVersion parameters: - name: slug in: path description: The slug of the project to return the version for required: true schema: type: string - name: name in: path description: The name of the version to return required: true schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/Version' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/Version' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/Version' security: - HangarAuth: - view_public_info /api/v1/projects/{slug}/versions/{name}/{platform}/download: get: tags: - Versions summary: Downloads a version description: Downloads the file for a specific platform of a version. Requires visibility of the project and version. operationId: downloadVersion parameters: - name: slug in: path description: The slug of the project to download the version from required: true schema: type: string - name: name in: path description: The name of the version to download required: true schema: type: string - name: platform in: path description: The platform of the version to download required: true schema: $ref: '#/components/schemas/Platform' responses: "303": description: Version has an external download url content: application/octet-stream: schema: type: object "200": description: Ok content: application/octet-stream: schema: type: object "400": description: Version doesn't have a file attached to it content: application/octet-stream: schema: type: object "403": description: Not enough permissions to use this endpoint content: application/octet-stream: schema: type: object "401": description: "Api session missing, invalid or expired" content: application/octet-stream: schema: type: object security: - HangarAuth: [] /api/v1/projects/{slug}/versions/{name}/stats: get: tags: - Versions summary: Returns the stats for a version description: Returns the stats (downloads) for a version per day for a certain date range. Requires the `is_subject_member` permission. operationId: showVersionStats parameters: - name: slug in: path description: The slug of the project to return stats for required: true schema: type: string - name: name in: path description: The version to return the stats for required: true schema: type: string - name: fromDate in: query description: The first date to include in the result required: true schema: type: string format: date-time - name: toDate in: query description: The last date to include in the result required: true schema: type: string format: date-time responses: "200": description: Ok content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/VersionStats' "403": description: Not enough permissions to use this endpoint content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/VersionStats' "401": description: "Api session missing, invalid or expired" content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/VersionStats' security: - HangarAuth: - is_subject_member /api/v1/projects/{slug}/stats: get: tags: - Projects summary: Returns the stats for a project description: Returns the stats (downloads and views) for a project per day for a certain date range. Requires the `is_subject_member` permission. operationId: showProjectStats parameters: - name: slug in: path description: The slug of the project to return stats for required: true schema: type: string - name: fromDate in: query description: The first date to include in the result required: true schema: type: string format: date-time - name: toDate in: query description: The last date to include in the result required: true schema: type: string format: date-time responses: "200": description: Ok content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/DayProjectStats' "403": description: Not enough permissions to use this endpoint content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/DayProjectStats' "401": description: "Api session missing, invalid or expired" content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/DayProjectStats' security: - HangarAuth: - is_subject_member /api/v1/projects/{slug}/stargazers: get: tags: - Projects summary: Returns the stargazers of a project description: Returns the stargazers of a project. Requires the `view_public_info` permission. operationId: getProjectStargazers parameters: - name: slug in: path description: The slug of the project to return stargazers for required: true schema: type: string - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' security: - HangarAuth: - view_public_info /api/v1/projects/{slug}/members: get: tags: - Projects summary: Returns the members of a project description: Returns the members of a project. Requires the `view_public_info` permission. operationId: getProjectMembers parameters: - name: slug in: path description: The slug of the project to return members for required: true schema: type: string - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectMember' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectMember' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultProjectMember' security: - HangarAuth: - view_public_info /api/v1/projects/{slug}/latestrelease: get: tags: - Versions summary: Returns the latest release version of a project description: Returns the latest version of a project. Requires the `view_public_info` permission in the project or owning organizations. operationId: latestReleaseVersion parameters: - name: slug in: path description: The slug of the project to return the latest version for required: true schema: type: string responses: "200": description: Ok content: text/plain: schema: type: string "403": description: Not enough permissions to use this endpoint content: text/plain: schema: type: string "401": description: "Api session missing, invalid or expired" content: text/plain: schema: type: string security: - HangarAuth: - view_public_info /api/v1/projects/{slug}/latest: get: tags: - Versions summary: Returns the latest version of a project for a specific channel description: Returns the latest version of a project. Requires the `view_public_info` permission in the project or owning organization. operationId: latestVersion parameters: - name: slug in: path description: The slug of the project to return the latest version for required: true schema: type: string - name: channel in: query description: The channel to return the latest version for required: true schema: type: string responses: "200": description: Ok content: text/plain: schema: type: string "403": description: Not enough permissions to use this endpoint content: text/plain: schema: type: string "401": description: "Api session missing, invalid or expired" content: text/plain: schema: type: string security: - HangarAuth: - view_public_info /api/v1/projects/{author}/{slug}/versions: get: tags: - Versions operationId: getVersions parameters: - name: author in: path description: The author of the project to return versions for required: true schema: type: string - name: slug in: path description: The slug of the project to return versions for required: true schema: type: string - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResultVersion' deprecated: true /api/v1/projects/{author}/{slug}/versions/{name}: get: tags: - Versions operationId: getVersion parameters: - name: author in: path description: The author of the project to return the version for required: true schema: type: string - name: slug in: path description: The slug of the project to return the version for required: true schema: type: string - name: name in: path description: The name of the version to return required: true schema: type: string responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/Version' deprecated: true /api/v1/projects/{author}/{slug}/versions/{name}/{platform}/download: get: tags: - Versions operationId: downloadVersion_1 parameters: - name: author in: path description: The author of the project to download the version from required: true schema: type: string - name: slug in: path description: The slug of the project to download the version from required: true schema: type: string - name: name in: path description: The name of the version to download required: true schema: type: string - name: platform in: path description: The platform of the version to download required: true schema: $ref: '#/components/schemas/Platform' responses: "200": description: OK content: application/octet-stream: schema: type: object deprecated: true /api/v1/projects/{author}/{slug}/versions/{name}/stats: get: tags: - Versions operationId: getVersionStats parameters: - name: author in: path description: The author of the version to return the stats for required: true schema: type: string - name: slug in: path description: The slug of the project to return stats for required: true schema: type: string - name: name in: path description: The version to return the stats for required: true schema: type: string - name: fromDate in: query description: The first date to include in the result required: true schema: type: string format: date-time - name: toDate in: query description: The last date to include in the result required: true schema: type: string format: date-time responses: "200": description: OK content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/VersionStats' deprecated: true /api/v1/projects/{author}/{slug}/latestrelease: get: tags: - Versions operationId: getLatestReleaseVersion parameters: - name: author in: path description: The author of the project to return the latest version for required: true schema: type: string - name: slug in: path description: The slug of the project to return the latest version for required: true schema: type: string responses: "200": description: OK content: text/plain: schema: type: string deprecated: true /api/v1/projects/{author}/{slug}/latest: get: tags: - Versions operationId: getLatestVersion parameters: - name: author in: path description: The author of the project to return the latest version for required: true schema: type: string - name: slug in: path description: The slug of the project to return the latest version for required: true schema: type: string - name: channel in: query description: The channel to return the latest version for required: true schema: type: string responses: "200": description: OK content: text/plain: schema: type: string deprecated: true /api/v1/permissions: get: tags: - Permissions summary: Returns your permissions description: Returns a list of permissions you have in the given context operationId: showPermissions parameters: - name: slug in: query description: The slug of the project get the permissions for. Must not be used together with `organizationName` required: false schema: type: string - name: organization in: query description: The organization to check permissions in. Must not be used together with `projectOwner` and `projectSlug` required: false schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/UserPermissions' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/UserPermissions' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/UserPermissions' security: - HangarAuth: [] /api/v1/permissions/hasAny: get: tags: - Permissions summary: Checks whether you have at least one of the provided permissions description: Checks whether you have at least one of the provided permissions in the given context operationId: hasAny parameters: - name: permissions in: query description: The permissions to check required: true schema: uniqueItems: true type: array items: $ref: '#/components/schemas/NamedPermission' - name: slug in: query description: The slug of the project to check permissions in. Must not be used together with `organization` required: false schema: type: string - name: organization in: query description: The organization to check permissions in. Must not be used together with `slug` required: false schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PermissionCheck' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PermissionCheck' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/PermissionCheck' security: - HangarAuth: [] /api/v1/permissions/hasAll: get: tags: - Permissions summary: Checks whether you have all the provided permissions description: Checks whether you have all the provided permissions in the given context operationId: hasAll parameters: - name: permissions in: query description: The permissions to check required: true schema: maxItems: 50 minItems: 0 uniqueItems: true type: array items: $ref: '#/components/schemas/NamedPermission' - name: slug in: query description: The project slug of the project to check permissions in. Must not be used together with `organizationName` required: false schema: type: string - name: organization in: query description: The organization to check permissions in. Must not be used together with `projectOwner` and `projectSlug` required: false schema: type: string responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PermissionCheck' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PermissionCheck' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/PermissionCheck' security: - HangarAuth: [] /api/v1/pages/page/{slug}: get: tags: - Pages summary: Returns a page of a project description: Returns a page of a project. Requires visibility of the page. operationId: getPage parameters: - name: slug in: path description: The slug of the project to return the page for required: true schema: type: string - name: path in: query description: The path of the page required: true schema: type: string responses: "200": description: Ok content: text/plain: schema: type: string "403": description: Not enough permissions to use this endpoint content: text/plain: schema: type: string "401": description: "Api session missing, invalid or expired" content: text/plain: schema: type: string /api/v1/pages/main/{slug}: get: tags: - Pages summary: Returns the main page of a project description: Returns the main page of a project. Requires visibility of the page. operationId: getMainPage parameters: - name: slug in: path description: The slug of the project to return the page for required: true schema: type: string responses: "200": description: Ok content: text/plain: schema: type: string "403": description: Not enough permissions to use this endpoint content: text/plain: schema: type: string "401": description: "Api session missing, invalid or expired" content: text/plain: schema: type: string /api/v1/authors: get: tags: - Users summary: Returns all users with at least one public project description: Returns all users that have at least one public project. Requires the `view_public_info` permission. operationId: getAuthors parameters: - name: query in: query description: The search query required: true schema: type: string - name: pagination in: query description: Pagination information required: true schema: $ref: '#/components/schemas/RequestPagination' - name: sort in: query description: Used to sort the result style: form schema: type: string enum: - name - createdAt - projectCount responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "403": description: Not enough permissions to use this endpoint content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' "401": description: "Api session missing, invalid or expired" content: application/json: schema: $ref: '#/components/schemas/PaginatedResultUser' security: - HangarAuth: - view_public_info components: schemas: MultipartFileOrUrl: type: object properties: platforms: type: array description: List of platforms this jar runs on example: "[PAPER, WATERFALL, VELOCITY]" items: $ref: '#/components/schemas/Platform' externalUrl: type: string description: "External url to download the jar from if not provided via\ \ an attached jar, else null" example: https://papermc.io/downloads description: List of different jars/external links that are part of the version Platform: type: string description: Server platform example: PAPER enum: - PAPER - WATERFALL - VELOCITY PluginDependency: type: object properties: name: type: string description: "Name of the plugin dependency. For non-external dependencies,\ \ this should be the Hangar project name" example: Maintenance required: type: boolean description: Whether the dependency is required for the plugin to function externalUrl: type: string description: "External url to download the dependency from if not a Hangar\ \ project, else null" example: https://papermc.io/downloads platform: $ref: '#/components/schemas/Platform' description: Map of each platform's plugin dependencies VersionUpload: required: - channel - version type: object properties: version: type: string description: Version string of the version to be published example: 1.0.0-SNAPSHOT+1 pluginDependencies: type: object additionalProperties: uniqueItems: true type: array description: Map of each platform's plugin dependencies items: $ref: '#/components/schemas/PluginDependency' description: Map of each platform's plugin dependencies platformDependencies: type: object additionalProperties: uniqueItems: true type: array description: Map of platforms and their versions this version runs on example: "{PAPER: [\"1.12\", \"1.16-1.18.2\", \"1.20.x\"]}" items: type: string description: Map of platforms and their versions this version runs on example: "{PAPER: [\"1.12\", \"1.16-1.18.2\", \"1.20.x\"]}" description: Map of platforms and their versions this version runs on example: "{PAPER: [\"1.12\", \"1.16-1.18.2\", \"1.20.x\"]}" description: type: string files: maxItems: 3 minItems: 1 type: array items: $ref: '#/components/schemas/MultipartFileOrUrl' channel: type: string description: Channel of the version to be published under example: Release description: Version data. See the VersionUpload schema for more info UploadedVersion: type: object properties: url: type: string description: URL of the uploaded version example: https://hangar.papermc.io/PaperMC/Debuggery/versions/1.0.0 description: A version that has been uploaded CreateAPIKeyForm: required: - name - permissions type: object properties: name: maximum: 36 minimum: 5 maxLength: 36 minLength: 5 type: string permissions: uniqueItems: true type: array items: $ref: '#/components/schemas/NamedPermission' description: Data about the key to create NamedPermission: type: string enum: - view_public_info - edit_own_user_settings - edit_api_keys - edit_subject_settings - manage_subject_members - is_subject_owner - is_subject_member - create_project - edit_page - delete_project - create_version - edit_version - delete_version - edit_channels - create_organization - delete_organization - post_as_organization - mod_notes_and_flags - see_hidden - is_staff - reviewer - view_health - view_ip - view_stats - view_logs - manual_value_changes - restore_version - restore_project - hard_delete_project - hard_delete_version - edit_all_user_settings ApiSession: type: object properties: token: type: string description: JWT used for authentication expiresIn: type: integer description: Milliseconds this JWT expires in format: int64 StringContent: required: - content type: object properties: content: type: string description: "A non-null, non-empty string" description: The path and new contents of the page PageEditForm: required: - content - path type: object properties: path: type: string content: type: string description: The path and new contents of the page RequestPagination: type: object properties: limit: maximum: 25 minimum: 1 type: integer description: The maximum amount of items to return format: int64 example: 1 offset: minimum: 0 type: integer description: Where to start searching format: int64 example: 0 JsonNode: type: object PaginatedResultUser: type: object properties: pagination: $ref: '#/components/schemas/Pagination' result: type: array items: $ref: '#/components/schemas/User' Pagination: type: object properties: limit: maximum: 25 minimum: 1 type: integer description: The maximum amount of items to return format: int64 example: 1 offset: minimum: 0 type: integer description: Where to start searching format: int64 example: 0 count: type: integer format: int64 User: type: object properties: createdAt: type: string format: date-time name: type: string tagline: type: string roles: type: array items: type: integer format: int64 projectCount: type: integer format: int64 locked: type: boolean nameHistory: type: array items: $ref: '#/components/schemas/UserNameChange' avatarUrl: type: string socials: $ref: '#/components/schemas/JsonNode' isOrganization: type: boolean UserNameChange: type: object properties: oldName: type: string newName: type: string date: type: string format: date-time ProjectSortingStrategy: type: string enum: - stars - downloads - views - newest - updated - recent_views - recent_downloads Category: type: string description: The category of the project enum: - admin_tools - chat - dev_tools - economy - gameplay - games - protection - role_playing - world_management - misc - undefined PaginatedResultProjectCompact: type: object properties: pagination: $ref: '#/components/schemas/Pagination' result: type: array items: $ref: '#/components/schemas/ProjectCompact' ProjectCompact: type: object properties: createdAt: type: string format: date-time name: type: string description: The unique name of the project namespace: $ref: '#/components/schemas/ProjectNamespace' stats: $ref: '#/components/schemas/ProjectStats' category: $ref: '#/components/schemas/Category' lastUpdated: type: string description: The last time the project was updated format: date-time visibility: $ref: '#/components/schemas/Visibility' avatarUrl: type: string description: The url to the project's icon ProjectNamespace: type: object properties: owner: type: string slug: type: string description: The unique name of a project example: Maintenance description: The namespace of the project ProjectStats: type: object properties: views: type: integer format: int64 downloads: type: integer format: int64 recentViews: type: integer format: int64 recentDownloads: type: integer format: int64 stars: type: integer format: int64 watchers: type: integer format: int64 description: Stats of the project Visibility: type: string description: The visibility of a project or version example: PUBLIC enum: - public - new - needsChanges - needsApproval - softDelete Link: type: object properties: id: type: integer format: int64 name: type: string url: type: string LinkSection: required: - links - type type: object properties: id: type: integer format: int64 type: type: string description: Type of the link. Either SIDEBAR or TOP example: TOP title: type: string links: type: array items: $ref: '#/components/schemas/Link' PaginatedResultProject: type: object properties: pagination: $ref: '#/components/schemas/Pagination' result: type: array items: $ref: '#/components/schemas/Project' Project: type: object properties: createdAt: type: string format: date-time name: type: string description: The unique name of the project namespace: $ref: '#/components/schemas/ProjectNamespace' stats: $ref: '#/components/schemas/ProjectStats' category: $ref: '#/components/schemas/Category' lastUpdated: type: string description: The last time the project was updated format: date-time visibility: $ref: '#/components/schemas/Visibility' avatarUrl: type: string description: The url to the project's icon description: type: string description: The short description of the project userActions: $ref: '#/components/schemas/UserActions' settings: $ref: '#/components/schemas/ProjectSettings' ProjectDonationSettings: type: object properties: enable: type: boolean subject: type: string ProjectLicense: type: object properties: name: type: string url: type: string type: type: string ProjectSettings: required: - keywords - links - tags type: object properties: links: type: array items: $ref: '#/components/schemas/LinkSection' tags: type: array items: type: string license: $ref: '#/components/schemas/ProjectLicense' keywords: type: array items: type: string sponsors: type: string donation: $ref: '#/components/schemas/ProjectDonationSettings' description: The settings of the project UserActions: type: object properties: starred: type: boolean watching: type: boolean flagged: type: boolean description: Information about your interactions with the project ChannelFlag: type: string enum: - FROZEN - UNSTABLE - PINNED - SENDS_NOTIFICATIONS Color: type: string enum: - '#B400FF' - '#C87DFF' - '#E100E1' - '#0000FF' - '#B9F2FF' - '#E7FEFF' - '#0096FF' - '#00E1E1' - '#00DC00' - '#009600' - '#7FFF00' - '#FFC800' - '#CFB53B' - '#FF8200' - '#DC0000' - '#C0C0C0' - '#A9A9A9' - transparent FileInfo: type: object properties: name: type: string sizeBytes: type: integer format: int64 sha256Hash: type: string PaginatedResultVersion: type: object properties: pagination: $ref: '#/components/schemas/Pagination' result: type: array items: $ref: '#/components/schemas/Version' PinnedStatus: type: string enum: - NONE - VERSION - CHANNEL PlatformVersionDownload: type: object properties: fileInfo: $ref: '#/components/schemas/FileInfo' externalUrl: type: string description: External download url if not directly uploaded to Hangar downloadUrl: type: string description: Hangar download url if not an external download ProjectChannel: type: object properties: createdAt: type: string format: date-time name: type: string description: type: string color: $ref: '#/components/schemas/Color' flags: uniqueItems: true type: array items: $ref: '#/components/schemas/ChannelFlag' ReviewState: type: string enum: - unreviewed - reviewed - under_review - partially_reviewed Version: type: object properties: createdAt: type: string format: date-time name: type: string visibility: $ref: '#/components/schemas/Visibility' description: type: string stats: $ref: '#/components/schemas/VersionStats' author: type: string reviewState: $ref: '#/components/schemas/ReviewState' channel: $ref: '#/components/schemas/ProjectChannel' pinnedStatus: $ref: '#/components/schemas/PinnedStatus' downloads: type: object additionalProperties: $ref: '#/components/schemas/PlatformVersionDownload' pluginDependencies: type: object additionalProperties: uniqueItems: true type: array items: $ref: '#/components/schemas/PluginDependency' platformDependencies: type: object additionalProperties: uniqueItems: true type: array items: type: string platformDependenciesFormatted: type: object additionalProperties: type: string VersionStats: type: object properties: totalDownloads: type: integer format: int64 platformDownloads: type: object additionalProperties: type: integer format: int64 DayProjectStats: type: object properties: views: type: integer format: int64 downloads: type: integer format: int64 CompactRole: type: object properties: title: type: string color: $ref: '#/components/schemas/Color' rank: type: integer format: int32 category: type: string PaginatedResultProjectMember: type: object properties: pagination: $ref: '#/components/schemas/Pagination' result: type: array items: $ref: '#/components/schemas/ProjectMember' ProjectMember: type: object properties: user: type: string roles: type: array items: $ref: '#/components/schemas/CompactRole' PermissionType: type: string enum: - global - project - organization UserPermissions: type: object properties: type: $ref: '#/components/schemas/PermissionType' permissionBinString: type: string permissions: type: array items: $ref: '#/components/schemas/NamedPermission' PermissionCheck: type: object properties: type: $ref: '#/components/schemas/PermissionType' result: type: boolean ApiKey: type: object properties: createdAt: type: string format: date-time name: type: string tokenIdentifier: type: string permissions: type: array items: $ref: '#/components/schemas/NamedPermission' lastUsed: type: string format: date-time securitySchemes: HangarAuth: type: http scheme: bearer bearerFormat: JWT