Repository Endpoints

Manage repositories via the Gitea API

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

curl -X GET "https://gitea.example.com/api/v1/repos/search?q=example&sort=stars&order=desc" \
  -H "Authorization: token YOUR_TOKEN"

{
  "ok": true,
  "data": [
    {
      "id": 1,
      "name": "example-repo",
      "full_name": "user/example-repo",
      "description": "An example repository",
      "private": false,
      "fork": false,
      "stars_count": 42,
      "forks_count": 7,
      "default_branch": "main",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-03-10T00:00:00Z"
    }
  ]
}

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

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"
  }'

{
  "id": 123,
  "name": "my-new-repo",
  "full_name": "username/my-new-repo",
  "description": "My awesome new repository",
  "private": false,
  "fork": false,
  "empty": false,
  "default_branch": "main",
  "created_at": "2024-03-10T12:00:00Z",
  "updated_at": "2024-03-10T12:00:00Z"
}

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

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

curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name" \
  -H "Authorization: token YOUR_TOKEN"

{
  "id": 123,
  "owner": {
    "id": 1,
    "login": "username",
    "full_name": "User Name"
  },
  "name": "repo-name",
  "full_name": "username/repo-name",
  "description": "Repository description",
  "private": false,
  "fork": false,
  "html_url": "https://gitea.example.com/username/repo-name",
  "ssh_url": "[e-mail]:username/repo-name.git",
  "clone_url": "https://gitea.example.com/username/repo-name.git",
  "default_branch": "main",
  "stars_count": 10,
  "forks_count": 2,
  "permissions": {
    "admin": true,
    "push": true,
    "pull": true
  }
}

Get Repository by ID

Get a repository by its ID.

GET /repositories/{id}

Path Parameters

id · integer · required

ID of the repository

cURL

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

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
  }'

{
  "id": 123,
  "name": "repo-name",
  "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

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

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
  }'

{
  "id": 456,
  "name": "my-new-project",
  "full_name": "username/my-new-project",
  "description": "Project from template",
  "private": false,
  "template": false,
  "created_at": "2024-03-10T12:00:00Z"
}

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

curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/activities/feeds?date=2024-03-10" \
  -H "Authorization: token YOUR_TOKEN"

[
  {
    "id": 1,
    "user_id": 1,
    "op_type": "commit_repo",
    "act_user": {
      "id": 1,
      "login": "username"
    },
    "repo": {
      "id": 123,
      "name": "repo-name"
    },
    "created": "2024-03-10T12:00:00Z"
  }
]