> ## Documentation Index
> Fetch the complete documentation index at: https://docs.korve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

> Organizations (accounts). Billing and projects attach here, never to users.

Organizations (accounts). Billing and projects attach here, never to users.

## orgs.list

List organizations the caller belongs to.

```text theme={null}
GET /v1/orgs
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs" \
  -b "$SESSION"
```

### Responses

| Status | Description                           |
| ------ | ------------------------------------- |
| `200`  | Organizations with the caller's role. |

### Response body (200)

An array of objects with these fields:

| Field           | Type    | Description                                         |
| --------------- | ------- | --------------------------------------------------- |
| `id`            | string  | —                                                   |
| `name`          | string  | —                                                   |
| `slug`          | string  | —                                                   |
| `isPersonal`    | boolean | —                                                   |
| `billingStatus` | string  | One of: `unpaid`, `active`, `past_due`, `canceled`. |
| `createdAt`     | string  | Format: `date-time`.                                |

## orgs.create

Create a team organization owned by the caller.

```text theme={null}
POST /v1/orgs
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `member`
* **Risk:** `write`

### Request body

| Field  | Type   | Required | Description |
| ------ | ------ | -------- | ----------- |
| `name` | string | Yes      | —           |
| `slug` | string | Yes      | —           |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs" \
  -b "$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront",
  "slug": "storefront"
}'
```

### Responses

| Status | Description           |
| ------ | --------------------- |
| `201`  | Organization created. |
| `409`  | Slug already taken.   |

### Response body (201)

| Field           | Type    | Description                                         |
| --------------- | ------- | --------------------------------------------------- |
| `id`            | string  | —                                                   |
| `name`          | string  | —                                                   |
| `slug`          | string  | —                                                   |
| `isPersonal`    | boolean | —                                                   |
| `billingStatus` | string  | One of: `unpaid`, `active`, `past_due`, `canceled`. |
| `createdAt`     | string  | Format: `date-time`.                                |

## orgs.get

Get one organization the caller belongs to.

```text theme={null}
GET /v1/orgs/{orgId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                           |
| ------ | ------------------------------------- |
| `200`  | The organization.                     |
| `404`  | Not a member or no such organization. |

### Response body (200)

| Field           | Type    | Description                                         |
| --------------- | ------- | --------------------------------------------------- |
| `id`            | string  | —                                                   |
| `name`          | string  | —                                                   |
| `slug`          | string  | —                                                   |
| `isPersonal`    | boolean | —                                                   |
| `billingStatus` | string  | One of: `unpaid`, `active`, `past_due`, `canceled`. |
| `createdAt`     | string  | Format: `date-time`.                                |

## orgs.update

Update an organization's name and/or slug. Slugs are lowercase letters, numbers and dashes, must be unique across the platform, and change the organization's dashboard URLs immediately.

```text theme={null}
PATCH /v1/orgs/{orgId}
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `admin`
* **Risk:** `write`

### Request body

| Field  | Type   | Required | Description                        |
| ------ | ------ | -------- | ---------------------------------- |
| `name` | string | No       | 1-100 characters.                  |
| `slug` | string | No       | Pattern: `^[a-z][a-z0-9-]{1,38}$`. |

### Example

```bash theme={null}
curl -X PATCH "https://api.korve.dev/v1/orgs/$ORG_ID" \
  -b "$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront",
  "slug": "storefront"
}'
```

### Responses

| Status | Description           |
| ------ | --------------------- |
| `200`  | Updated organization. |
| `409`  | Slug already in use.  |
| `422`  | Invalid name or slug. |

### Response body (200)

| Field           | Type    | Description                                         |
| --------------- | ------- | --------------------------------------------------- |
| `id`            | string  | —                                                   |
| `name`          | string  | —                                                   |
| `slug`          | string  | —                                                   |
| `isPersonal`    | boolean | —                                                   |
| `billingStatus` | string  | One of: `unpaid`, `active`, `past_due`, `canceled`. |
| `createdAt`     | string  | Format: `date-time`.                                |

## orgs.delete

Delete an organization and everything in it.

```text theme={null}
DELETE /v1/orgs/{orgId}
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `owner`
* **Risk:** `destructive` · sensitive (elevated blast radius)

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID" \
  -b "$SESSION"
```

### Responses

| Status | Description                               |
| ------ | ----------------------------------------- |
| `200`  | Organization deleted.                     |
| `422`  | Personal organizations cannot be deleted. |

## orgs.listMembers

List organization members with roles.

```text theme={null}
GET /v1/orgs/{orgId}/members
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/members" \
  -b "$SESSION"
```

### Responses

| Status | Description |
| ------ | ----------- |
| `200`  | Members.    |

### Response body (200)

An array of objects with these fields:

| Field       | Type   | Description                         |
| ----------- | ------ | ----------------------------------- |
| `id`        | string | —                                   |
| `userId`    | string | —                                   |
| `email`     | string | —                                   |
| `name`      | string | —                                   |
| `role`      | string | One of: `owner`, `admin`, `member`. |
| `createdAt` | string | Format: `date-time`.                |

## orgs.updateMemberRole

Change a member's role.

```text theme={null}
PATCH /v1/orgs/{orgId}/members/{memberId}
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `admin`
* **Risk:** `write`

### Request body

| Field  | Type   | Required | Description                         |
| ------ | ------ | -------- | ----------------------------------- |
| `role` | string | Yes      | One of: `owner`, `admin`, `member`. |

### Example

```bash theme={null}
curl -X PATCH "https://api.korve.dev/v1/orgs/$ORG_ID/members/$MEMBER_ID" \
  -b "$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "owner"
}'
```

### Responses

| Status | Description     |
| ------ | --------------- |
| `200`  | Updated member. |

### Response body (200)

| Field       | Type   | Description                         |
| ----------- | ------ | ----------------------------------- |
| `id`        | string | —                                   |
| `userId`    | string | —                                   |
| `email`     | string | —                                   |
| `name`      | string | —                                   |
| `role`      | string | One of: `owner`, `admin`, `member`. |
| `createdAt` | string | Format: `date-time`.                |

## orgs.removeMember

Remove a member from the organization.

```text theme={null}
DELETE /v1/orgs/{orgId}/members/{memberId}
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `admin`
* **Risk:** `destructive`

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/members/$MEMBER_ID" \
  -b "$SESSION"
```

### Responses

| Status | Description                       |
| ------ | --------------------------------- |
| `200`  | Member removed.                   |
| `422`  | The last owner cannot be removed. |

## orgs.listInvitations

List pending invitations.

```text theme={null}
GET /v1/orgs/{orgId}/invitations
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/invitations" \
  -b "$SESSION"
```

### Responses

| Status | Description          |
| ------ | -------------------- |
| `200`  | Pending invitations. |

### Response body (200)

An array of objects with these fields:

| Field       | Type   | Description                         |
| ----------- | ------ | ----------------------------------- |
| `id`        | string | —                                   |
| `email`     | string | —                                   |
| `role`      | string | One of: `owner`, `admin`, `member`. |
| `status`    | string | —                                   |
| `expiresAt` | string | Format: `date-time`.                |

## orgs.createInvitation

Invite someone by email. Sends an invitation email.

```text theme={null}
POST /v1/orgs/{orgId}/invitations
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `admin`
* **Risk:** `write`

### Request body

| Field   | Type   | Required | Description                |
| ------- | ------ | -------- | -------------------------- |
| `email` | string | Yes      | Format: `email`.           |
| `role`  | string | Yes      | One of: `admin`, `member`. |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/invitations" \
  -b "$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "dev@acme.com",
  "role": "admin"
}'
```

### Responses

| Status | Description                     |
| ------ | ------------------------------- |
| `201`  | Invitation created and emailed. |

### Response body (201)

| Field       | Type   | Description                         |
| ----------- | ------ | ----------------------------------- |
| `id`        | string | —                                   |
| `email`     | string | —                                   |
| `role`      | string | One of: `owner`, `admin`, `member`. |
| `status`    | string | —                                   |
| `expiresAt` | string | Format: `date-time`.                |

## orgs.revokeInvitation

Cancel a pending invitation.

```text theme={null}
DELETE /v1/orgs/{orgId}/invitations/{invitationId}
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `admin`
* **Risk:** `destructive`

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/invitations/$INVITATION_ID" \
  -b "$SESSION"
```

### Responses

| Status | Description          |
| ------ | -------------------- |
| `200`  | Invitation canceled. |