---
title: "List libraries"
method: GET
path: "/api/libraries"
tags: ["libraries"]
---

# List libraries

`GET /api/libraries`

Returns libraries owned by the authenticated user (no pagination — users typically have one or a handful). Call this when another tool's `library_id` parameter is required but you don't yet know which libraries exist. A single-library user can usually omit `library_id` on other tools entirely.

By default trashed libraries are excluded. Pass `state=trashed` to list the trash drawer (ordered by most recently trashed) or `state=all` for both.

## Query parameters

- `state` 'live' | 'trashed' | 'all' — Which set of libraries to return: `live` (default — excludes trashed), `trashed` (only trashed, ordered by most recently trashed), or `all` (both).

## Response `200`

Successful Response

- LibraryResponse[]
  - `id` string, required — Unique library identifier with 'lib_' prefix
  - `name` string, required — Display name of the library
  - `description` string, nullable — Optional description text for the library
  - `user_id` string, required — ID of the user who owns this library
  - `asset_count` integer, required — Total number of assets in this library
  - `storage_used_bytes` integer, required — Bytes of assets currently stored in this library
  - `storage_limit_bytes` integer, nullable — Maximum bytes this library may store, or null if no per-library limit applies
  - `created_at` string, date-time, required — When this library was created
  - `updated_at` string, date-time, required — When this library was last updated

## Other responses

- `401` — Missing, invalid, or expired credentials.
- `403` — The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `422` — Validation Error
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.

---

[API](https://skmtc.net/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.net/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/versions/e71db45f5d4a/schema)