forgejo-docs/docs/user/api-usage.md

---
title: 'API Usage'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/development/api-usage.en-us.md'
---

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](../versions/).

## Enabling/configuring API access

By default, `ENABLE_SWAGGER` is true, and `MAX_RESPONSE_ITEMS` is set to 50.

## Authentication

Forgejo supports these methods of API authentication:

- HTTP basic authentication
- `token=...` parameter in URL query string
- `access_token=...` parameter in URL query string
- `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 username:password https://forgejo.your.host/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](../token-scope/) 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:password@forgejo.your.host/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
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.your.host/api/v1/users/yourusername/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:

```sh
Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
```

In a `curl` command, for instance, this would look like:

```sh
curl "http://localhost:4000/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.

## 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 pages. The `x-total-count` is also returned to indicate the total number of items.

```sh
curl -v "http://localhost/api/v1/repos/search?limit=1"
...
< link: <http://localhost/api/v1/repos/search?limit=1&page=2>; rel="next",<http://localhost/api/v1/repos/search?limit=1&page=5252>; rel="last"
...
< x-total-count: 5252
```

The default and maximum values for the `page` parameter can be obtained from the `https://forgejo.your.host/api/v1/settings/api` endpoint.

```sh
$ curl https://codeberg.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.your.host/api/swagger`.

The OpenAPI document is at:
`https://forgejo.your.host/swagger.v1.json`

## 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.

## SDKs

- See [the list at delightful Forgejo](https://codeberg.org/forgejo-contrib/delightful-forgejo)