---
title: "Create a library"
method: POST
path: "/api/libraries"
tags: ["libraries"]
---

# Create a library

`POST /api/libraries`

Creates a new, empty photo library for the authenticated user. A library is the top-level container for assets, albums, people, and faces — most users have exactly one. Only create a new library when the user explicitly asks for a separate container.

## Request body

- LibraryCreate
  - `name` string, required — Display name for the new library. Required.
  - `description` string, nullable — Optional free-form description shown alongside the library name.

## Response `201`

Successful Response

- LibraryResponse — Represents a user's photo library.
  - `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)