Hosting
List the diagrams a key or an app's token can see
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/libraryTL;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. |
| 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 |
| 400 | The query is not valid, or the cursor is not one this API gave. | ErrorResponse |
| 401 | No key, or the key or token is not valid. | ErrorResponse |
| 403 | The token's grant does not hold library:read (oauth.insufficient_scope). | ErrorResponse |
| 404 | The organisation of the key is gone, or the member left it. | ErrorResponse |
| 429 | Too many requests, or the daily limit is used up. | ErrorResponse |
Response body
A 200 answer has the type 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 | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |