Skip to main content
The Gitea API provides comprehensive endpoints for managing repositories, including creating, retrieving, updating, and deleting repositories.

​
Search Repositories

Search for repositories based on various criteria. 
GET /repos/search

​
Query Parameters

​
q
string
Keyword to search for
​
topic
boolean
Limit search to repositories with keyword as topic
​
includeDesc
boolean
Include search of keyword within repository description
​
uid
integer
Search only for repos that the user with the given id owns or contributes to
​
private
boolean
default:"true"
Include private repositories this user has access to
​
archived
boolean
Show only archived, non-archived or all repositories
​
mode
string
Type of repository to search for. Supported values: fork, source, mirror, collaborative
​
sort
string
default:"alpha"
Sort repos by attribute. Supported values: alpha, created, updated, size, git_size, lfs_size, stars, forks, id
​
order
string
default:"asc"
Sort order: asc (ascending) or desc (descending)
​
page
integer
default:"1"
Page number of results to return (1-based)
​
limit
integer
Page size of results

​
Response

​
ok
boolean
Indicates if the search was successful
​
data
array
Array of repository objects matching the search criteria
​
id
integer
Repository ID
​
name
string
Repository name
​
full_name
string
Full repository name including owner
​
description
string
Repository description
​
private
boolean
Whether the repository is private
​
fork
boolean
Whether the repository is a fork
​
stars_count
integer
Number of stars
​
forks_count
integer
Number of forks
curl -X GET "https://gitea.example.com/api/v1/repos/search?q=example&sort=stars&order=desc" \
  -H "Authorization: token YOUR_TOKEN"

​
Create Repository

Create a new repository for the authenticated user. 
POST /user/repos

​
Request Body

​
name
string
required
Name of the repository to create (unique)
​
description
string
Description of the repository
​
private
boolean
default:"false"
Whether the repository is private
​
auto_init
boolean
default:"false"
Whether the repository should be auto-initialized
​
gitignores
string
Gitignores to use
​
license
string
License to use
​
readme
string
default:"Default"
Readme template to use
​
default_branch
string
Default branch name (used when initializing)
​
trust_model
string
Trust model. Supported values: default, collaborator, committer, collaboratorcommitter
curl -X POST "https://gitea.example.com/api/v1/user/repos" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-repo",
    "description": "My awesome new repository",
    "private": false,
    "auto_init": true,
    "license": "MIT",
    "readme": "Default"
  }'

​
Create Organization Repository

Create a new repository in an organization. 
POST /orgs/{org}/repos

​
Path Parameters

​
org
string
required
Name of the organization

​
Request Body

Same as Create Repository endpoint. 
curl -X POST "https://gitea.example.com/api/v1/orgs/my-org/repos" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org-repo",
    "description": "Organization repository",
    "private": true
  }'

​
Get Repository

Get a repository by owner and repository name. 
GET /repos/{owner}/{repo}

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository

​
Response

​
id
integer
Repository ID
​
name
string
Repository name
​
full_name
string
Full repository name (owner/repo)
​
description
string
Repository description
​
private
boolean
Whether the repository is private
​
fork
boolean
Whether the repository is a fork
​
html_url
string
Web URL to view the repository
​
clone_url
string
HTTPS clone URL
​
ssh_url
string
SSH clone URL
​
default_branch
string
Default branch name
​
permissions
object
User permissions for this repository
​
admin
boolean
Whether the user is an administrator
​
push
boolean
Whether the user can push
​
pull
boolean
Whether the user can pull
curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name" \
  -H "Authorization: token YOUR_TOKEN"

​
Get Repository by ID

Get a repository by its ID. 
GET /repositories/{id}

​
Path Parameters

​
id
integer
required
ID of the repository
curl -X GET "https://gitea.example.com/api/v1/repositories/123" \
  -H "Authorization: token YOUR_TOKEN"

​
Update Repository

Edit a repository’s properties. Only fields that are set will be changed. 
PATCH /repos/{owner}/{repo}

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository

​
Request Body

​
name
string
New name for the repository
​
description
string
New description
​
website
string
Repository website URL
​
private
boolean
Make repository private or public
​
default_branch
string
Set default branch
​
archived
boolean
Archive or unarchive the repository
​
has_issues
boolean
Enable or disable issues
​
has_wiki
boolean
Enable or disable wiki
​
has_pull_requests
boolean
Enable or disable pull requests
curl -X PATCH "https://gitea.example.com/api/v1/repos/username/repo-name" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "private": true,
    "has_issues": true
  }'

​
Delete Repository

Delete a repository permanently. 
DELETE /repos/{owner}/{repo}

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository to delete
curl -X DELETE "https://gitea.example.com/api/v1/repos/username/repo-name" \
  -H "Authorization: token YOUR_TOKEN"
Deleting a repository is permanent and cannot be undone. All issues, pull requests, releases, and other data will be deleted.

​
Generate Repository from Template

Create a repository from a template repository. 
POST /repos/{template_owner}/{template_repo}/generate

​
Path Parameters

​
template_owner
string
required
Owner of the template repository
​
template_repo
string
required
Name of the template repository

​
Request Body

​
name
string
required
Name of the new repository
​
owner
string
Owner of the new repository (defaults to authenticated user)
​
description
string
Description of the new repository
​
private
boolean
Whether the new repository should be private
​
git_content
boolean
default:"true"
Include git content from template
​
topics
boolean
default:"true"
Include topics from template
​
git_hooks
boolean
default:"false"
Include git hooks from template
​
webhooks
boolean
default:"false"
Include webhooks from template
​
avatar
boolean
default:"false"
Include avatar from template
​
labels
boolean
default:"true"
Include labels from template
curl -X POST "https://gitea.example.com/api/v1/repos/template-user/template-repo/generate" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-project",
    "description": "Project from template",
    "private": false,
    "git_content": true,
    "topics": true
  }'

​
List Repository Activity Feeds

Get activity feeds for a repository. 
GET /repos/{owner}/{repo}/activities/feeds

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository

​
Query Parameters

​
date
string
Date of activities to find (format: YYYY-MM-DD)
​
page
integer
default:"1"
Page number of results
​
limit
integer
Page size of results
curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/activities/feeds?date=2024-03-10" \
  -H "Authorization: token YOUR_TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us