# Organizations API

> List, read, create, and rename the organizations the caller belongs to.

- [List organizations](#list-organizations): `GET /v1/organizations`
- [Create an organization](#create-an-organization): `POST /v1/organizations`
- [Get an organization](#get-an-organization): `GET /v1/organizations/{organization_id}`
- [Rename an organization](#rename-an-organization): `PATCH /v1/organizations/{organization_id}`

## List organizations

`GET /v1/organizations`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`OrganizationList`](/docs/api/schemas#organizationlist) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/organizations" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "dev",
      "role": "owner",
      "suspended_at": "2026-10-12T05:51:01Z"
    }
  ]
}
```

## Create an organization

`POST /v1/organizations`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Any signed-in user.

**Request body** (`application/json`, [`CreateOrganizationRequest`](/docs/api/schemas#createorganizationrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | 1-64 characters without control characters or surrounding whitespace; unique (case-insensitively) among the caller's own organizations. 1–64 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `201` | Created with the caller as owner and a trial wallet | [`OrganizationDto`](/docs/api/schemas#organizationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure or bearer authentication (`session_required`) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `organization_name_taken`: the caller already created one with this name | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | `rate_limited`: 5 creations per user per 24 hours, counting the personal organization created at sign-in | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/organizations" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "dev"
}'
```

```json title="Response 201"
{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}
```

## Get an organization

`GET /v1/organizations/{organization_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`OrganizationDto`](/docs/api/schemas#organizationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not a member, or another organization than the API key's | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}
```

## Rename an organization

`PATCH /v1/organizations/{organization_id}`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Request body** (`application/json`, [`UpdateOrganizationRequest`](/docs/api/schemas#updateorganizationrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | 1–64 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`OrganizationDto`](/docs/api/schemas#organizationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, bearer authentication (`session_required`), or neither owner nor admin | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `organization_name_taken`: its creator already has an organization with this name | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PATCH "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "dev"
}'
```

```json title="Response 200"
{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}
```