# API # API Usage The Forgejo API for all versions that have the same major number (e.g. the major number of Forgejo 7.0.0 is 7) are compatible. There are breaking changes (e.g. removal of an API endpoint) when the major number changes and the release notes of this major version provide explanations to help developers upgrade their software accordingly. Read more about the [Forgejo numbering scheme](/link/1150). > **Warning:** The following instructions use `forgejo.example.org` as placeholder for the Forgejo instance URL and other placeholders, such as `{yourusername}` and `{yourpassword}`, which need to be replaced before running these commands. ## Enabling/configuring API access By default, the API is enabled on Forgejo instances, but instance administrators may choose to [disable it](/link/1226#bkmrk-api-%28api%29). ## Authentication Forgejo supports these methods of API authentication: - HTTP basic authentication - `Authorization: Bearer ...` header in HTTP headers - `Authorization: token ...` header in HTTP headers ### Generating and listing API tokens A new token can be generated with a `POST` request to `/users/:name/tokens`. Note that `/users/:name/tokens` is a special endpoint and requires you to authenticate using `BasicAuth` and a password, as follows: ```sh $ curl -H "Content-Type: application/json" -d '{"name":"test","scopes":["write:package"]}' -u {yourusername}:{yourpassword} https://forgejo.example.org/api/v1/users/{username}/tokens {"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d","scopes":["write:package"]} ``` The keys of the JSON data object are `name` (the display name for the token) and `scopes` (list of [Access Token scope](/link/1157) names). The `sha1` (the token) is only returned once and is not stored in plain-text. It will not be displayed when listing tokens with a `GET` request; e.g. ```sh $ curl --url https://{yourusername}:{yourpassword}@forgejo.example.org/api/v1/users/{username}/tokens [{"name":"test","sha1":"","token_last_eight":"........"},{"name":"dev","sha1":"","token_last_eight":"........"}] ``` To use the API with basic authentication with two factor authentication (2FA) enabled, you'll need to send an additional header that contains the one-time password (6-digit rotating token). An example of the header is `X-Forgejo-OTP: 123456` where `123456` is where you'd place the code from your authenticator. Here is how the request would look like in curl: ```sh $ curl -H "X-Forgejo-OTP: 123456" --url https://{yourusername}:{yourpassword}@forgejo.example.org/api/v1/users/{username}/tokens ``` You can also create an API key token via your Forgejo installation's web interface: `Settings | Applications | Generate New Token`. ### OAuth2 Provider Access tokens obtained from Forgejo's OAuth2 provider are accepted by these methods: - `Authorization: Bearer ...` header in HTTP headers - `token=...` parameter in URL query string - `access_token=...` parameter in URL query string #### More on the `Authorization:` header For historical reasons, Forgejo needs the word `token` included before the API key token in an authorization header, like this: ``` Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675 ``` In a `curl` command, for instance, this would look like: ```sh curl "https://forgejo.example.org/api/v1/repos/test1/test1/issues" \ -H "accept: application/json" \ -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \ -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i ``` As mentioned above, the token used is the same one you would use in the `token=` string in a GET request. ### Sudo The API allows admin users to sudo API requests as another user. Simply add either a `sudo=` parameter or `Sudo:` request header with the username of the user to sudo. ## Pagination The API supports pagination. The `page` and `limit` parameters are used to specify the page number and the number of items per page. As well, the `Link` header is returned with the next, previous, and last page links if there are more than one page. The `x-total-count` is also returned to indicate the total number of items. ```sh curl -v "https://forgejo.example.org/api/v1/repos/search?limit=1" ... < link: ; rel="next",; rel="last" ... < x-total-count: 5252 ``` The default and maximum values for the `page` parameter can be obtained from the `https://forgejo.example.org/api/v1/settings/api` endpoint. ```sh $ curl https://forgejo.example.org/api/v1/settings/api { "max_response_items": 50, "default_paging_num": 30, "default_git_trees_per_page": 1000, "default_max_blob_size": 10485760 } ``` ## API Guide API Reference guide is auto-generated by Swagger and available on: `https://forgejo.example.org/api/swagger`. For instance, find the reference guide of [Forgejo Next](https://forgejo.org/docs/v15.0/user/api/forgejo-next/) at . The OpenAPI document is at: `https://forgejo.example.org/swagger.v1.json` ## SDKs Find [clients using the API](https://delightful.coding.social/delightful-forgejo/#clients) and [API client libraries](https://delightful.coding.social/delightful-forgejo/#api-client-libraries) at the list of [Delightful Forgejo](https://delightful.coding.social/delightful-forgejo). # Forgejo numbering scheme The Forgejo versions look like `X.Y.Z+gitea-A.B.C` (e.g., 7.0.0+gitea-1.22.0). The Forgejo version is the first part, before the '+' (e.g., 7.0.0), and the following metadata, after the '+', shows the Gitea version with which the API is compatible (e.g., 1.22.0). ## Obtaining the Forgejo version The Forgejo version is displayed in the footer of the web UI, in the output of the `forgejo --version` CLI, and returned by two API endpoints: - [example.com/api/v1/version](https://code.forgejo.org/api/swagger/#/miscellaneous/getVersion) - [example.com/api/forgejo/v1/version](https://code.forgejo.org/api/forgejo/swagger/#/default/getVersion) For Forgejo 7.0.0 and above, the two endpoints return the same value and they match what is displayed by the CLI or the web UI. ## Compatibility with Gitea As of Forgejo 7.0.0, tools designed to work with Gitea 1.22.0 and below are compatible and do not need any modification to keep working. In the future, if a tool wants to assert the level of compatibility of a Forgejo version with Gitea, it can: - Obtain the version number [example.com/api/v1/version](https://code.forgejo.org/api/swagger/#/miscellaneous/getVersion) using the same API endpoint as Gitea - If the returned version contains '+gitea-', keep what follows as the compatible Gitea version number For instance, Gitnex will not notice a difference when the version number is bumped from Forgejo 1.21.7-0 to Forgejo 7.0.0. It only uses version numbers to verify if a new feature is available in a newer version. The last time such a check was added was with Gitea 1.17, which was published in July 2022. ## Semantic Version [SemVer](https://semver.org/spec/v2.0.0.html) allows users to understand the scope of a software update at first glance, based on the following: - `` is increased for breaking changes. - `` is increased for backwards-compatible new features. - `` is increased for backwards-compatible bug fixes. Forgejo changes reflected in the version could be: - a command, an option, or an argument, for a CLI - a route path, a query parameter, or a body property, for a REST API - a text node, a button, or a field, for a GUI Since Forgejo has all of the above, changes to all of those components are taken into consideration when creating a new version number. ### Stable versions The structure of the version number is `..+gitea-`, where: - `..` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200) - `gitea-` is the Gitea version this Forgejo release is compatible with ### Experimental and pre-release versions The structure of the version number is `..-dev-+gitea-`, where: - `..` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200) - `` is the Git SHA from which the release was built - `gitea-` is the Gitea version this Forgejo release is compatible with ## Legacy forgejo numbering scheme In Forgejo versions prior to 7.0.0, i.e., from 1.18.0-1 to 1.21.7-0 included, the Forgejo version matched the Gitea version by removing the string following the trailing dash (-) and the release cycles were synchronized. The version number A.B.C-N was displayed with the dash (-) replaced by a plus (+) (e.g., Forgejo 1.18.0-1 was displayed as 1.18.0+1). The two API endpoints returned different results: - [example.com/api/v1/version](https://code.forgejo.org/api/swagger/#/miscellaneous/getVersion) returned `{"version":"A.B.C+N"}` - [example.com/api/forgejo/v1/version](https://code.forgejo.org/api/forgejo/swagger/#/default/getVersion) returned `{"version":"X.Y.Z+N-gitea-A.B.C"}` The Forgejo semantic number `X.Y.Z` could only be found in the second endpoint and was used to prepare for switching to semantic versioning. It was advertised in release notes and [documented in the user reference guide](https://forgejo.org/docs/v1.21/user/semver/). # API Forgejo's API is documented via Swagger/OpenAPI v2, the raw JSON file can be accessed via https://next.forgejo.org/swagger.v1.json. A human readable UI for the swagger file can be accessed via https://next.forgejo.org/api/swagger. Using the API is furthermore documented in [API Usage][./usage/].