> ## 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.

# 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.

```bash theme={null}
GET /repos/search
```

### Query Parameters

<ParamField query="q" type="string">
  Keyword to search for
</ParamField>

<ParamField query="topic" type="boolean">
  Limit search to repositories with keyword as topic
</ParamField>

<ParamField query="includeDesc" type="boolean">
  Include search of keyword within repository description
</ParamField>

<ParamField query="uid" type="integer">
  Search only for repos that the user with the given id owns or contributes to
</ParamField>

<ParamField query="private" type="boolean" default="true">
  Include private repositories this user has access to
</ParamField>

<ParamField query="archived" type="boolean">
  Show only archived, non-archived or all repositories
</ParamField>

<ParamField query="mode" type="string">
  Type of repository to search for. Supported values: `fork`, `source`, `mirror`, `collaborative`
</ParamField>

<ParamField query="sort" type="string" default="alpha">
  Sort repos by attribute. Supported values: `alpha`, `created`, `updated`, `size`, `git_size`, `lfs_size`, `stars`, `forks`, `id`
</ParamField>

<ParamField query="order" type="string" default="asc">
  Sort order: `asc` (ascending) or `desc` (descending)
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number of results to return (1-based)
</ParamField>

<ParamField query="limit" type="integer">
  Page size of results
</ParamField>

### Response

<ResponseField name="ok" type="boolean">
  Indicates if the search was successful
</ResponseField>

<ResponseField name="data" type="array">
  Array of repository objects matching the search criteria

  <ResponseField name="id" type="integer">
    Repository ID
  </ResponseField>

  <ResponseField name="name" type="string">
    Repository name
  </ResponseField>

  <ResponseField name="full_name" type="string">
    Full repository name including owner
  </ResponseField>

  <ResponseField name="description" type="string">
    Repository description
  </ResponseField>

  <ResponseField name="private" type="boolean">
    Whether the repository is private
  </ResponseField>

  <ResponseField name="fork" type="boolean">
    Whether the repository is a fork
  </ResponseField>

  <ResponseField name="stars_count" type="integer">
    Number of stars
  </ResponseField>

  <ResponseField name="forks_count" type="integer">
    Number of forks
  </ResponseField>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://gitea.example.com/api/v1/repos/search?q=example&sort=stars&order=desc" \
    -H "Authorization: token YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

## Create Repository

Create a new repository for the authenticated user.

```bash theme={null}
POST /user/repos
```

### Request Body

<ParamField body="name" type="string" required>
  Name of the repository to create (unique)
</ParamField>

<ParamField body="description" type="string">
  Description of the repository
</ParamField>

<ParamField body="private" type="boolean" default="false">
  Whether the repository is private
</ParamField>

<ParamField body="auto_init" type="boolean" default="false">
  Whether the repository should be auto-initialized
</ParamField>

<ParamField body="gitignores" type="string">
  Gitignores to use
</ParamField>

<ParamField body="license" type="string">
  License to use
</ParamField>

<ParamField body="readme" type="string" default="Default">
  Readme template to use
</ParamField>

<ParamField body="default_branch" type="string">
  Default branch name (used when initializing)
</ParamField>

<ParamField body="trust_model" type="string">
  Trust model. Supported values: `default`, `collaborator`, `committer`, `collaboratorcommitter`
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

## Create Organization Repository

Create a new repository in an organization.

```bash theme={null}
POST /orgs/{org}/repos
```

### Path Parameters

<ParamField path="org" type="string" required>
  Name of the organization
</ParamField>

### Request Body

Same as Create Repository endpoint.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

## Get Repository

Get a repository by owner and repository name.

```bash theme={null}
GET /repos/{owner}/{repo}
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

### Response

<ResponseField name="id" type="integer">
  Repository ID
</ResponseField>

<ResponseField name="name" type="string">
  Repository name
</ResponseField>

<ResponseField name="full_name" type="string">
  Full repository name (owner/repo)
</ResponseField>

<ResponseField name="description" type="string">
  Repository description
</ResponseField>

<ResponseField name="private" type="boolean">
  Whether the repository is private
</ResponseField>

<ResponseField name="fork" type="boolean">
  Whether the repository is a fork
</ResponseField>

<ResponseField name="html_url" type="string">
  Web URL to view the repository
</ResponseField>

<ResponseField name="clone_url" type="string">
  HTTPS clone URL
</ResponseField>

<ResponseField name="ssh_url" type="string">
  SSH clone URL
</ResponseField>

<ResponseField name="default_branch" type="string">
  Default branch name
</ResponseField>

<ResponseField name="permissions" type="object">
  User permissions for this repository

  <ResponseField name="admin" type="boolean">
    Whether the user is an administrator
  </ResponseField>

  <ResponseField name="push" type="boolean">
    Whether the user can push
  </ResponseField>

  <ResponseField name="pull" type="boolean">
    Whether the user can pull
  </ResponseField>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name" \
    -H "Authorization: token YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "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": "git@gitea.example.com: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
    }
  }
  ```
</CodeGroup>

## Get Repository by ID

Get a repository by its ID.

```bash theme={null}
GET /repositories/{id}
```

### Path Parameters

<ParamField path="id" type="integer" required>
  ID of the repository
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://gitea.example.com/api/v1/repositories/123" \
    -H "Authorization: token YOUR_TOKEN"
  ```
</CodeGroup>

## Update Repository

Edit a repository's properties. Only fields that are set will be changed.

```bash theme={null}
PATCH /repos/{owner}/{repo}
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

### Request Body

<ParamField body="name" type="string">
  New name for the repository
</ParamField>

<ParamField body="description" type="string">
  New description
</ParamField>

<ParamField body="website" type="string">
  Repository website URL
</ParamField>

<ParamField body="private" type="boolean">
  Make repository private or public
</ParamField>

<ParamField body="default_branch" type="string">
  Set default branch
</ParamField>

<ParamField body="archived" type="boolean">
  Archive or unarchive the repository
</ParamField>

<ParamField body="has_issues" type="boolean">
  Enable or disable issues
</ParamField>

<ParamField body="has_wiki" type="boolean">
  Enable or disable wiki
</ParamField>

<ParamField body="has_pull_requests" type="boolean">
  Enable or disable pull requests
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```json Response theme={null}
  {
    "id": 123,
    "name": "repo-name",
    "description": "Updated description",
    "private": true,
    "has_issues": true
  }
  ```
</CodeGroup>

## Delete Repository

Delete a repository permanently.

```bash theme={null}
DELETE /repos/{owner}/{repo}
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository to delete
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://gitea.example.com/api/v1/repos/username/repo-name" \
    -H "Authorization: token YOUR_TOKEN"
  ```
</CodeGroup>

<Note>
  Deleting a repository is permanent and cannot be undone. All issues, pull requests, releases, and other data will be deleted.
</Note>

## Generate Repository from Template

Create a repository from a template repository.

```bash theme={null}
POST /repos/{template_owner}/{template_repo}/generate
```

### Path Parameters

<ParamField path="template_owner" type="string" required>
  Owner of the template repository
</ParamField>

<ParamField path="template_repo" type="string" required>
  Name of the template repository
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  Name of the new repository
</ParamField>

<ParamField body="owner" type="string">
  Owner of the new repository (defaults to authenticated user)
</ParamField>

<ParamField body="description" type="string">
  Description of the new repository
</ParamField>

<ParamField body="private" type="boolean">
  Whether the new repository should be private
</ParamField>

<ParamField body="git_content" type="boolean" default="true">
  Include git content from template
</ParamField>

<ParamField body="topics" type="boolean" default="true">
  Include topics from template
</ParamField>

<ParamField body="git_hooks" type="boolean" default="false">
  Include git hooks from template
</ParamField>

<ParamField body="webhooks" type="boolean" default="false">
  Include webhooks from template
</ParamField>

<ParamField body="avatar" type="boolean" default="false">
  Include avatar from template
</ParamField>

<ParamField body="labels" type="boolean" default="true">
  Include labels from template
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```json Response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

## List Repository Activity Feeds

Get activity feeds for a repository.

```bash theme={null}
GET /repos/{owner}/{repo}/activities/feeds
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

### Query Parameters

<ParamField query="date" type="string">
  Date of activities to find (format: YYYY-MM-DD)
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number of results
</ParamField>

<ParamField query="limit" type="integer">
  Page size of results
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/activities/feeds?date=2024-03-10" \
    -H "Authorization: token YOUR_TOKEN"
  ```

  ```json Response theme={null}
  [
    {
      "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"
    }
  ]
  ```
</CodeGroup>