A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Gitea API is how an app or AI agent works with a Gitea instance: reading and creating repositories, filing and editing issues, opening and merging pull requests, and reading or writing files in a repository. Access is granted through an access token sent in an Authorization header, and each token carries scopes that decide which areas it can read or write, so an agent is limited to the repositories and accounts that token reaches. Gitea can also push events to a webhook URL when something happens in a repository.
How an app or AI agent connects to Gitea determines what it can reach. The main route is the REST API, and an official MCP server wraps the same operations for agents, each governed by the access token behind it and the scopes that token carries.
The REST API answers under the /api/v1 path of a Gitea instance and returns JSON. It is the main route for an app or AI agent, and a Swagger explorer is served at /api/swagger on the instance.
The Gitea project maintains an official MCP server at gitea.com/gitea/gitea-mcp. It lets an agent call Gitea through the Model Context Protocol over standard input and output or over HTTP, authenticating with a Gitea access token, and covers repositories, issues, pull requests, files, releases, and organization tools.
Webhooks deliver the chosen events to a receiver URL registered on a repository, such as a push or a pull request opening, so an integration is notified instead of polling. A secret on each hook lets the receiver confirm a delivery came from the instance.
A personal access token is the standard way to authenticate. It carries a chosen set of read and write scopes, so it can be limited to only the areas an integration needs, and it is sent in the Authorization header on each request.
Gitea is an OAuth2 provider, so an app can obtain a token on behalf of a user through an authorization flow. The resulting token is sent as a bearer token and, in recent releases, can request granular scopes rather than full access.
HTTP basic authentication with a username and password is supported, mainly to create the first access token. A token-based method is preferred for ongoing API use.
The Gitea API is split into areas an agent can act on, such as repositories, issues, pull requests, file contents, releases, and webhooks. Each area maps to its own token scope, and some grant access to far more than others.
List the repositories an account owns or an organization owns, read a single repository, create one for the current user or an organization, edit a repository's settings, and delete a repository.
List, read, create, and edit issues in a repository, and list and create their comments.
List, read, create, and edit pull requests, and merge a pull request into its base branch.
List a repository's branches, read a single branch, create a branch, and delete a branch.
List the commits on a repository and read a commit's combined status by branch, tag, or commit reference.
Read a file's contents at a path, create a file, update a file, and delete a file in a repository.
List a repository's releases, read the latest release, and create a release.
List and create a repository's labels, and list and create its milestones.
List a repository's webhooks, create one, and delete one.
Read the authenticated user's profile and read another user's profile by username.
List the authenticated user's organizations, read an organization's details, and edit its settings.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
RepositoriesList the repositories an account owns or an organization owns, read a single repository, create one for the current user or an organization, edit a repository's settings, and delete a repository.7 | ||||||
| GET | /user/repos | List the repositories the authenticated user owns. | read | read:repository | Current | |
Returns only the repositories the token's account owns. The read:repository scope covers read methods across the repository area. Acts onrepository Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org}/repos | List an organization's repositories. | read | read:repository | Current | |
Private repositories appear only when the token's account can see them. Acts onrepository Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo} | Get a repository's details. | read | read:repository | Current | |
Returns 404 rather than 403 for a private repository the token cannot see. Acts onrepository Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /user/repos | Create a repository owned by the authenticated user. | write | write:repository | Current | |
Creating a repository needs the write:repository scope. Acts onrepository Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orgs/{org}/repos | Create a repository in an organization. | write | write:repository | Current | |
The account must have rights to create repositories in the organization. Acts onrepository Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /repos/{owner}/{repo} | Edit a repository's properties. | write | write:repository | Current | |
Changes settings such as the description, default branch, and feature toggles. Acts onrepository Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /repos/{owner}/{repo} | Delete a repository. | write | write:repository | Current | |
Removes the repository and its history; the account must own or administer it. Acts onrepository Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IssuesList, read, create, and edit issues in a repository, and list and create their comments.5 | ||||||
| GET | /repos/{owner}/{repo}/issues | List a repository's issues. | read | read:issue | Current | |
Pull requests can also be returned here, filtered through the type parameter. Acts onissue Permission (capability) read:issueVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/issues/{index} | Get a single issue by its index. | read | read:issue | Current | |
The index is the issue number within the repository. Acts onissue Permission (capability) read:issueVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/issues | Create an issue. | write | write:issue | Current | |
Creating an issue needs the write:issue scope. Acts onissue Permission (capability) write:issueVersionAvailable since the API’s base version Webhook event issuesRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /repos/{owner}/{repo}/issues/{index} | Edit an issue's title, body, state, labels, or assignees. | write | write:issue | Current | |
Closing and reopening use the state field here. Acts onissue Permission (capability) write:issueVersionAvailable since the API’s base version Webhook event issuesRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/issues/{index}/comments | Add a comment to an issue or pull request. | write | write:issue | Current | |
The same endpoint serves pull request conversation comments. Acts oncomment Permission (capability) write:issueVersionAvailable since the API’s base version Webhook event issue_commentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Pull requestsList, read, create, and edit pull requests, and merge a pull request into its base branch.5 | ||||||
| GET | /repos/{owner}/{repo}/pulls | List a repository's pull requests. | read | read:repository | Current | |
Pull requests live in the repository area, so they use the repository scope. Acts onpull request Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/pulls/{index} | Get a single pull request. | read | read:repository | Current | |
The index is the pull request number within the repository. Acts onpull request Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/pulls | Create a pull request. | write | write:repository | Current | |
Opens a pull request from a head branch into a base branch. Acts onpull request Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event pull_requestRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /repos/{owner}/{repo}/pulls/{index} | Edit a pull request's title, body, state, or base branch. | write | write:repository | Current | |
Closing and reopening use the state field here. Acts onpull request Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event pull_requestRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/pulls/{index}/merge | Merge a pull request into its base branch. | write | write:repository | Current | |
Merging commits to the base branch. Returns 405 when the pull request is not mergeable. Acts onpull request Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event pull_requestRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BranchesList a repository's branches, read a single branch, create a branch, and delete a branch.3 | ||||||
| GET | /repos/{owner}/{repo}/branches | List a repository's branches. | read | read:repository | Current | |
Branches live in the repository area, so they use the repository scope. Acts onbranch Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/branches | Create a branch. | write | write:repository | Current | |
A new branch can be created from an existing branch. Acts onbranch Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event createRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /repos/{owner}/{repo}/branches/{branch} | Delete a specific branch from a repository. | write | write:repository | Current | |
A protected branch cannot be deleted through the API. Acts onbranch Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event deleteRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommitsList the commits on a repository and read a commit's combined status by branch, tag, or commit reference.2 | ||||||
| GET | /repos/{owner}/{repo}/commits | Get a list of all commits from a repository. | read | read:repository | Current | |
Can be filtered by branch, path, or author. Acts oncommit Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/commits/{ref}/status | Get a commit's combined status by branch, tag, or commit reference. | read | read:repository | Current | |
Combines the statuses reported against a commit into one overall state. Acts oncommit Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
File contentsRead a file's contents at a path, create a file, update a file, and delete a file in a repository.4 | ||||||
| GET | /repos/{owner}/{repo}/contents/{filepath} | Get the metadata and contents of a file in a repository. | read | read:repository | Current | |
Returns the file's content base64-encoded along with its metadata. Acts onfile Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/contents/{filepath} | Create a file in a repository. | write | write:repository | Current | |
Commits a new file with base64-encoded content to a branch. Acts onfile Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event pushRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /repos/{owner}/{repo}/contents/{filepath} | Update a file in a repository. | write | write:repository | Current | |
The existing file's sha must be supplied so the commit applies to the right version. Acts onfile Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event pushRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /repos/{owner}/{repo}/contents/{filepath} | Delete a file in a repository. | write | write:repository | Current | |
The file's sha must be supplied, and the deletion is committed to a branch. Acts onfile Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event pushRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReleasesList a repository's releases, read the latest release, and create a release.3 | ||||||
| GET | /repos/{owner}/{repo}/releases | List a repository's releases. | read | read:repository | Current | |
Releases live in the repository area, so they use the repository scope. Acts onrelease Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/releases/latest | Get the latest release of a repository. | read | read:repository | Current | |
Returns the most recent published release. Acts onrelease Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/releases | Create a release. | write | write:repository | Current | |
A release is tied to a git tag, which can be created with it. Acts onrelease Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook event releaseRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Labels & milestonesList and create a repository's labels, and list and create its milestones.4 | ||||||
| GET | /repos/{owner}/{repo}/labels | Get all of a repository's labels. | read | read:issue | Current | |
Labels are part of the issue area, so they use the issue scope. Acts onlabel Permission (capability) read:issueVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/labels | Create a label. | write | write:issue | Current | |
A label has a name and a color, and can then be applied to issues. Acts onlabel Permission (capability) write:issueVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/milestones | Get all of a repository's milestones. | read | read:issue | Current | |
Milestones are part of the issue area, so they use the issue scope. Acts onmilestone Permission (capability) read:issueVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/milestones | Create a milestone. | write | write:issue | Current | |
A milestone groups issues and pull requests toward a target. Acts onmilestone Permission (capability) write:issueVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList a repository's webhooks, create one, and delete one.3 | ||||||
| GET | /repos/{owner}/{repo}/hooks | List the webhooks in a repository. | read | read:repository | Current | |
Webhooks live in the repository area, so they use the repository scope. Acts onwebhook Permission (capability) read:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/hooks | Create a webhook on a repository. | write | write:repository | Current | |
Registers a receiver URL and the events to deliver, with an optional secret. Acts onwebhook Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /repos/{owner}/{repo}/hooks/{id} | Delete a webhook from a repository. | write | write:repository | Current | |
Stops further deliveries for the removed hook. Acts onwebhook Permission (capability) write:repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the authenticated user's profile and read another user's profile by username.2 | ||||||
| GET | /user | Get the authenticated user's profile. | read | read:user | Current | |
Identifies the account the token belongs to. Acts onuser Permission (capability) read:userVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/{username} | Get a user's profile by username. | read | read:user | Current | |
Returns the public profile fields for the named user. Acts onuser Permission (capability) read:userVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsList the authenticated user's organizations, read an organization's details, and edit its settings.3 | ||||||
| GET | /user/orgs | List the organizations the authenticated user belongs to. | read | read:organization | Current | |
Returns the organizations the token's account is a member of. Acts onorganization Permission (capability) read:organizationVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org} | Get an organization's details. | read | read:organization | Current | |
Returns the organization's public profile and settings the account can see. Acts onorganization Permission (capability) read:organizationVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /orgs/{org} | Edit an organization's settings. | write | write:organization | Current | |
The account must administer the organization. Acts onorganization Permission (capability) write:organizationVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Gitea can notify an app or AI agent when something happens in a repository, instead of the app repeatedly asking. Gitea posts the event payload to a webhook URL that has been registered on the repository for the chosen events, such as a push or a new pull request.
| Event | What it signals | Triggered by |
|---|---|---|
push | Fires when one or more commits are pushed to a branch of a repository. | In-app only |
issues | Fires on activity on an issue, such as opened, edited, closed, reopened, assigned, or labeled. | /repos/{owner}/{repo}/issues/repos/{owner}/{repo}/issues/{index} |
issue_comment | Fires when a comment is created, edited, or deleted on an issue or a pull request. | /repos/{owner}/{repo}/issues/{index}/comments |
pull_request | Fires on activity on a pull request, such as opened, edited, closed, reopened, or merged. | /repos/{owner}/{repo}/pulls/repos/{owner}/{repo}/pulls/{index}/repos/{owner}/{repo}/pulls/{index}/merge |
release | Fires when a release is published, updated, or deleted in a repository. | /repos/{owner}/{repo}/releases |
create | Fires when a branch or tag is created in a repository. | /repos/{owner}/{repo}/branches |
delete | Fires when a branch or tag is deleted in a repository. | /repos/{owner}/{repo}/branches/{branch} |
Gitea is self-hosted software, so how fast and how much an app or AI agent can call depends on the instance. There is no fixed request quota in the API itself, and pagination caps how many items each list call returns.
Gitea is self-hosted, so there is no fixed request quota set by the API itself. Each instance decides its own ceilings, and an administrator can place rate limiting in front of Gitea at the reverse proxy or with the instance configuration. An integration cannot assume a published per-hour limit the way a hosted API would set one; the effective limit is whatever the instance and its operator allow.
List endpoints page through the page parameter, which is 1-based, and the limit parameter for the page size. A Link response header carries the next, previous, and last page URLs when more than one page exists, and the X-Total-Count header reports the total number of items. The default and maximum page size are set per instance, so an integration should follow the Link header rather than assume a fixed size.
Requests and responses are JSON. List sizes are bounded by the per-instance page-size limit, and file contents and attachment endpoints are subject to the instance's configured maximum blob and upload sizes. There is no single fixed payload limit across the API, since each instance sets its own.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication is missing or the access token is invalid or expired. | Send a valid token in the Authorization header, and check it has not been revoked. |
| 403 | Forbidden | The request is authenticated but the token lacks the scope or the account lacks the permission for this action, such as a read-only token attempting a write. | Grant the token the required scope, such as write:repository or write:issue, or use an account with access. |
| 404 | Not Found | The resource does not exist, or the token cannot see a private resource. Gitea returns 404 rather than 403 for a private repository the token cannot access, so it does not confirm the repository exists. | Confirm the owner and repository in the path, and that the token has access to it. |
| 409 | Conflict | The request conflicts with the current state, such as merging a pull request that is not mergeable or creating something that already exists. | Refetch the current state and retry once the conflict is resolved. |
| 422 | Unprocessable Entity | Validation failed: the request was well-formed but a field is missing or invalid. The response body holds a message describing the problem. | Read the message field, correct the named field, and resend. |
The Gitea API has a single version, v1, served under a stable path. New methods and fields ship with each Gitea server release rather than through a new API version, and breaking changes are called out in the release notes.
Gitea serves one API version, v1, under a stable base path. Rather than minting a new API version for changes, Gitea ships new methods and fields with each server release and notes breaking changes in that release's changelog. The version below is the current API version, and the timeline lists notable server releases that changed the API.
Gitea 1.26.0 was the largest release in the project's history, with API changes among them. Breaking changes for integrations include corrected Swagger annotations for enums, status codes, and notification state, and the removal of the GET registration-token method. The page list size for unadopted repositories was bounded to avoid unbounded responses. Patch releases 1.26.3 and 1.26.4 followed.
Gitea 1.25.0 continued to extend the API alongside server features. New methods and fields shipped with the release, following the project's model of evolving the v1 API through server releases rather than a new API version.
An integration tracks the Gitea server version it runs against, since newer methods appear as the server is upgraded.
Gitea changelog ↗Bollard AI sits between a team's AI agents and Gitea. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.