> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Introduction to the Gitea REST API, including base URLs, versioning, and rate limits

## Introduction

The Gitea API provides programmatic access to Gitea's features, allowing you to automate repository management, user administration, issue tracking, and more. The API follows REST principles and returns JSON responses.

## Base URL

The API is versioned and all endpoints are prefixed with `/api/v1/`:

```bash theme={null}
https://your-gitea-instance.com/api/v1/
```

For example, to get version information:

```bash theme={null}
https://your-gitea-instance.com/api/v1/version
```

<Note>
  Replace `your-gitea-instance.com` with your actual Gitea server domain.
</Note>

## API Versioning

Gitea currently uses API version 1 (`v1`) as the stable API version. The version is included in the URL path:

* **Current Version**: `v1`
* **Base Path**: `/api/v1/`
* **Full URL Pattern**: `https://{domain}/api/v1/{endpoint}`

The API version is returned in responses and can be retrieved via the version endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://your-gitea-instance.com/api/v1/version
  ```

  ```javascript JavaScript theme={null}
  fetch('https://your-gitea-instance.com/api/v1/version')
    .then(response => response.json())
    .then(data => console.log(data));
  ```

  ```python Python theme={null}
  import requests

  response = requests.get('https://your-gitea-instance.com/api/v1/version')
  print(response.json())
  ```
</CodeGroup>

## Content Types

The API consumes and produces the following content types:

**Consumes:**

* `application/json`
* `text/plain`

**Produces:**

* `application/json` (default)
* `text/html` (for specific endpoints)

<Note>
  Always set the `Content-Type: application/json` header when sending JSON data in request bodies.
</Note>

## Response Formats

All API responses use JSON format. Successful responses return the requested data with appropriate HTTP status codes:

* **200 OK**: Request succeeded
* **201 Created**: Resource created successfully
* **204 No Content**: Request succeeded with no content to return
* **400 Bad Request**: Invalid request parameters
* **401 Unauthorized**: Authentication required or failed
* **403 Forbidden**: Insufficient permissions
* **404 Not Found**: Resource not found
* **422 Unprocessable Entity**: Validation error

## Pagination

Many list endpoints support pagination through query parameters:

* `page`: Page number (default: 1)
* `limit`: Items per page (default: 30, max: 50)

<CodeGroup>
  ```bash Example Request theme={null}
  curl "https://your-gitea-instance.com/api/v1/repos/search?page=2&limit=20" \
    -H "Authorization: token YOUR_TOKEN"
  ```

  ```json Example Response theme={null}
  {
    "data": [
      {
        "id": 1,
        "name": "repo-name",
        "full_name": "owner/repo-name"
      }
    ],
    "ok": true
  }
  ```
</CodeGroup>

<Note>
  Pagination limits are configurable in the server settings:

  * `API.MaxResponseItems`: Maximum items per page (default: 50)
  * `API.DefaultPagingNum`: Default items per page (default: 30)
</Note>

## Rate Limiting

Gitea does not enforce built-in API rate limiting at the application level. However, rate limiting may be implemented through:

1. **Reverse Proxy**: Configure rate limiting in nginx, Apache, or other reverse proxies
2. **External Migration**: Rate limits apply when migrating repositories from external sources (e.g., GitHub)

<Warning>
  When migrating repositories from external sources like GitHub, you may encounter rate limiting from those platforms. Use authenticated requests or multiple tokens to increase rate limits on source platforms.
</Warning>

## CORS Support

CORS (Cross-Origin Resource Sharing) can be enabled in the Gitea configuration:

```ini theme={null}
[cors]
ENABLED = true
ALLOW_DOMAIN = https://example.com
METHODS = GET,POST,PUT,PATCH,DELETE
ALLOW_CREDENTIALS = true
MAX_AGE = 3600
```

When enabled, the API includes appropriate CORS headers:

* `Access-Control-Allow-Origin`
* `Access-Control-Allow-Methods`
* `Access-Control-Allow-Headers`
* `Access-Control-Max-Age`

## Swagger Documentation

Gitea provides interactive Swagger/OpenAPI documentation for the API. Access it at:

```
https://your-gitea-instance.com/api/swagger
```

The Swagger UI allows you to:

* Browse all available endpoints
* View request/response schemas
* Test API calls directly from the browser
* Download the OpenAPI specification

<Note>
  Swagger documentation can be enabled/disabled via the `API.EnableSwagger` configuration option (enabled by default).
</Note>

## API Settings

The following settings can be configured in `app.ini`:

```ini theme={null}
[api]
; Enable Swagger API documentation
ENABLE_SWAGGER = true

; Maximum number of items in a single API response
MAX_RESPONSE_ITEMS = 50

; Default number of items per page
DEFAULT_PAGING_NUM = 30

; Default number of items per page for git trees
DEFAULT_GIT_TREES_PER_PAGE = 1000

; Maximum blob size to return in API responses (bytes)
DEFAULT_MAX_BLOB_SIZE = 10485760

; Maximum response size (bytes)
DEFAULT_MAX_RESPONSE_SIZE = 104857600
```

## Security Schemes

The API supports multiple authentication methods:

* **BasicAuth**: HTTP Basic Authentication
* **Token**: API token in query parameter (deprecated)
* **AccessToken**: Access token in query parameter (deprecated)
* **AuthorizationHeaderToken**: Bearer token in Authorization header (recommended)
* **SudoParam**: Sudo parameter for admin impersonation
* **SudoHeader**: Sudo header for admin impersonation
* **TOTPHeader**: TOTP header for two-factor authentication

<Warning>
  Query parameter authentication (`token` and `access_token`) is deprecated and will be removed in future versions. Use the Authorization header instead.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn about authentication methods and token management
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Explore the complete API endpoint reference
  </Card>
</CardGroup>