{ "openapi": "3.1.0", "info": { "title": "BrewPage API", "version": "1.87.0", "termsOfService": "https://brewpage.app/terms", "description": "REST API for BrewPage — HTML/KV/JSON/file hosting platform. Publish and manage web content, key-value data,\nJSON documents, and files with short URLs, password protection, and real-time statistics.\n\n## Namespaces — READ BEFORE PUBLISHING\n\n**WARNING:** If you DO NOT pass `?ns=...`, your content goes into the namespace LITERALLY NAMED `public`\n— a SHARED, WORLDWIDE-DISCOVERABLE namespace. Anything stored in `public` WITHOUT a password:\n\n- is listed on the **brewpage.app HOMEPAGE GALLERY**\n- is returned by `GET /api/gallery` (paginated, full-text search over title/tags)\n- is indexable by search engines (sitemap + meta tags)\n- can be browsed by anyone — including LLM crawlers\n\n**If you do NOT want your content on the public homepage, you MUST pass a CUSTOM NAMESPACE**\n(e.g. `?ns=myproject-2026`) and/or set a password via `X-Password`. Only then will the item\nbe excluded from `/api/gallery`. The direct short URL `/{ns}/{id}` remains reachable by anyone\nwho knows it, regardless of namespace choice.\n\n- **DEFAULT** (when `ns` is omitted): `public` ← SHARED, LISTED ON HOMEPAGE\n- **CUSTOM**: any `[a-z0-9-]{3,32}` — auto-created on first use, NOT shown in gallery\n- **Collision** on `ns+id`: server returns `409 Conflict`; retry with a different `id` or omit `id`\n\n## TTL\n\n`ttl_days` applies to html, markdown, json, kv, files, and sites. Default `15`, allowed range `1..30`\n(max `30`). Resources auto-delete after expiry.\n\n## Short URL GET resolvers\n\nEvery short-URL GET resolver (HTML, markdown, JSON, KV, file, site) returns the current view counter in the\n`X-Views: ` response header.\n\n## File serving\n\nFile responses support HTTP Range requests (`Accept-Ranges: bytes`, `206 Partial Content`), carry an `ETag`\nheader, and are cached with `Cache-Control: public, max-age=3600`.\n\nAllowed file extensions include (non-exhaustive): html, md, json, txt, css, js, jsx, mjs, ts, tsx,\nplus images, audio, and video types permitted by platform limits.\n\n## Required Headers\n\n`User-Agent` is REQUIRED on every request. Format: `AgentName/version` (e.g. `Claude/4.5`, `Codex/1.0`,\n`MyBot/2.1`). Requests without User-Agent may be rate-limited or rejected. Identify yourself truthfully —\nspoofed or anonymous UAs may be flagged.\n\n## Access Logging\n\nEvery API request (both PUBLISH and READ) is persisted server-side into the `access_events` table:\nclient IP, User-Agent, HTTP method + path + query, response status, request duration (ms), UTC timestamp.\nRetention: 30 days (nightly cleanup). Admin-only endpoints: `GET /api/admin/access` (paginated log with\nfilters) and `GET /api/admin/access/stats` (aggregates). Only static assets are excluded from logging;\nevery API POST/GET/PUT/DELETE is recorded.\n", "contact": { "name": "BrewPage", "url": "https://brewpage.app" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "externalDocs": { "description": "BrewPage API documentation (Scalar)", "url": "https://kochetkov-ma.github.io/brewpage-openapi/" }, "servers": [ { "url": "https://brewpage.app", "description": "Generated server url" } ], "tags": [ { "name": "SEO", "description": "Search engine optimization endpoints" }, { "name": "Gallery", "description": "Browse public content from the 'public' namespace without password protection" }, { "name": "JSON", "description": "JSON document store with up to 10,000 docs per collection" }, { "name": "Stats", "description": "Platform-wide usage statistics" }, { "name": "Short Links", "description": "Short URL resolver for sharing" }, { "name": "HTML", "description": "HTML page hosting with markdown support" }, { "name": "KV", "description": "Key-Value store with up to 1000 keys per namespace" }, { "name": "Files", "description": "File hosting up to 5 MB per file, 1000 files per namespace" }, { "name": "Sites", "description": "Multi-file HTML site hosting via ZIP or folder upload (up to 5 MB per file, 1000 files per site)" }, { "name": "Reports", "description": "Abuse reports for published content (public submission endpoint)" }, { "name": "Admin", "description": "Administrative endpoints protected by the X-Admin-Password header" }, { "name": "Namespace", "description": "Fresh, collision-free namespace suggestions" }, { "name": "Owner", "description": "Owner token minting for claiming and updating your own resources" } ], "paths": { "/api/kv/{ns}/{id}/{key}": { "get": { "tags": [ "KV" ], "summary": "Get key value", "description": "Returns the value and last update timestamp for a specific key", "operationId": "getKey", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Password", "in": "header", "description": "Access password via header", "required": false, "schema": { "type": "string" } }, { "name": "p", "in": "query", "description": "Access password via query param (alternative to X-Password header)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key value", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvGetResponse" } } } }, "403": { "description": "Wrong password", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvGetResponse" } } } }, "404": { "description": "Store or key not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvGetResponse" } } } } } }, "put": { "tags": [ "KV" ], "summary": "Upsert key", "description": "Sets (creates or replaces) a key value while preserving the key short URL `/{ns}/{id}/{key}` —\nagents poll the same URL and see the latest value.\nTypical use: deploy-status counters, AI agent step state, current-config flags.\nMax 1000 keys per store. No version history: previous value is overwritten.\nRequires the owner token returned at creation.\n", "operationId": "upsertKey", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token returned at creation. Required for update and delete", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KvUpsertKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "Key upserted", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvUpsertKeyResponse" } } } }, "403": { "description": "Missing or wrong owner token", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvUpsertKeyResponse" } } } }, "404": { "description": "Store not found or expired", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvUpsertKeyResponse" } } } }, "409": { "description": "Key limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvUpsertKeyResponse" } } } } } }, "delete": { "tags": [ "KV" ], "summary": "Delete key", "description": "Removes a single key from the store; deleting the last key does not remove the store", "operationId": "deleteKey", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token returned at creation. Required for update and delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Key deleted" }, "403": { "description": "Missing or wrong owner token" }, "404": { "description": "Store or key not found" } } } }, "/api/json/{ns}/{id}": { "get": { "tags": [ "JSON" ], "summary": "Get JSON document", "description": "Returns raw JSON content with application/json content type", "operationId": "getById", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Password", "in": "header", "description": "Access password via header", "required": false, "schema": { "type": "string" } }, { "name": "p", "in": "query", "description": "Access password via query param (alternative to X-Password header)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON content", "content": { "*/*": { "schema": { "type": "string" } } } }, "403": { "description": "Wrong password", "content": { "*/*": { "schema": { "type": "string" } } } }, "404": { "description": "Document not found or expired", "content": { "*/*": { "schema": { "type": "string" } } } } } }, "put": { "tags": [ "JSON" ], "summary": "Update JSON document", "description": "Replaces document content while preserving the short URL — share once, edit in place.\nUseful for AI agents iterating on a JSON artifact (test results, plan state, config snapshot)\nwithout producing a new URL each time.\nImmutable on update: tags. No version history: previous content is overwritten.\nRequires the owner token returned at creation.\n", "operationId": "update", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token returned at creation. Required for update and delete", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Document updated", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/JsonUpdateResponse" } } } }, "403": { "description": "Missing or wrong owner token", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/JsonUpdateResponse" } } } }, "404": { "description": "Document not found or expired", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/JsonUpdateResponse" } } } } } }, "delete": { "tags": [ "JSON" ], "summary": "Delete JSON document", "description": "Permanently removes the document", "operationId": "delete", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token returned at creation. Required for update and delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Document deleted" }, "403": { "description": "Missing or wrong owner token" }, "404": { "description": "Document not found or expired" } } } }, "/api/html/{ns}/{id}": { "get": { "tags": [ "HTML" ], "summary": "Get HTML page", "description": "Returns rendered HTML content; password-protected pages require X-Password header or ?p= query param", "operationId": "getById_1", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Password", "in": "header", "description": "Access password via header", "required": false, "schema": { "type": "string" } }, { "name": "p", "in": "query", "description": "Access password via query param (alternative to X-Password header)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML content", "content": { "*/*": { "schema": { "type": "string" } } } }, "403": { "description": "Wrong password", "content": { "*/*": { "schema": { "type": "string" } } } }, "404": { "description": "Page not found or expired", "content": { "*/*": { "schema": { "type": "string" } } } } } }, "put": { "tags": [ "HTML" ], "summary": "Update HTML page (accepts JSON or raw text/*)", "description": "Replaces page content while preserving the short URL — share once, edit in place.\nThe link already shared stays valid; readers see the new content on next load.\nPrimary use cases: AI agents iterating on output, fixing typos in already-shared pages.\nImmutable on update: tags, password, format, filename, showTopBar — delete and recreate to change those.\nNo version history: previous content is overwritten. Requires the owner token returned at creation.\nAlso accepts raw text/* bodies — see /llms-full.txt.\n", "operationId": "update_1", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token returned at creation. Required for update and delete", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Primary path: application/json with HtmlUpdateRequest. Fallback paths accept raw text/* bodies — server\nrecords the fallback admission but htmlService.update preserves the stored format. See /llms-full.txt.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlUpdateRequest" } }, "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } }, "text/yaml": { "schema": { "type": "string" } }, "text/xml": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "text/css": { "schema": { "type": "string" } }, "text/javascript": { "schema": { "type": "string" } }, "text/x-toml": { "schema": { "type": "string" } }, "application/xml": { "schema": { "type": "string" } }, "application/yaml": { "schema": { "type": "string" } }, "application/x-yaml": { "schema": { "type": "string" } }, "application/javascript": { "schema": { "type": "string" } }, "application/toml": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Page updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlUpdateResponse" } } } }, "403": { "description": "Missing or wrong owner token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Page not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "HTML" ], "summary": "Delete HTML page", "description": "Permanently removes page and frees the short URL", "operationId": "delete_1", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token returned at creation. Required for update and delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Page deleted" }, "403": { "description": "Missing or wrong owner token" }, "404": { "description": "Page not found or expired" } } } }, "/api/html/{ns}/{id}/settings": { "get": { "tags": [ "HTML" ], "summary": "Get HTML page settings", "description": "Returns the republish-prefill projection (namespace, ttlDays, hasPassword, showTopBar,\nformat, title, filename, createdAt, expiresAt) without the content body. Owner-only —\nrequires the X-Owner-Token returned at creation. Designed for the SPA Republish entry\nfrom gallery cards and the in-page badge: callers supplying a fresh body skip the cost\nof shipping the previous content (HTML rows can be up to 5 MB). Mirrors `/source`'s\n404/403 semantics; a blank token returns 400 with `OWNER_TOKEN_REQUIRED` so the SPA\ncan distinguish \"no token pasted yet\" from \"token rejected\".\n", "operationId": "getHtmlSettings", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token returned at creation. Required for settings access", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Settings projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlSettingsResponse" } } } }, "400": { "description": "Owner token missing (code OWNER_TOKEN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Wrong owner token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Page not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/html/{ns}/{id}/source": { "get": { "tags": [ "HTML" ], "summary": "Get HTML page raw source", "description": "Returns the raw user-submitted body (pre-render, pre-sanitize) plus metadata for\nrepublish (format, title, namespace, id, ttlDays, createdAt, expiresAt, filename,\nshowTopBar). Owner-only — requires the X-Owner-Token returned at creation. The\nserved bytes are the verbatim original — markdown is NOT re-rendered, HTML is NOT\nre-sanitized. A blank token returns 400 with `OWNER_TOKEN_REQUIRED` so the SPA can\ndistinguish \"no token pasted yet\" from \"token rejected\".\n", "operationId": "getHtmlSource", "parameters": [ { "name": "ns", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token returned at creation. Required for source access", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw source body and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlSourceResponse" } } } }, "400": { "description": "Owner token missing (code OWNER_TOKEN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Wrong owner token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Page not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/kv": { "get": { "tags": [ "KV" ], "summary": "List KV stores", "description": "Returns all KV stores owned by the given token in the namespace. Returns empty list without token", "operationId": "listStores", "parameters": [ { "name": "ns", "in": "query", "description": "Namespace", "required": false, "schema": { "type": "string", "default": "public" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token to filter by ownership. Without token returns empty list", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Store list", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KvStoreListResponse" } } } } } } }, "post": { "tags": [ "KV" ], "summary": "Create KV store", "description": "Creates a new store with an initial key-value pair and returns a shareable link. Reuse existing owner token to group entities under one owner", "operationId": "createStore", "parameters": [ { "name": "ns", "in": "query", "description": "Namespace. Default: public. All namespaces are PUBLIC and indexable. Pages in 'public' without password appear in gallery. Custom namespace is created automatically. Format: [a-z0-9-]{3,32}. On ns+id collision the server returns 409 Conflict — retry with a different id or omit id to let the server generate one", "required": false, "schema": { "type": "string", "default": "public", "pattern": "^[a-z0-9-]{3,32}$" } }, { "name": "tags", "in": "query", "description": "Comma-separated tags", "required": false, "schema": { "type": "string" } }, { "name": "ttl", "in": "query", "description": "Time to live in days (1-30, default 15, max 30). Store auto-deletes after expiry", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 30, "default": 15 } }, { "name": "X-Password", "in": "header", "description": "Access password. Empty = public store visible in gallery. With password = hidden from gallery, viewers must enter password or pass ?p= in URL", "required": false, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Reuse existing owner token to group entities under one owner. If omitted, a new token is generated", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KvCreateStoreRequest" } } }, "required": true }, "responses": { "201": { "description": "Store created", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvCreateStoreResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvCreateStoreResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/KvCreateStoreResponse" } } } } } } }, "/api/json": { "get": { "tags": [ "JSON" ], "summary": "List JSON documents", "description": "Returns documents owned by the given token. Empty list without token", "operationId": "list", "parameters": [ { "name": "ns", "in": "query", "description": "Namespace", "required": false, "schema": { "type": "string", "default": "public" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token to filter by ownership. Without token returns empty list", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document list", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JsonListResponse" } } } } } } }, "post": { "tags": [ "JSON" ], "summary": "Create JSON document", "description": "Stores any valid JSON and returns a shareable link. Reuse existing owner token to group entities under one owner", "operationId": "create", "parameters": [ { "name": "ns", "in": "query", "description": "Namespace. Default: public. All namespaces are PUBLIC and indexable. Pages in 'public' without password appear in gallery. Custom namespace is created automatically. Format: [a-z0-9-]{3,32}. On ns+id collision the server returns 409 Conflict — retry with a different id or omit id to let the server generate one", "required": false, "schema": { "type": "string", "default": "public", "pattern": "^[a-z0-9-]{3,32}$" } }, { "name": "tags", "in": "query", "description": "Comma-separated tags", "required": false, "schema": { "type": "string" } }, { "name": "ttl", "in": "query", "description": "Time to live in days (1-30, default 15, max 30). Document auto-deletes after expiry.\nSince v1.49.0 the query string also accepts a suffixed form like `'30d'` or `'30 days'`\n(parsed server-side back to an integer) — useful for clients that prefer human-readable\ndurations.\n", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 30, "default": 15 } }, { "name": "X-Password", "in": "header", "description": "Access password. Empty = public document visible in gallery. With password = hidden from gallery, viewers must enter password or pass ?p= in URL", "required": false, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Reuse existing owner token to group entities under one owner. If omitted, a new token is generated", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "string" } } }, "required": true }, "responses": { "201": { "description": "Document created", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/JsonCreateResponse" } } } }, "400": { "description": "Invalid JSON or request parameters", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/JsonCreateResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/JsonCreateResponse" } } } } } } }, "/api/html": { "post": { "tags": [ "HTML" ], "summary": "Create HTML page (accepts JSON or raw text/*/octet-stream)", "description": "Stores HTML or markdown content and returns a shareable link. Reuse\nexisting owner token to group entities under one owner. Accepts three\ncontent-type families: `application/json` (structured `HtmlUploadRequest`\npayload — primary path), raw `text/*` (HTML, Markdown, YAML, XML, CSV,\ncode — server detects format), and `application/octet-stream` (binary —\nauto-routes to /api/files for png/jpg/gif/webp/mp4/pdf/zip; otherwise\ntext-sniffed). See /llms-full.txt.\n\nIdempotent for the (owner_token, content, public/, 24h) tuple:\na byte-identical repost from the same owner to `ns=public` without a\npassword within 24h returns the existing id. Response status stays\n201 and body shape is unchanged; the silently-merged response carries\nheader `X-Existing-Resource: 1`. To replace content at the same id\nuse `PUT /api/html/{ns}/{id}` (the canonical republish path).\n", "operationId": "create_1", "parameters": [ { "name": "ns", "in": "query", "description": "Namespace. Default: public. All namespaces are PUBLIC and indexable. Pages in 'public' without password appear in gallery. Custom namespace is created automatically. Format: [a-z0-9-]{3,32}. On ns+id collision the server returns 409 Conflict — retry with a different id or omit id to let the server generate one", "required": false, "schema": { "type": "string", "default": "public", "pattern": "^[a-z0-9-]{3,32}$" } }, { "name": "tags", "in": "query", "description": "Comma-separated tags", "required": false, "schema": { "type": "string" } }, { "name": "ttl", "in": "query", "description": "Time to live in days (1-30, default 15, max 30). Page auto-deletes after expiry.\nSince v1.49.0 the query string also accepts a suffixed form like `'30d'` or `'30 days'`\n(parsed server-side back to an integer) — useful for clients that prefer human-readable\ndurations.\n", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 30, "default": 15 } }, { "name": "format", "in": "query", "description": "Content format: 'html' (default), 'markdown', or 'md'. Markdown is rendered to styled HTML with github-markdown-css", "required": false, "schema": { "type": "string", "default": "html" } }, { "name": "X-Password", "in": "header", "description": "Access password. Empty = public page visible in gallery. With password = hidden from gallery, viewers must enter password or pass ?p= in URL", "required": false, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Reuse existing owner token to group entities under one owner. If omitted, a new token is generated", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Primary path: `application/json` with `HtmlUploadRequest`. Fallback paths accept raw text/* and\n`application/octet-stream` bodies — server detects format (or use `?format=`). See `/llms-full.txt`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlUploadRequest" } }, "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } }, "text/yaml": { "schema": { "type": "string" } }, "text/xml": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "text/css": { "schema": { "type": "string" } }, "text/javascript": { "schema": { "type": "string" } }, "text/x-toml": { "schema": { "type": "string" } }, "application/xml": { "schema": { "type": "string" } }, "application/yaml": { "schema": { "type": "string" } }, "application/x-yaml": { "schema": { "type": "string" } }, "application/javascript": { "schema": { "type": "string" } }, "application/toml": { "schema": { "type": "string" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Binary — auto-routes to /api/files for png/jpg/gif/webp/mp4/pdf/zip; otherwise text-sniffed." } } }, "required": true }, "responses": { "201": { "description": "Page created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlUploadResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Unsupported Content-Type — body did not match any supported text/* or application/* fallback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Body parsed but failed validation (e.g. binary detected on text path, size limit exceeded).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/files": { "get": { "tags": [ "Files" ], "summary": "List files", "description": "Returns files owned by the given token. Empty list without token", "operationId": "list_1", "parameters": [ { "name": "ns", "in": "query", "description": "Namespace", "required": false, "schema": { "type": "string", "default": "public" } }, { "name": "X-Owner-Token", "in": "header", "description": "Owner token to filter by ownership. Without token returns empty list", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File list", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileListResponse" } } } } } } }, "post": { "tags": [ "Files" ], "summary": "Upload file", "description": "Stores a file via multipart upload (part name `file`) and returns a download link. Only safe file types\naccepted. Size caps: 5 MB generic, video up to 20 MB, audio up to 5 MB. Up to 1000 files per namespace.\nReuse existing owner token to group entities under one owner.\n", "operationId": "upload", "parameters": [ { "name": "ns", "in": "query", "description": "Namespace. Default: public. All namespaces are PUBLIC and indexable. Pages in 'public' without password appear in gallery. Custom namespace is created automatically. Format: [a-z0-9-]{3,32}. On ns+id collision the server returns 409 Conflict — retry with a different id or omit id to let the server generate one", "required": false, "schema": { "type": "string", "default": "public", "pattern": "^[a-z0-9-]{3,32}$" } }, { "name": "tags", "in": "query", "description": "Comma-separated tags", "required": false, "schema": { "type": "string" } }, { "name": "ttl", "in": "query", "description": "Time to live in days (1-30, default 15, max 30). File auto-deletes after expiry.\nSince v1.49.0 the query string also accepts a suffixed form like `'30d'` or `'30 days'`\n(parsed server-side back to an integer) — useful for clients that prefer human-readable\ndurations.\n", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 30, "default": 15 } }, { "name": "X-Password", "in": "header", "description": "Access password. Empty = public file visible in gallery. With password = hidden from gallery, viewers must enter password or pass ?p= in URL", "required": false, "schema": { "type": "string" } }, { "name": "X-Owner-Token", "in": "header", "description": "Reuse existing owner token to group entities under one owner. If omitted, a new token is generated", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload. The original filename is preserved from the multipart part headers." } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "File uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "400": { "description": "Invalid request or file too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Unsupported file type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "File parsed but failed validation (e.g. extension allowed but content sniffed as a disallowed type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/{ns}/{id}": { "get": { "tags": [ "Short Links" ], "summary": "Resolve short URL", "description": "Resolves a short URL to the underlying resource (HTML, markdown, JSON, KV, file, or site entry).\n\nThe `?raw=1` query parameter bypasses the SPA shell and streams raw resource bytes directly.\nRequired for browser-native consumers that cannot run the SPA wrapper — `