Create library

Keeps one thing you made in your Library: its bytes go to your own prefix of the Library's store, and it is listed to you alone until you share it.

POST /v1/library

Library → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/library`
Method	`POST`
Operation	`post_library`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Keeps one thing you made in your Library: its bytes go to your own prefix of the Library's store, and it is listed to you alone until you share it. Send data up to 10 MiB inline, or send bytes up to 2 GiB to reserve a signed upload PUT and finish it with PATCH /v1/library/:id {"commit": true}. A save with the key of one already kept answers that item.

Request

15 fields, body application/json (required).

Field	In	Type	Required	Description
`bytes`	body	integer (int64)	—	Bytes reserves an upload of this size, at most 2 GiB, when data is empty, and returns a signed PUT in upload.
`data`	body	string	—	Data is the bytes, base64, at most 10 MiB; omit when reserving with bytes.
`height`	body	integer (int64)	—
`key`	body	string	—	Key makes the save idempotent: the same source and key answer the item already kept.
`kind`	body	string	—	Kind is image, video, audio, document, slides, type, model, code or file; absent derives it from mime.
`mime`	body	string	—	Mime is its media type.
`name`	body	string	—	Name is what it is called, a file name.
`origin`	body	string	—	Origin is the path on this site back to what made it, as /chat?thread=….
`pages`	body	integer (int64)	—
`preview`	body	string	—	Preview is a still that shows it, base64, at most 2 MiB.
`project`	body	string	—	Project is one of the organization's projects, by slug.
`ref`	body	string	—	Ref is what made it: the conversation, the run.
`seconds`	body	number (double)	—
`source`	body	string	—	Source is the product it came from: chat, dev, studio or workflow.
`width`	body	integer (int64)	—	Width, Height, Seconds and Pages describe it when known.

Response

Status	Body	Meaning
`201`	library.LibraryItem	created
`default`	problem-details	refused

201 body — 29 fields.

Field	In	Type	Always	Description
`by`	body	string	—	By is the owner as a reader names them: the name, else the address, the identity boundary carried when the item was made.
`bytes`	body	integer (int64)	—
`created`	body	string	—
`download`	body	string	—
`expires`	body	string	—
`height`	body	integer (int64)	—
`id`	body	string	—
`kind`	body	string	—
`mime`	body	string	—
`mine`	body	boolean	—
`name`	body	string	—
`origin`	body	string	—
`owner`	body	string	—
`pages`	body	integer (int64)	—
`preview`	body	string	—
`project`	body	string	—
`ref`	body	string	—
`seconds`	body	number (double)	—
`shared`	body	boolean	—
`source`	body	string	—
`updated`	body	string	—
`upload`	body	library.LibraryUpload	—
`upload.expires`	body	string	—
`upload.headers`	body	library.Field[]	—	Headers are the ones the PUT must carry.
`upload.headers[].name`	body	string	—	Name is the field's name.
`upload.headers[].value`	body	string	—	Value is the field's value, verbatim.
`upload.url`	body	string	—
`url`	body	string	—
`width`	body	integer (int64)	—

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo library create

.ts

.py

.go

.rs

.java

import { Configuration, LibraryApi } from 'hanzoai';

const api = new LibraryApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postLibrary({ bytes: 0, data: "<data>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import LibraryApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = LibraryApi(client).post_library(bytes=0, data="<data>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.LibraryAPI.PostLibrary(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, library_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = library_api::post_library(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.LibraryApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new LibraryApi(client).postLibrary();

curl -X POST https://api.hanzo.ai/v1/library \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "bytes": 0,
       "data": "<data>"
     }'

MCP reaches library through the library tool, which names its 6 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_libraries"
         }
       }
     }'

Library API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousUpdate library NextGet download