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.

id · integer · required

The unique identifier of the team

name · string · required

The name of the team

description · string

The description of the team

organization · object

The organization that the team belongs to

includes_all_repositories · boolean

Whether the team has access to all repositories in the organization

permission · string

Team permission level: none, read, write, admin, or owner

units_map · object

Fine-grained permissions for different repository units (e.g., repo.code, repo.issues, repo.wiki)

can_create_org_repo · boolean

Whether the team can create repositories in the organization

List Organization Teams

GET /orgs/{org}/teams

List all teams in an organization

Path Parameters

org · string · required

The name of the organization

Query Parameters

page · integer

Page number of results to return (1-based)

limit · integer

Page size of results

Example Request

curl -X GET "https://gitea.example.com/api/v1/orgs/myorg/teams" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

Response

[
  {
    "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

GET /teams/{id}

Get details about a specific team by ID

Path Parameters

id · integer · required

The ID of the team to retrieve

Example Request

curl -X GET "https://gitea.example.com/api/v1/teams/1" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

Response

{
  "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

POST /orgs/{org}/teams

Create a new team in an organization

Path Parameters

org · string · required

The name of the organization

Request Body

name · string · required

The name of the team (max 255 characters)

description · string

The description of the team (max 255 characters)

includes_all_repositories · boolean · default: "false"

Whether the team has access to all repositories in the organization

permission · string · default: "read"

Team permission level: read, write, or admin

units_map · object

Fine-grained permissions for repository units. Example: {"repo.code": "read", "repo.issues": "write"}

can_create_org_repo · boolean · default: "false"

Whether the team can create repositories in the organization

Example Request

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

{
  "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

PATCH /teams/{id}

Update an existing team’s information

Path Parameters

id · integer · required

The ID of the team to update

Request Body

name · string

The name of the team

description · string

The description of the team

includes_all_repositories · boolean

Whether the team has access to all repositories

permission · string

Team permission level: read, write, or admin

units_map · object

Fine-grained permissions for repository units

can_create_org_repo · boolean

Whether the team can create repositories

Example Request

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

DELETE /teams/{id}

Delete a team from an organization

Path Parameters

id · integer · required

The ID of the team to delete

Example Request

curl -X DELETE "https://gitea.example.com/api/v1/teams/1" \
  -H "Authorization: token YOUR_TOKEN"

Team Members

List Members

Get all members of a team

Get Member

Check if a user is a team member

Add Member

Add a user to a team

Remove Member

Remove a user from a team

List Team Members

GET /teams/{id}/members

List all members of a team

Path Parameters

id · integer · required

The ID of the team

Query Parameters

page · integer

Page number of results to return (1-based)

limit · integer

Page size of results

Example Request

curl -X GET "https://gitea.example.com/api/v1/teams/1/members" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

Get Team Member

GET /teams/{id}/members/{username}

Check if a specific user is a member of the team

Path Parameters

id · integer · required

The ID of the team

username · string · required

The username of the user to check

Example Request

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

PUT /teams/{id}/members/{username}

Add a user to a team

Path Parameters

id · integer · required

The ID of the team

username · string · required

The username of the user to add

Example Request

curl -X PUT "https://gitea.example.com/api/v1/teams/1/members/john" \
  -H "Authorization: token YOUR_TOKEN"

Remove Team Member

DELETE /teams/{id}/members/{username}

Remove a user from a team

Path Parameters

id · integer · required

The ID of the team

username · string · required

The username of the user to remove

Example Request

curl -X DELETE "https://gitea.example.com/api/v1/teams/1/members/john" \
  -H "Authorization: token YOUR_TOKEN"

Team Repositories

List Repositories

Get all repositories assigned to a team

Get Repository

Check if a repository is assigned to the team

Add Repository

Assign a repository to a team

Remove Repository

Remove a repository from a team

List Team Repositories

GET /teams/{id}/repos

List all repositories that a team has access to

Path Parameters

id · integer · required

The ID of the team

Query Parameters

page · integer

Page number of results to return (1-based)

limit · integer

Page size of results

Example Request

curl -X GET "https://gitea.example.com/api/v1/teams/1/repos" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

Get Team Repository

GET /teams/{id}/repos/{org}/{repo}

Check if a specific repository is assigned to the team

Path Parameters

id · integer · required

The ID of the team

org · string · required

The organization that owns the repository

repo · string · required

The name of the repository

Example Request

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

PUT /teams/{id}/repos/{org}/{repo}

Add a repository to a team

Path Parameters

id · integer · required

The ID of the team

org · string · required

The organization that owns the repository

repo · string · required

The name of the repository to add

Example Request

curl -X PUT "https://gitea.example.com/api/v1/teams/1/repos/myorg/myrepo" \
  -H "Authorization: token YOUR_TOKEN"

Remove Team Repository

DELETE /teams/{id}/repos/{org}/{repo}

Remove a repository from a team (does not delete the repository)

Path Parameters

id · integer · required

The ID of the team

org · string · required

The organization that owns the repository

repo · string · required

The name of the repository to remove

Example Request

curl -X DELETE "https://gitea.example.com/api/v1/teams/1/repos/myorg/myrepo" \
  -H "Authorization: token YOUR_TOKEN"

Search Teams

GET /orgs/{org}/teams/search

Search for teams within an organization

Path Parameters

org · string · required

The name of the organization

Query Parameters

q · string

Keywords to search for

include_desc · boolean · default: "true"

Include search within team descriptions

page · integer

Page number of results to return (1-based)

limit · integer

Page size of results

Example Request

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

{
  "ok": true,
  "data": [
    {
      "id": 1,
      "name": "Developers",
      "description": "Development team",
      "permission": "write"
    }
  ]
}

List User Teams

GET /user/teams

List all teams that the authenticated user belongs to

Query Parameters

page · integer

Page number of results to return (1-based)

limit · integer

Page size of results

Example Request

curl -X GET "https://gitea.example.com/api/v1/user/teams" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

Activity Feeds

GET /teams/{id}/activities/feeds

List a team’s activity feeds

Path Parameters

id · integer · required

The ID of the team

Query Parameters

date · string

The date of the activities to be found (format: YYYY-MM-DD)

page · integer

Page number of results to return (1-based)

limit · integer

Page size of results

Example Request

curl -X GET "https://gitea.example.com/api/v1/teams/1/activities/feeds" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"