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

# Teams API

> Manage organization teams through the Gitea API

The Teams API allows you to create and manage teams within organizations. Teams provide fine-grained access control for organization repositories.

## Team Object

The Team object represents a team within an organization.

<ResponseField name="id" type="integer" required>
  The unique identifier of the team
</ResponseField>

<ResponseField name="name" type="string" required>
  The name of the team
</ResponseField>

<ResponseField name="description" type="string">
  The description of the team
</ResponseField>

<ResponseField name="organization" type="object">
  The organization that the team belongs to
</ResponseField>

<ResponseField name="includes_all_repositories" type="boolean">
  Whether the team has access to all repositories in the organization
</ResponseField>

<ResponseField name="permission" type="string">
  Team permission level: `none`, `read`, `write`, `admin`, or `owner`
</ResponseField>

<ResponseField name="units_map" type="object">
  Fine-grained permissions for different repository units (e.g., `repo.code`, `repo.issues`, `repo.wiki`)
</ResponseField>

<ResponseField name="can_create_org_repo" type="boolean">
  Whether the team can create repositories in the organization
</ResponseField>

## List Organization Teams

<Card title="GET /orgs/{org}/teams" icon="users">
  List all teams in an organization
</Card>

### Path Parameters

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

### Query Parameters

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

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

### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/orgs/myorg/teams" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Response

```json theme={null}
[
  {
    "id": 1,
    "name": "Developers",
    "description": "Development team",
    "organization": {
      "id": 1,
      "name": "myorg",
      "full_name": "My Organization"
    },
    "includes_all_repositories": false,
    "permission": "write",
    "units_map": {
      "repo.code": "write",
      "repo.issues": "write",
      "repo.pulls": "write"
    },
    "can_create_org_repo": false
  }
]
```

## Get a Team

<Card title="GET /teams/{id}" icon="user-group">
  Get details about a specific team by ID
</Card>

### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the team to retrieve
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/teams/1" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Response

```json theme={null}
{
  "id": 1,
  "name": "Developers",
  "description": "Development team",
  "organization": {
    "id": 1,
    "name": "myorg",
    "full_name": "My Organization"
  },
  "includes_all_repositories": false,
  "permission": "write",
  "units_map": {
    "repo.code": "write",
    "repo.issues": "write",
    "repo.pulls": "write"
  },
  "can_create_org_repo": false
}
```

## Create a Team

<Card title="POST /orgs/{org}/teams" icon="plus">
  Create a new team in an organization
</Card>

### Path Parameters

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

### Request Body

<ParamField body="name" type="string" required>
  The name of the team (max 255 characters)
</ParamField>

<ParamField body="description" type="string">
  The description of the team (max 255 characters)
</ParamField>

<ParamField body="includes_all_repositories" type="boolean" default="false">
  Whether the team has access to all repositories in the organization
</ParamField>

<ParamField body="permission" type="string" default="read">
  Team permission level: `read`, `write`, or `admin`
</ParamField>

<ParamField body="units_map" type="object">
  Fine-grained permissions for repository units. Example: `{"repo.code": "read", "repo.issues": "write"}`
</ParamField>

<ParamField body="can_create_org_repo" type="boolean" default="false">
  Whether the team can create repositories in the organization
</ParamField>

### Example Request

```bash theme={null}
curl -X POST "https://gitea.example.com/api/v1/orgs/myorg/teams" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Developers",
    "description": "Development team",
    "permission": "write",
    "units_map": {
      "repo.code": "write",
      "repo.issues": "write",
      "repo.pulls": "write",
      "repo.wiki": "read"
    },
    "can_create_org_repo": false
  }'
```

### Response

```json theme={null}
{
  "id": 1,
  "name": "Developers",
  "description": "Development team",
  "organization": {
    "id": 1,
    "name": "myorg"
  },
  "includes_all_repositories": false,
  "permission": "write",
  "units_map": {
    "repo.code": "write",
    "repo.issues": "write",
    "repo.pulls": "write",
    "repo.wiki": "read"
  },
  "can_create_org_repo": false
}
```

## Update a Team

<Card title="PATCH /teams/{id}" icon="pen-to-square">
  Update an existing team's information
</Card>

### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the team to update
</ParamField>

### Request Body

<ParamField body="name" type="string">
  The name of the team
</ParamField>

<ParamField body="description" type="string">
  The description of the team
</ParamField>

<ParamField body="includes_all_repositories" type="boolean">
  Whether the team has access to all repositories
</ParamField>

<ParamField body="permission" type="string">
  Team permission level: `read`, `write`, or `admin`
</ParamField>

<ParamField body="units_map" type="object">
  Fine-grained permissions for repository units
</ParamField>

<ParamField body="can_create_org_repo" type="boolean">
  Whether the team can create repositories
</ParamField>

### Example Request

```bash theme={null}
curl -X PATCH "https://gitea.example.com/api/v1/teams/1" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated development team",
    "permission": "admin"
  }'
```

## Delete a Team

<Card title="DELETE /teams/{id}" icon="trash">
  Delete a team from an organization
</Card>

### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the team to delete
</ParamField>

### Example Request

```bash theme={null}
curl -X DELETE "https://gitea.example.com/api/v1/teams/1" \
  -H "Authorization: token YOUR_TOKEN"
```

## Team Members

<CardGroup cols={2}>
  <Card title="List Members" icon="users" href="#list-team-members">
    Get all members of a team
  </Card>

  <Card title="Get Member" icon="user" href="#get-team-member">
    Check if a user is a team member
  </Card>

  <Card title="Add Member" icon="user-plus" href="#add-team-member">
    Add a user to a team
  </Card>

  <Card title="Remove Member" icon="user-minus" href="#remove-team-member">
    Remove a user from a team
  </Card>
</CardGroup>

### List Team Members

<Card title="GET /teams/{id}/members" icon="users">
  List all members of a team
</Card>

#### Path Parameters

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

#### Query Parameters

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

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

#### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/teams/1/members" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Get Team Member

<Card title="GET /teams/{id}/members/{username}" icon="user">
  Check if a specific user is a member of the team
</Card>

#### Path Parameters

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

<ParamField path="username" type="string" required>
  The username of the user to check
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/teams/1/members/john" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Add Team Member

<Card title="PUT /teams/{id}/members/{username}" icon="user-plus">
  Add a user to a team
</Card>

#### Path Parameters

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

<ParamField path="username" type="string" required>
  The username of the user to add
</ParamField>

#### Example Request

```bash theme={null}
curl -X PUT "https://gitea.example.com/api/v1/teams/1/members/john" \
  -H "Authorization: token YOUR_TOKEN"
```

### Remove Team Member

<Card title="DELETE /teams/{id}/members/{username}" icon="user-minus">
  Remove a user from a team
</Card>

#### Path Parameters

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

<ParamField path="username" type="string" required>
  The username of the user to remove
</ParamField>

#### Example Request

```bash theme={null}
curl -X DELETE "https://gitea.example.com/api/v1/teams/1/members/john" \
  -H "Authorization: token YOUR_TOKEN"
```

## Team Repositories

<CardGroup cols={2}>
  <Card title="List Repositories" icon="folder" href="#list-team-repositories">
    Get all repositories assigned to a team
  </Card>

  <Card title="Get Repository" icon="folder-open" href="#get-team-repository">
    Check if a repository is assigned to the team
  </Card>

  <Card title="Add Repository" icon="folder-plus" href="#add-team-repository">
    Assign a repository to a team
  </Card>

  <Card title="Remove Repository" icon="folder-minus" href="#remove-team-repository">
    Remove a repository from a team
  </Card>
</CardGroup>

### List Team Repositories

<Card title="GET /teams/{id}/repos" icon="folder">
  List all repositories that a team has access to
</Card>

#### Path Parameters

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

#### Query Parameters

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

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

#### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/teams/1/repos" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Get Team Repository

<Card title="GET /teams/{id}/repos/{org}/{repo}" icon="folder-open">
  Check if a specific repository is assigned to the team
</Card>

#### Path Parameters

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

<ParamField path="org" type="string" required>
  The organization that owns the repository
</ParamField>

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

#### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/teams/1/repos/myorg/myrepo" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Add Team Repository

<Card title="PUT /teams/{id}/repos/{org}/{repo}" icon="folder-plus">
  Add a repository to a team
</Card>

#### Path Parameters

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

<ParamField path="org" type="string" required>
  The organization that owns the repository
</ParamField>

<ParamField path="repo" type="string" required>
  The name of the repository to add
</ParamField>

#### Example Request

```bash theme={null}
curl -X PUT "https://gitea.example.com/api/v1/teams/1/repos/myorg/myrepo" \
  -H "Authorization: token YOUR_TOKEN"
```

### Remove Team Repository

<Card title="DELETE /teams/{id}/repos/{org}/{repo}" icon="folder-minus">
  Remove a repository from a team (does not delete the repository)
</Card>

#### Path Parameters

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

<ParamField path="org" type="string" required>
  The organization that owns the repository
</ParamField>

<ParamField path="repo" type="string" required>
  The name of the repository to remove
</ParamField>

#### Example Request

```bash theme={null}
curl -X DELETE "https://gitea.example.com/api/v1/teams/1/repos/myorg/myrepo" \
  -H "Authorization: token YOUR_TOKEN"
```

## Search Teams

<Card title="GET /orgs/{org}/teams/search" icon="magnifying-glass">
  Search for teams within an organization
</Card>

### Path Parameters

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

### Query Parameters

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

<ParamField query="include_desc" type="boolean" default="true">
  Include search within team descriptions
</ParamField>

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

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

### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/orgs/myorg/teams/search?q=dev&include_desc=true" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Response

```json theme={null}
{
  "ok": true,
  "data": [
    {
      "id": 1,
      "name": "Developers",
      "description": "Development team",
      "permission": "write"
    }
  ]
}
```

## List User Teams

<Card title="GET /user/teams" icon="user-group">
  List all teams that the authenticated user belongs to
</Card>

### Query Parameters

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

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

### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/user/teams" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

## Activity Feeds

<Card title="GET /teams/{id}/activities/feeds" icon="rss">
  List a team's activity feeds
</Card>

### Path Parameters

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

### Query Parameters

<ParamField query="date" type="string">
  The date of the activities to be found (format: YYYY-MM-DD)
</ParamField>

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

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

### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/teams/1/activities/feeds" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```