Skip to main content
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"

Build docs developers (and LLMs) love

Get started for freeTalk to us