Skip to main content

​
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/: 
https://your-gitea-instance.com/api/v1/
For example, to get version information: 
https://your-gitea-instance.com/api/v1/version
Replace your-gitea-instance.com with your actual Gitea server domain.

​
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: 
curl https://your-gitea-instance.com/api/v1/version

​
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)
Always set the Content-Type: application/json header when sending JSON data in request bodies.

​
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)
curl "https://your-gitea-instance.com/api/v1/repos/search?page=2&limit=20" \
  -H "Authorization: token YOUR_TOKEN"
Pagination limits are configurable in the server settings:
  • API.MaxResponseItems: Maximum items per page (default: 50)
  • API.DefaultPagingNum: Default items per page (default: 30)

​
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)
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.

​
CORS Support

CORS (Cross-Origin Resource Sharing) can be enabled in the Gitea configuration: 
[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
Swagger documentation can be enabled/disabled via the API.EnableSwagger configuration option (enabled by default).

​
API Settings

The following settings can be configured in app.ini: 
[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
Query parameter authentication (token and access_token) is deprecated and will be removed in future versions. Use the Authorization header instead.

​
Next Steps

Authentication

Learn about authentication methods and token management

API Reference

Explore the complete API endpoint reference

Build docs developers (and LLMs) love

Get started for freeTalk to us