# Organization Teams API

Base URL: `${FORGEJO_URL}/api/v1`

## List Teams

```
GET /orgs/{org}/teams
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/teams?page=1&limit=20"
```

---

## Create Team

```
POST /orgs/{org}/teams
```

### CreateTeamOption

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | yes | Team name |
| description | string | no | Team description |
| permission | string | no | Permission level: `read`, `write`, `admin`, `owner` |
| can_create_org_repo | boolean | no | Members can create repos in org |
| includes_all_repositories | boolean | no | Team has access to all org repos |
| units | array of string | no | Unit access list (see below) |
| units_map | object | no | Map of unit name to permission string |

### Available Units

| Unit | Description |
|------|-------------|
| `repo.code` | Repository code |
| `repo.issues` | Issues |
| `repo.ext_issues` | External issue tracker |
| `repo.wiki` | Wiki |
| `repo.pulls` | Pull requests |
| `repo.releases` | Releases |
| `repo.projects` | Projects |
| `repo.ext_wiki` | External wiki |
| `repo.packages` | Packages |

### units vs units_map

- **units**: Simple array listing which units the team can access. All listed units inherit the team's `permission` level.
- **units_map**: Object mapping unit names to individual permission levels (`read`, `write`, `admin`). Provides granular per-unit permissions.

If both are provided, `units_map` takes precedence.

```bash
# Create team with simple units list
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{team_name}",
    "description": "Core development team",
    "permission": "write",
    "can_create_org_repo": true,
    "includes_all_repositories": false,
    "units": [
      "repo.code",
      "repo.issues",
      "repo.pulls",
      "repo.releases"
    ]
  }' \
  "${FORGEJO_URL}/api/v1/orgs/{org}/teams"
```

```bash
# Create team with granular units_map
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{team_name}",
    "description": "Issue triage team",
    "permission": "read",
    "units_map": {
      "repo.code": "read",
      "repo.issues": "write",
      "repo.pulls": "read",
      "repo.wiki": "write"
    }
  }' \
  "${FORGEJO_URL}/api/v1/orgs/{org}/teams"
```

---

## Search Teams

```
GET /orgs/{org}/teams/search
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| q | string | query | Search keyword |
| include_desc | boolean | query | Include description in search |
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/teams/search?q=dev&include_desc=true"
```

**Response:**
```json
{
  "ok": true,
  "data": [ /* array of Team objects */ ]
}
```

---

## Get Team by ID

```
GET /teams/{id}
```

**Response (Team):**
| Field | Type | Description |
|-------|------|-------------|
| id | integer | Team ID |
| name | string | Team name |
| description | string | Description |
| organization | object | Parent organization |
| permission | string | Permission level |
| can_create_org_repo | boolean | Can create repos |
| includes_all_repositories | boolean | Access to all repos |
| units | array | Unit access list |
| units_map | object | Per-unit permissions map |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}"
```

---

## Edit Team

```
PATCH /teams/{id}
```

**Request Body (EditTeamOption):**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | yes | Team name |
| description | string | no | Description |
| permission | string | no | `read`, `write`, `admin`, `owner` |
| can_create_org_repo | boolean | no | Can create repos |
| includes_all_repositories | boolean | no | Access all repos |
| units | array | no | Unit access list |
| units_map | object | no | Per-unit permissions |

```bash
curl -s -X PATCH \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{team_name}",
    "description": "Updated description",
    "permission": "admin",
    "includes_all_repositories": true
  }' \
  "${FORGEJO_URL}/api/v1/teams/{team_id}"
```

---

## Delete Team

```
DELETE /teams/{id}
```

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}"
```

Returns `204 No Content` on success.

---

## List Team Repositories

```
GET /teams/{id}/repos
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}/repos"
```

---

## Add Repository to Team

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

```bash
curl -s -X PUT \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}/repos/{owner}/{repo}"
```

Returns `204 No Content` on success.

---

## Remove Repository from Team

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

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}/repos/{owner}/{repo}"
```

Returns `204 No Content` on success.

---

## List Team Members

```
GET /teams/{id}/members
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}/members"
```

---

## Add Member to Team

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

```bash
curl -s -X PUT \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}/members/{username}"
```

Returns `204 No Content` on success.

---

## Remove Member from Team

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

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}/members/{username}"
```

Returns `204 No Content` on success.

---

## Team Activity Feed

```
GET /teams/{id}/activities/feeds
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| date | string | query | Date filter (YYYY-MM-DD) |
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/teams/{team_id}/activities/feeds?page=1&limit=10"
```

**Response:** Array of activity objects containing action details, actor info, and timestamps.
