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

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

## 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"}' -u username:password https://forgejo.your.host/api/v1/users/<username>/tokens
{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
```

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)