Prompts
Package prompts is your prompt library, versioned, so nothing changes silently.
Package prompts is your prompt library, versioned, so nothing changes silently.
| Base URL | https://api.hanzo.ai |
| Operations | 6 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
prompts
GET /v1/prompts/{name}
Get returns one of the caller org's prompts: its CURRENT template text plus the metadata of every version it has had. The history carries version numbers, types and timestamps only — not each version's body — so a long history cannot inflate this response. A name the caller's org does not own is 404, whoever owns it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | Name is the prompt to act on, from the path. |
DELETE /v1/prompts/{name}
Delete removes one of the caller org's prompts and every version of it, answering 204. It is scoped to the caller's org, so a name another tenant owns is the same 404 an unknown name gives. There is no undo: the version history goes with it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | Name is the prompt to act on, from the path. |
GET /v1/prompts/catalog
Catalog returns the read-only starter prompt library shipped with the binary — reference content every tenant sees the same, NOT the caller's own prompts and never mixed into them. An org's library stays honestly empty until someone explicitly imports a starter, which is an ordinary POST /v1/prompts. Entries that would fail the create guards are dropped, so everything offered here can actually be imported.
GET /v1/prompts/metrics
Metrics returns real per-prompt statistics for the caller's org: how many versions each prompt has, which one is current, and when it was created and last changed. Every number is counted from the store — nothing here is estimated or fabricated.
GET /v1/prompts
List returns the caller org's prompt library as one row per prompt: its name, type, every version number it has, its taxonomy and when it last changed. The template bodies are deliberately absent — fetch one prompt to read its text.
POST /v1/prompts
Create records a prompt for the caller's org and answers 201 with it. A name the org already uses is NOT an error and NOT an overwrite: it appends a new version, so the library keeps real, inspectable history and the response carries the whole version list. The name is also the URL segment the prompt is fetched by, which is why its shape is constrained and a handful of names are reserved.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
labels | string[] | — | Labels is free-form taxonomy, each up to 64 characters, capped at 32 entries. |
name | string | — | Name is the org-unique handle AND the URL segment the prompt is addressed by: 1-64 characters matching… |
prompt | string | — | Prompt is the template body, capped at 64 KiB. |
tags | string[] | — | Tags is free-form taxonomy under the same bounds as Labels. |
type | string | — | Type labels the template's kind; defaults to "text". |
How is this guide?