# List the diagrams a key or an app's token can see

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

A page of diagrams, newest first: a person's own hosted diagrams, or an organisation's library under its folder rules and approval holds, as the person would see it.

`GET /v1/library`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | List the diagrams a key or an app's token can see. |
| What does it take? | `limit`, `cursor`, `folder` in the query string. |
| What does it return? | Status 200 with a body of type [`LibraryPage`](https://docs.plotwork.dev/api/schemas.md#librarypage). |
| What can go wrong? | `400` the query is not valid, or the cursor is not one this API gave; `401` no key, or the key or token is not valid; `403` the token's grant does not hold library:read (oauth.insufficient_scope); `404` the organisation of the key is gone, or the member left it; `429` too many requests, or the daily limit is used up. Every failure uses the one error envelope. |

## What it does

A page of diagrams, newest first: a person's own hosted diagrams, or an organisation's library under its folder rules and approval holds, as the person would see it. No diagram source is answered. An app's token needs library:read. Open to every plan.

## Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` | `integer` | no | Diagrams a page, 1 to 100. 50 when left out. |
| `cursor` | `string` | no | The nextCursor of the page before. |
| `folder` | `string` | no | Keep to this folder and everything inside it, such as Payments/Checkout. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | A page of the library. | [`LibraryPage`](https://docs.plotwork.dev/api/schemas.md#librarypage) |
| 400 | The query is not valid, or the cursor is not one this API gave. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | No key, or the key or token is not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | The token's grant does not hold library:read (oauth.insufficient_scope). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | The organisation of the key is gone, or the member left it. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests, or the daily limit is used up. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

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

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | `object[]` | yes |  |
| `items[].id` | `string` | yes |  |
| `items[].name` | `string \| null` | yes |  |
| `items[].folder` | `string \| null` | yes |  |
| `items[].scheme` | `"light" \| "dark" \| "auto"` | yes | The color scheme it was drawn in: light, dark, or auto. |
| `items[].bytes` | `integer` | yes |  |
| `items[].updatedAt` | `integer` | yes | When it was last published, in milliseconds since the epoch. |
| `items[].classification` | `"public" \| "internal" \| "confidential" \| null` | yes | Its label in an organisation's library, or null for a person's own diagram. |
| `nextCursor` | `string \| null` | yes |  |

## 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 |