# promptlib REST API — complete reference This document is the canonical, self-sufficient API reference. It is written so that a human or an AI agent can build a complete frontend against the API without reading the server source. Everything the wire does is here: every endpoint, every request/response shape, every error, every limit. - **Base URL**: `https://hygpo.com` (all API routes under `/v1/`) - **Formats**: JSON request/response (`Content-Type: application/json`), except file upload which is `multipart/form-data`. - **IDs**: UUIDv7 in canonical `8-4-4-4-12` form. Time-ordered, never sequential integers. - **Timestamps**: RFC 3339 UTC, e.g. `"2026-07-19T15:54:26.147Z"`. - **Errors**: every non-2xx response has the body `{"error": ""}`. Messages are stable enough to display, but branch on the status code, not the text. --- ## 1. Core concepts (read this before generating UI) **The API is the product; the frontend is yours.** The server stores *what things are* (essence) and refuses to store *how you arrange them* (organization) as anything but opaque JSON. Two users can render the same data as completely different products. - **content** — one uploaded (or, in future, generated) file: an audio track or an image. A content row is one **owner's projection** of a file: the same bytes uploaded by two users are two content rows sharing one deduplicated blob. A content has: - `caption` — the owner's one-line description (plain text). - `user_defined_content_meta` — the owner's **opaque JSON**. The server stores, returns, and size-caps it, and never reads it. Use it for tags, albums, layout hints — anything your frontend wants. - `kind` — `"image"` or `"audio"`. There are no sub-types: no "stem", no "vocal", no "full-mix" kind. What a track *is to you* is your frontend's annotation, not the content's type. - lifecycle: `status` × `visibility` (see §3). - **post** — the organization/publication unit (think WordPress post). A post is `caption` + `body` (free text, opaque) + `meta` (opaque JSON) + an **ordered list of items**, each item referencing one content plus an opaque per-item `annotation`. The same content can appear in many posts — and twice in one post — with different annotations each time. Your frontend decides what a post *looks like* (track editor, DJ deck, gallery, article) — typically by convention keys you define yourself in `post.meta`. - **generation** — content can also be *generated*, not just uploaded. You submit an async **job** (`POST /v1/jobs`) naming a `capability` (today `music.synth` and its planning/understanding siblings). A worker runs it and parks the result(s) in **scratch** — candidate artifacts that are NOT yet library contents and cost you no storage until you keep them. You poll the job, preview the candidates, then **commit** the ones you want, promoting them into permanent `content` (the prompt is written to the searchable `body`, the resolved generation request to server-owned metadata). Uncommitted candidates expire. See §4 *Async jobs* and §5.13–5.18. - **referral** — registration is invitation-only: every new account spends a single-use referral code minted by an existing user. **What does NOT exist yet** (do not generate UI that needs it): - Generation is **audio only** today (`music.*`); image and text generation are designed, not yet served. - No search endpoint (semantic prompt search is designed, not yet served). - No account management: no password change, no logout/revoke, no profile edit, no user listing. - No content delete or content status/visibility change (contents are born `draft`+`private` and currently stay owner-visible only; **posts** are the publishable unit). - No CORS headers: browsers must be served from the same origin (or proxied). --- ## 2. Authentication ### Model - **Session token** (bearer): opaque signed string, **valid 15 minutes**. Send as `Authorization: Bearer `. - **Refresh token**: opaque string, **single-use**. Exchange it at `POST /v1/sessions/refresh` for a fresh session + a NEW refresh token. Reusing a refresh token that was already spent revokes the whole token family (defense against theft) — the client must then log in again. - **Anonymous**: requests with NO `Authorization` header are the anonymous reader — GET endpoints work and return only `published` + `public` rows. A *present but invalid* bearer is `401`, never silently anonymous. ### Recommended client loop 1. Login → store `session_token` + `refresh_token`. 2. On any `401` from an API call: call refresh once, replace both tokens, retry the original request once. If refresh itself fails → prompt login. 3. Never send the refresh token as a bearer; it only ever goes in the refresh request body. ### Roles | role | may | |---|---| | (anonymous) | read published+public rows | | `reader` | read (own + public) | | `author` | read; write/publish **their own** content & posts; mint codes granting ≤ their rank | | `editor` | read; write/publish **anyone's** | | `admin` | everything, including reading all rows regardless of visibility | --- ## 3. Lifecycle: status × visibility Two orthogonal fields on both contents and posts: - `status`: `draft` → `pending` → `published` → `archived` / `trash` (workflow position). - `visibility`: `private` | `public` (audience). A row is **world-readable only when** `status="published"` AND `visibility="public"`. Owners always see their own rows whatever the state. A row the caller may not see is reported as **404 not found — never 403** (the API refuses to confirm hidden things exist). Generate UI accordingly: treat 404 as "does not exist for this user". For v1, only **posts** expose status/visibility editing. Contents are created `draft`+`private` and stay that way (publish the *post* that references them). --- ## 4. Conventions ### Pagination (all list endpoints) Keyset cursor, newest first: ``` GET /v1/posts?limit=20&after= → {"items": [...], "next": ""} ``` - `limit`: default 20, max 100 (values beyond are clamped). - `next` is an opaque cursor; pass it back as `after` for the next page. Empty `next` = last page. Never construct a cursor yourself; a malformed one is `400`. ### Rate limits | class | applies to | rate | on excess | |---|---|---|---| | per-IP | every request | ~300/min, burst 60 | `429` + `Retry-After` | | auth | login / register / refresh (per IP) | ~10/min, burst 5 | `429` | | write | uploads, edits, post writes (per user) | ~30/min, burst 10 | `429` | `429` bodies are uniform and reveal nothing about accounts. Honor `Retry-After` (seconds). ### Size caps (server-enforced) | field | cap | |---|---| | upload file | 64 MiB | | JSON request body | 64 KiB | | `caption` (content & post) | 2 KiB | | post `body` | 32 KiB | | `user_defined_content_meta`, post `meta`, item `annotation` | 16 KiB each | | items per post | 256 | | contents per user | 200 rows | | posts per user | 500 rows | | job `params` | 16 KiB | | in-flight jobs per user (`queued`+`running`) | 20 | | generation candidates | scratch; expire after 24 h (or by scratch quota) unless committed | ### Async jobs (generation) Generation is asynchronous — a job runs on a single serial GPU worker, so it is queued, not awaited inline. The loop: 1. `POST /v1/jobs` → `202` `{"id":...,"status":"queued"}`. 2. Poll `GET /v1/jobs/{id}` until `status` is terminal (`done` / `failed` / `cancelled`). Poll ~1 s; polling has no side effect. 3. On `done`, the job carries `result.candidates` — one or more scratch artifacts. Preview a candidate's bytes with `GET /v1/jobs/{id}/candidates/{k}` (§5.16). 4. `POST /v1/jobs/{id}/commit` the candidate you want → it becomes a permanent `content`. Uncommitted candidates expire (caps above). Statuses: `queued` → `running` → `done` | `failed` | `cancelled`. A job is visible only to its owner (`404` otherwise), exactly like contents and posts. --- ## 5. Endpoints ### 5.1 Register — `POST /v1/users` Anonymous. Spends a referral code. Does NOT log in (call login next). Request: ```json {"referral_code": "", "email": "you@example.com", "password": "min 8 chars"} ``` Responses: - `201` → `{"id","email","role","created_at"}` — role comes from the code. - `400` invalid/expired code, or validation (`password must be at least 8 characters`, bad email — message is display-safe). - `409` code already used / email already registered. - `429` auth rate limit. Email is lowercased server-side. Password: 8–4096 chars. ### 5.2 Login — `POST /v1/sessions` Anonymous. Request: ```json {"email": "you@example.com", "password": "..."} ``` Responses: - `200` → ```json {"session_token":"...","refresh_token":"...", "user":{"id":"...","email":"...","role":"author","created_at":"..."}} ``` - `401` `{"error":"invalid credentials"}` (same for unknown email — no enumeration). - `429` auth rate limit. ### 5.3 Refresh — `POST /v1/sessions/refresh` Anonymous (the token in the body is the credential). Request: `{"refresh_token": "..."}` Responses: - `200` → same shape as login (NEW session token + NEW refresh token; the old refresh token is dead). - `401` invalid OR reused token (reuse also revokes the family). - `429` auth rate limit. ### 5.4 Mint referral code — `POST /v1/referral-codes` Authenticated. Grants a role no higher than your own. Request: `{"granted_role": "reader" | "author" | "editor" | "admin"}` Responses: - `201` → `{"code":"...","granted_role":"...","expires_at":"..."}` — codes live 24 h, single-use. - `403` your role may not grant that role. - `429` more than 50 unexpired codes outstanding. ### 5.5 Upload content — `POST /v1/contents` Authenticated (any writing role). `multipart/form-data`: | part | value | |---|---| | `file` | the bytes (≤ 64 MiB) | | `kind` | `image` or `audio` | | `caption` | optional; >2 KiB is truncated | Responses: - `201` → content DTO (below). Born `status:"draft"`, `visibility:"private"`. **Idempotent**: re-uploading the same bytes returns the *existing* content (same `id`), not a new row and not an error — the API deduplicates per owner. - `400` bad form / unsupported kind. - `413` file too large. - `429` write rate or the 200-row storage quota (`"you have reached your storage limit"`). Content DTO: ```json {"id":"0198...","owner_id":"0198...","kind":"audio", "status":"draft","visibility":"private", "caption":"...","original_name":"track.mp3", "tool_defined_content_meta":{...}, // omitted when unset — READ-ONLY "user_defined_content_meta":{...}, // omitted when unset "created_at":"...","updated_at":"..."} ``` `original_name` is the uploaded filename, display-only. The file hash is never exposed. `tool_defined_content_meta` are the tool-parsed *essence* facts — for a committed generation, the resolved plan (`bpm`, `keyscale`, `duration`, `vocal_language`, `lyrics`, `seed`, …) plus the byte `format`. It is **read-only**: the generate / commit flow writes it; there is no request field that sets it (a plain upload leaves it absent). Do not confuse it with `user_defined_content_meta`, which is your own opaque organising JSON that you PATCH. ### 5.6 List contents — `GET /v1/contents` Anonymous or authenticated. Paginated (§4). Scope: anonymous → published + public; user → their own (all states) + published/public of others; admin → everything. `200` → `{"items":[...],"next":"..."}` ### 5.7 Get content — `GET /v1/contents/{id}` Same scoping. `200` → content DTO. `404` unknown OR not visible to you. #### 5.7a Download content bytes — `GET /v1/contents/{id}/file` The raw bytes of a committed content — the read-side twin of the candidate preview (§5.16), for content already in a library. Draw a waveform, play, or download from here. Same scoping as §5.7 (a row not visible to you is `404`, never "forbidden"). - `200` → the bytes. `Content-Type` reflects the file (`audio/wav`, `audio/mpeg`, `image/png`, …; `application/octet-stream` when unknown). - **Cacheable & seekable**: responds with a strong `ETag` (send it back as `If-None-Match` for a `304`) and `Cache-Control: private, immutable` — the bytes never change under an id. Honours `Range`, so an `