# List your organisations

> Page: https://docs.plotwork.dev/api/get-orgs. Index of every page: https://docs.plotwork.dev/llms.txt

The organisations the account belongs to, by name, at most 100, each with the caller's role, its plan (its owner's), what it holds, and the limits.

`GET /orgs`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | List your organisations. |
| What does it take? | Nothing. |
| What does it return? | Status 200 with a body of type [`OrganisationList`](https://docs.plotwork.dev/api/schemas.md#organisationlist). |
| What can go wrong? | `401` not signed in; `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope. |

## What it does

The organisations the account belongs to, by name, at most 100, each with the caller's role, its plan (its owner's), what it holds, and the limits.

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The organisations. | [`OrganisationList`](https://docs.plotwork.dev/api/schemas.md#organisationlist) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Organisations are not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`OrganisationList`](https://docs.plotwork.dev/api/schemas.md#organisationlist).

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | `Organisation[]` | yes | By name, at most 100. |
| `items[].id` | `string` | yes |  |
| `items[].slug` | `string` | yes |  |
| `items[].name` | `string` | yes |  |
| `items[].role` | `"owner" \| "admin" \| "member" \| "reader"` | yes | What the caller is in this organisation. |
| `items[].createdAt` | `integer` | yes | Milliseconds since the epoch. |
| `items[].memberCount` | `integer` | yes | People who have joined, the owner included. The same number as `usage.members`. minimum 0. |
| `items[].plan` | `"free" \| "pro" \| "enterprise"` | yes | The organisation's plan: `enterprise` under a contract, otherwise its owner's. |
| `items[].contractEndsOn` | `string \| null` | yes | The last day of the Enterprise contract, `YYYY-MM-DD`, or null when there is none or it has no end date written. The terms of a contract are not shown to members. |
| `items[].usage` | `OrganisationUsage` | yes |  |
| `items[].usage.diagrams` | `integer` | yes | minimum 0. |
| `items[].usage.bytes` | `integer` | yes | minimum 0. |
| `items[].usage.members` | `integer` | yes | People who have joined, the owner included. minimum 0. |
| `items[].usage.invites` | `integer` | yes | Invitations that can still be accepted. They count toward the member limit. minimum 0. |
| `items[].limits` | `OrganisationLimits` | yes |  |
| `items[].limits.dailyCalls` | `integer` | yes |  |
| `items[].limits.hostedDiagrams` | `integer` | yes | Diagrams the organisation may hold. |
| `items[].limits.hostedBytes` | `integer` | yes | Total bytes of diagrams the organisation may hold. |
| `items[].limits.retentionDays` | `integer \| null` | yes | Days a diagram is kept after it was last published, or null to keep it until it is deleted. |
| `items[].limits.maxDiagramBytes` | `integer` | yes |  |
| `items[].limits.stableLinks` | `integer` | yes | Stable links the owner may keep for their own diagrams. An organisation's diagrams have none. |
| `items[].limits.organisations` | `integer` | yes | Organisations an account on this plan may own. |
| `items[].limits.orgMembers` | `integer` | yes | People one organisation may have, the owner included and pending invitations counted. |
| `items[].limits.orgIcons` | `integer` | yes | Custom icons one organisation may keep; zero on a plan without custom icons. minimum 0. |
| `items[].limits.driftHistoryDays` | `integer` | yes | Days the drift dashboard keeps a run and a status after it was reported; zero on a plan without the dashboard. minimum 0. |
| `items[].limits.auditRetentionDays` | `integer` | yes | Days the organisation's audit log keeps an event; zero on a plan that records none. minimum 0. |
| `items[].avatar` | `OrgAvatar` | yes | The organisation's uploaded avatar, or null when it has none and a mark made from its id stands in. |
| `items[].avatar.version` | `string` | yes | Changes with every upload. Put it in the address (?v=) so a new picture is a new address. |
| `items[].avatar.contentType` | `"image/svg+xml" \| "image/png" \| "image/gif" \| "image/webp"` | yes |  |
| `items[].avatar.animated` | `boolean` | yes | True when it moves, so a page can hold it still for a person who asked for less motion. |
| `items[].keepEditable` | `boolean` | yes | The owner's setting "Keep diagrams editable": true when a publish to the organisation that does not send embedSource writes the diagram source into the picture, so members can edit it in the portal later. Every member can open such a picture and read its source. |
| `items[].publishing` | `OrganisationPublishing` | yes |  |
| `items[].publishing.policy` | `"personal" \| "organisation-default" \| "organisation-required"` | yes | What the owner or an admin chose: personal (members publish where they choose), organisation-default (a member's publish that names no organisation goes to this library), or organisation-required (nothing a member publishes reaches a public link). |
| `items[].publishing.effective` | `"personal" \| "organisation-default" \| "organisation-required"` | yes | What is enforced now: the choice, except organisation-required on a plan that no longer includes it, which acts as organisation-default. |
| `items[].publishing.hideViewLinks` | `boolean` | yes | Whether hosted answers leave view links out for members and the organisation's keys. Honoured only while effective is organisation-required. |
| `items[].publishing.requiredAvailable` | `boolean` | yes | Whether the organisation's plan includes organisation-required (Pro and Enterprise). |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |