# Read an organisation

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

The organisation, the caller's role, its plan (its owner's), what it holds, and the limits.

`GET /orgs/{org}`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Read an organisation. |
| What does it take? | `org` in the path. |
| What does it return? | Status 200 with a body of type [`Organisation`](https://docs.plotwork.dev/api/schemas.md#organisation). |
| What can go wrong? | `401` not signed in; `404` no such organisation, or the caller is not a member of it; `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope. |

## What it does

The organisation, the caller's role, its plan (its owner's), what it holds, and the limits. A person who is not a member gets 404, the same as for an organisation that does not exist.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The organisation. | [`Organisation`](https://docs.plotwork.dev/api/schemas.md#organisation) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, or the caller is not a member of it. | [`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 [`Organisation`](https://docs.plotwork.dev/api/schemas.md#organisation).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `slug` | `string` | yes |  |
| `name` | `string` | yes |  |
| `role` | `"owner" \| "admin" \| "member" \| "reader"` | yes | What the caller is in this organisation. |
| `createdAt` | `integer` | yes | Milliseconds since the epoch. |
| `memberCount` | `integer` | yes | People who have joined, the owner included. The same number as `usage.members`. minimum 0. |
| `plan` | `"free" \| "pro" \| "enterprise"` | yes | The organisation's plan: `enterprise` under a contract, otherwise its owner's. |
| `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. |
| `usage` | `OrganisationUsage` | yes |  |
| `usage.diagrams` | `integer` | yes | minimum 0. |
| `usage.bytes` | `integer` | yes | minimum 0. |
| `usage.members` | `integer` | yes | People who have joined, the owner included. minimum 0. |
| `usage.invites` | `integer` | yes | Invitations that can still be accepted. They count toward the member limit. minimum 0. |
| `limits` | `OrganisationLimits` | yes |  |
| `limits.dailyCalls` | `integer` | yes |  |
| `limits.hostedDiagrams` | `integer` | yes | Diagrams the organisation may hold. |
| `limits.hostedBytes` | `integer` | yes | Total bytes of diagrams the organisation may hold. |
| `limits.retentionDays` | `integer \| null` | yes | Days a diagram is kept after it was last published, or null to keep it until it is deleted. |
| `limits.maxDiagramBytes` | `integer` | yes |  |
| `limits.stableLinks` | `integer` | yes | Stable links the owner may keep for their own diagrams. An organisation's diagrams have none. |
| `limits.organisations` | `integer` | yes | Organisations an account on this plan may own. |
| `limits.orgMembers` | `integer` | yes | People one organisation may have, the owner included and pending invitations counted. |
| `limits.orgIcons` | `integer` | yes | Custom icons one organisation may keep; zero on a plan without custom icons. minimum 0. |
| `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. |
| `limits.auditRetentionDays` | `integer` | yes | Days the organisation's audit log keeps an event; zero on a plan that records none. minimum 0. |
| `avatar` | `OrgAvatar` | yes | The organisation's uploaded avatar, or null when it has none and a mark made from its id stands in. |
| `avatar.version` | `string` | yes | Changes with every upload. Put it in the address (?v=) so a new picture is a new address. |
| `avatar.contentType` | `"image/svg+xml" \| "image/png" \| "image/gif" \| "image/webp"` | yes |  |
| `avatar.animated` | `boolean` | yes | True when it moves, so a page can hold it still for a person who asked for less motion. |
| `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. |
| `publishing` | `OrganisationPublishing` | yes |  |
| `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). |
| `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. |
| `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. |
| `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 |