# Organizations API

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

## List Public Organizations

```
GET /orgs
```

**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?page=1&limit=20"
```

---

## Create Organization

```
POST /orgs
```

**Request Body (CreateOrgOption):**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| username | string | yes | Organization username |
| full_name | string | no | Display name |
| description | string | no | Description |
| website | string | no | Website URL |
| location | string | no | Location |
| visibility | string | no | `public`, `limited`, or `private` |
| repo_admin_change_team_access | boolean | no | Allow repo admin to change team access |

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "{org}",
    "full_name": "My Organization",
    "description": "An example organization",
    "website": "https://example.com",
    "location": "Earth",
    "visibility": "public"
  }' \
  "${FORGEJO_URL}/api/v1/orgs"
```

---

## Get Organization Details

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

**Response (Organization):**
| Field | Type | Description |
|-------|------|-------------|
| id | integer | Org ID |
| name | string | Username |
| full_name | string | Display name |
| description | string | Description |
| website | string | Website URL |
| location | string | Location |
| visibility | string | `public`, `limited`, or `private` |
| avatar_url | string | Avatar URL |
| repo_admin_change_team_access | boolean | Repo admin can change team access |

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

---

## Edit Organization

```
PATCH /orgs/{org}
```

**Request Body (EditOrgOption):**
| Field | Type | Description |
|-------|------|-------------|
| full_name | string | Display name |
| description | string | Description |
| website | string | Website URL |
| location | string | Location |
| visibility | string | `public`, `limited`, or `private` |
| repo_admin_change_team_access | boolean | Allow repo admin to change team access |

```bash
curl -s -X PATCH \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Updated Org Name",
    "description": "Updated description",
    "visibility": "private"
  }' \
  "${FORGEJO_URL}/api/v1/orgs/{org}"
```

---

## Delete Organization

```
DELETE /orgs/{org}
```

> **Warning:** This permanently deletes the organization, all its repositories, teams, and data.

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

Returns `204 No Content` on success.

---

## Get Current User's Organizations

```
GET /user/orgs
```

**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/user/orgs?page=1&limit=20"
```

---

## Get User's Organizations

```
GET /users/{username}/orgs
```

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

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/users/{username}/orgs"
```

---

## Create Repository in Organization

```
POST /orgs/{org}/repos
```

**Request Body (CreateRepoOption):**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | yes | Repository name |
| description | string | no | Description |
| private | boolean | no | Whether repo is private |
| auto_init | boolean | no | Initialize with README |
| gitignores | string | no | Gitignore template(s) |
| license | string | no | License template |
| readme | string | no | README template |
| default_branch | string | no | Default branch name |
| issue_labels | string | no | Issue label set |
| trust_model | string | no | Trust model for signatures |
| template | boolean | no | Whether repo is a template |
| object_format_name | string | no | Object format (`sha1` or `sha256`) |

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{repo}",
    "description": "A new repo in the org",
    "private": false,
    "auto_init": true,
    "default_branch": "{branch}"
  }' \
  "${FORGEJO_URL}/api/v1/orgs/{org}/repos"
```

Alternate endpoint (equivalent):
```
POST /org/{org}/repos
```

---

## List Organization Repositories

```
GET /orgs/{org}/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/orgs/{org}/repos?page=1&limit=20"
```

---

## Rename Organization

```
POST /orgs/{org}/rename
```

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| new_name | string | yes | New organization name |

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"new_name": "new-org-name"}' \
  "${FORGEJO_URL}/api/v1/orgs/{org}/rename"
```

Returns `204 No Content` on success.

---

## Set Organization Avatar

```
POST /orgs/{org}/avatar
```

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| image | string | yes | Base64-encoded image data |

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d "{\"image\": \"$(base64 -w 0 avatar.png)\"}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/avatar"
```

---

## Delete Organization Avatar

```
DELETE /orgs/{org}/avatar
```

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

---

## Block User from Organization

```
PUT /orgs/{org}/block/{username}
```

```bash
curl -s -X PUT \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/block/{username}"
```

---

## Unblock User from Organization

```
PUT /orgs/{org}/unblock/{username}
```

```bash
curl -s -X PUT \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/unblock/{username}"
```

---

## List Blocked Users

```
GET /orgs/{org}/list_blocked
```

**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}/list_blocked"
```

**Response:** Array of `BlockedUser` objects:
| Field | Type | Description |
|-------|------|-------------|
| block_id | integer | Block record ID |
| created_at | string | Timestamp of block |
| blocked_user | object | User object of blocked user |

---

## Organization Activity Feed

```
GET /orgs/{org}/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/orgs/{org}/activities/feeds?page=1&limit=10"
```

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