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

## Changes

- **2026-08-08** `815e0302a988` — 1 breaking, 1 info
  - response property `detail` list-of-types was widened by adding types `string` to media type `application/json` of response `422`
  - the response property `detail` became required for the status `422`
- **2026-08-05** `c3e15c78f2da` — 4 info
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`
  - removed the non-success response with the status `404`
- **2026-07-21** `0de36cb170df` — 2 warning
  - the `description/anyOf[subschema #1]/` request property's maxLength was set to `8192`
  - the `name` request property's maxLength was set to `255`
- **2026-06-02** `4d4c5e5b7ab8` — 2 info
  - added the optional property `storage_limit_bytes` to the response with the `201` status
  - added the required property `storage_used_bytes` to the response with the `201` status

[Change history](https://skmtc.dev/gumnut-ai/apis/gumnut-api/changes/api/libraries/post.md)

---

[API](https://skmtc.dev/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.dev/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/revisions/2c3aca3a6e6d/schema)