{ "openapi": "3.1.0", "info": { "title": "Hypervalent Public API", "version": "1.0.0", "summary": "The token-authenticated content delivery and authoring API behind Hypervalent Studio.", "description": "Every route lives under `/orgs/{org_id}/projects/{projectSlug}/…` — the project is a **required path segment**, never a query\nparameter — except the two org-level discovery reads (`/token`, `/projects`). Authenticate with an organization API token\n(`atk_…`) in `Authorization: Bearer` or `X-API-Key`. Bodies are JSON with camelCase keys. Read responses for organizations\nwithout the `removeBranding` entitlement carry a `poweredBy` string.\n\nThis document is generated from the server's route table and token allow-list; the schemas are hand-authored beside\nthe shapers they describe. See https://docs.hypervalent.io/api/ for the guide.", "contact": { "name": "Hypervalent", "url": "https://hypervalent.io" } }, "servers": [ { "url": "https://api.hypervalent.io/v1", "description": "Production" } ], "security": [ { "bearerToken": [] }, { "apiKey": [] } ], "tags": [ { "name": "Token", "description": "What a credential may do and reach. Call these first with an organization-wide token." }, { "name": "Structure", "description": "The content model — document types, taxonomies, atoms (field definitions) and molecules (reusable blocks)." }, { "name": "Documents", "description": "Published documents, nested under their document type; drafts through the working view." }, { "name": "Taxonomies", "description": "Taxonomies and their terms." }, { "name": "Settings", "description": "General Settings — admin-defined configuration values." }, { "name": "Design tokens", "description": "The project's design system, as structured JSON, W3C tokens.json, or a CSS custom-property sheet." }, { "name": "Media", "description": "Image, file and video upload." } ], "paths": { "/orgs/{org_id}/projects": { "get": { "tags": [ "Token" ], "operationId": "listProjects", "summary": "List reachable projects", "description": "The projects this token can reach: every live project for an organization-wide token; exactly its own for a project-narrowed one. The only way an organization-wide token discovers project slugs.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "description": "Page size, clamped to the server maximum (50)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "1-based page number. Ignored when `offset` is given." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Row offset — an alternative to `page`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/atoms": { "get": { "tags": [ "Structure" ], "operationId": "listAtoms", "summary": "List atoms (field definitions)", "description": "Every published atom. Root-atom values and content nodes reference atoms by `uuid`; this list is how a consumer resolves them to a field definition.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtomList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Structure" ], "operationId": "createAtom", "summary": "Create an atom", "description": "Create a field definition. `fieldType`, `category`, `fieldConfig` (only the keys the field type reads) and `defaultValue` (a value of the field's own shape) are checked before anything is written — every problem at once, as 422 with `issues`. A draft by default: pass `status: published` to bind it into a molecule or document type straight away. Answers the public atom shape plus `status`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtomWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtomCreated" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/atoms/{slug}": { "get": { "tags": [ "Structure" ], "operationId": "getAtom", "summary": "Get an atom", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtomRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Structure" ], "operationId": "updateAtom", "summary": "Edit an atom", "description": "Edit an atom in the working view (draft or published; trashed is a 404). Every key of `AtomWrite` is optional and an omitted key is left alone; the checks run against the atom as it will be, so a new `fieldType` re-checks the stored `fieldConfig` and `defaultValue` (resend them when they no longer fit; `defaultValue: null` clears it). While the atom is bound in a molecule, document type or taxonomy its `fieldType` and `multiple` cannot change, and `status: draft` is 409 `CANNOT_DRAFT_IN_USE`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtomWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtomCreated" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken. Also: CANNOT_DRAFT_IN_USE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/design-token-schemes": { "get": { "tags": [ "Design tokens" ], "operationId": "listDesignTokenSchemes", "summary": "List design token schemes", "description": "Every published scheme (e.g. light / dark). A token's missing scheme value inherits from the scheme's `baseSchemeSlug`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "token_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by token type (e.g. `color`)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignTokenSchemeList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/design-token-theme": { "get": { "tags": [ "Design tokens" ], "operationId": "getDesignTheme", "summary": "Get the design theme", "description": "The generator input the palettes and color roles are built from: the source color, the M3 scheme variant and the optional secondary / tertiary / neutral key colors, plus the variants a theme may name.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignThemeRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Design tokens" ], "operationId": "updateDesignTheme", "summary": "Save the design theme and regenerate", "description": "Save any of the theme's keys (a key color sent as `null` or `\"\"` is cleared, and the variant then derives that palette from the source) and regenerate every palette and color role from it. Color tokens with `valueSource: manual` keep their values.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignThemeWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignThemeResult" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/design-tokens": { "get": { "tags": [ "Design tokens" ], "operationId": "listDesignTokens", "summary": "List design tokens", "description": "Every published design token, with each scheme value expanded (colors into hex / rgb / hsl forms). `status=draft` (a `read_write` token on a plan with API writes) adds the draft rows — the unpublished component tokens — each carrying its `status`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." }, { "name": "token_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by token type (e.g. `color`)." }, { "name": "component", "in": "query", "schema": { "type": "string" }, "description": "Filter component tokens by their M3 component (e.g. `switch`); comma-separate several." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignTokenList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Design tokens" ], "operationId": "updateDesignTokens", "summary": "Edit design tokens", "description": "Edit up to 200 EXISTING tokens by slug in one transaction — tokens are never created or trashed through the API. `schemeValues` keys replace the stored ones and the rest are kept: a color role is keyed by scheme slug (hex values), a palette by tone, every other type by `default` — a CSS string, a typography composite (merged by property; `fontFamily` names a font-family set), or a component's `{ ref: '.' }` / `{ value }`. A color edit stamps `valueSource: manual` so regeneration keeps it; `valueSource: generated` hands the color back to the generator and regenerates. `status` moves a token between `draft` and `published` (publishing a component's tokens adds it to the export). Every problem is reported at once as 422 with `issues`; nothing is written until all pass.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignTokenEdits" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignTokenEditResult" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/design-tokens.css": { "get": { "tags": [ "Design tokens" ], "operationId": "getDesignTokensCss", "summary": "CSS custom-property export", "description": "A stylesheet of custom properties per scheme (Material 3 roles), ready to link from a site. Errors from this raw export use the nested `{ error }` envelope; an unknown org or project answers a `text/plain` CSS comment.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "responses": { "200": { "description": "OK", "content": { "text/css": { "schema": { "type": "string" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/design-tokens.tokens.json": { "get": { "tags": [ "Design tokens" ], "operationId": "getDesignTokensW3C", "summary": "W3C tokens.json export", "description": "The published tokens in the W3C Design Tokens JSON format. Errors from this raw export use the nested `{ error }` envelope; an unknown org or project answers `{ \"error\": \"Not found\" }`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W3CDesignTokens" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/doctypes": { "get": { "tags": [ "Structure" ], "operationId": "listDocumentTypes", "summary": "List document types", "description": "Every published document type with its published-document count, root-atom bindings (`atoms`), offered `taxonomies` and supported molecule uuids (`supports`).", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTypeList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Structure" ], "operationId": "createDocumentType", "summary": "Create a document type", "description": "Create a content blueprint: root atom bindings, the molecules its content tree may hold at the top level, the taxonomies it offers and its preset tree — every reference a published row of this project, checked before anything is written. The plan's document-type cap applies (403 `LIMIT_EXCEEDED`). A draft by default; documents can be created under a draft document type, but only a published one is served by the reads.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTypeWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTypeCreated" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`) Also: LIMIT_EXCEEDED.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/doctypes/{doctypeSlug}/documents": { "get": { "tags": [ "Documents" ], "operationId": "listDocuments", "summary": "List documents of a type", "description": "One page of the document type's published documents, each with its active version's content and projected root atoms inline. The page's referenced images ship once in `referencedImages`, and the files and videos its file and video fields reference once in `referencedFiles`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "doctypeSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The document type slug — a path namespace, so a draft document type can still own published documents." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "description": "Page size, clamped to the server maximum (50)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "1-based page number. Ignored when `offset` is given." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Row offset — an alternative to `page`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Documents" ], "operationId": "createDocument", "summary": "Create a draft document", "description": "Create a draft document and its first version. The payload is validated against the document type before any write (422 with a per-field `fields` map). Content goes through the editor's own save path, so the write has exactly the guards the editor has. Answers the working view of the new document — the same body `GET …/documents/{slug}?status=draft` serves.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "doctypeSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The document type slug — a path namespace, so a draft document type can still own published documents." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/doctypes/{doctypeSlug}/documents/{slug}": { "get": { "tags": [ "Documents" ], "operationId": "getDocument", "summary": "Get a document", "description": "One document with its version, tagged taxonomy terms (with their content) and referenced images. Anything not published — or not existing — is a plain 404 to a read token.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "doctypeSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The document type slug — a path namespace, so a draft document type can still own published documents." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Documents" ], "operationId": "updateDocument", "summary": "Edit a document", "description": "Edit the working document (draft or published; a trashed document is a 404). `content` / `rootAtoms` / `taxonomyTerms` land on the working version FIRST — an editor holding a fresh checkout refuses the whole save with 409 `VERSION_LOCKED` and nothing is written — then `title` / `description` / `slug` land on the row. Editing a published version with versioning on forks a new draft, as the editor would.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "doctypeSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The document type slug — a path namespace, so a draft document type can still own published documents." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/doctypes/{doctypeSlug}/documents/{slug}/publish": { "post": { "tags": [ "Documents" ], "operationId": "publishDocument", "summary": "Publish a document", "description": "Make the working version live — **visible on the public read API and therefore on the customer's site at once**. Idempotent: an already-published working version is left alone. Lock-checked like any save.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "doctypeSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The document type slug — a path namespace, so a draft document type can still own published documents." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/doctypes/{doctypeSlug}/documents/{slug}/trash": { "post": { "tags": [ "Documents" ], "operationId": "trashDocument", "summary": "Trash a document", "description": "Soft-trash the document. The slug is rewritten to `-trashed-` so the original is free again. There is no purge and no restore through the public surface — an admin restores from Studio.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "doctypeSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The document type slug — a path namespace, so a draft document type can still own published documents." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTrashed" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/doctypes/{doctypeSlug}/documents/{slug}/unpublish": { "post": { "tags": [ "Documents" ], "operationId": "unpublishDocument", "summary": "Unpublish a document", "description": "Move the document row back to draft. Published versions are immutable and stay in the history.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "doctypeSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The document type slug — a path namespace, so a draft document type can still own published documents." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/doctypes/{slug}": { "get": { "tags": [ "Structure" ], "operationId": "getDocumentType", "summary": "Get a document type", "description": "One published document type — the authoring schema a write payload is validated against.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTypeRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Structure" ], "operationId": "updateDocumentType", "summary": "Edit a document type", "description": "Edit a document type in the working view. Every key of `DocumentTypeWrite` is optional; `atoms`, `supports`, `taxonomies` and `content` each REPLACE the stored list or tree when sent. Existing documents keep their stored values; a root atom removed from `atoms` drops out of their reads. Unpublishing a document type that documents use is 409 `CANNOT_DRAFT_IN_USE`. Answers the working-view read.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTypeWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTypeCreated" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken. Also: CANNOT_DRAFT_IN_USE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/library": { "get": { "tags": [ "Structure" ], "operationId": "listLibrary", "summary": "List the atom & molecule library", "description": "The platform's catalogue of ready-made atoms and molecules, which any project can insert. It is the same for every project and says nothing about what a project already holds: compare slugs with `/atoms` and `/molecules`, or call `/library/plan`. Strings are `en-US`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryCatalogue" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/library/insert": { "post": { "tags": [ "Structure" ], "operationId": "insertLibraryItems", "summary": "Insert library items", "description": "Insert items and their whole dependency closure in one all-or-nothing transaction. **Inserted rows are published immediately**, so they can be bound at once. A slug the project already has is reused and never overwritten; a matching draft is published in place. Calling it again changes nothing. Unknown items are 404 `LIBRARY_ITEM_NOT_FOUND`, a malformed list 400 `LIBRARY_ITEMS_INVALID`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryInsert" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryPlan" } } } }, "400": { "description": "LIBRARY_ITEMS_INVALID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/library/plan": { "get": { "tags": [ "Structure" ], "operationId": "planLibraryInsert", "summary": "Plan a library insert", "description": "A dry run of `POST …/library/insert` against this project; writes nothing. Lists every row of the dependency closure with what the insert would do to it: `add`, `reuse` (the slug exists and the project's definition wins) or `publish` (the slug exists as a draft and would be published in place). A `publish` row has no `uuid` unless the token can read drafts. Unknown items are 404 `LIBRARY_ITEM_NOT_FOUND`, a malformed list 400 `LIBRARY_ITEMS_INVALID`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "items", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated `kind:slug` pairs, e.g. `molecule:hero,atom:headline`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryPlan" } } } }, "400": { "description": "LIBRARY_ITEMS_INVALID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/media": { "post": { "tags": [ "Media" ], "operationId": "uploadMedia", "summary": "Upload an image, file or video", "description": "Upload one or more images, files or videos as `multipart/form-data` (`file` / `files` + `title` / `alt`), or one by public URL as JSON `{ url }` fetched server-side. Same ingest pipeline as Studio: content sniffing, a type allow-list (by default JPEG, PNG, WebP, GIF, AVIF and SVG images, PDF, Word, Excel and PowerPoint documents, zip, CSV and plain text, and MP4, WebM and MOV videos), SVG sanitizing, sha256 de-duplication, the plan's storage cap (403 `LIMIT_EXCEEDED`) and async thumbnails for images (files and videos have none, and no `width` / `height`). Per-file size caps, by default 20 MiB for images and files and 30 MiB for videos; a file over its cap is 413 `FILE_TOO_LARGE`. Use the returned `uuid` in an image field (images only), a file field, or a video field (videos only).", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MediaUploadMultipart" } }, "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadByUrl" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadResult" } } } }, "400": { "description": "EMPTY_FILE / UPLOAD_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`) Also: LIMIT_EXCEEDED.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/molecules": { "get": { "tags": [ "Structure" ], "operationId": "listMolecules", "summary": "List molecules (reusable blocks)", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoleculeList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Structure" ], "operationId": "createMolecule", "summary": "Create a molecule", "description": "Create a reusable block: its atom bindings (published atoms of this project, each once, with typed defaults and sibling visibility conditions), the published molecules it may nest (`supports`) and its preset tree (`content`). Checked against the project's published structure before anything is written. A draft by default. Answers the public molecule shape plus `status`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoleculeWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoleculeCreated" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/molecules/{slug}": { "get": { "tags": [ "Structure" ], "operationId": "getMolecule", "summary": "Get a molecule", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoleculeRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Structure" ], "operationId": "updateMolecule", "summary": "Edit a molecule", "description": "Edit a molecule in the working view. Every key of `MoleculeWrite` is optional; `atoms`, `supports` and `content` each REPLACE the stored list or tree when sent (read it with `?status=draft` first) and are left alone when omitted. A `supports` change re-checks the stored preset tree. Unpublishing a molecule another structure supports is 409 `CANNOT_DRAFT_IN_USE`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoleculeWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoleculeCreated" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken. Also: CANNOT_DRAFT_IN_USE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/settings": { "get": { "tags": [ "Settings" ], "operationId": "listSettings", "summary": "List settings", "description": "Every published General Setting with its configured value under `value`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/settings/{slug}": { "get": { "tags": [ "Settings" ], "operationId": "getSetting", "summary": "Get a setting", "description": "One published setting by slug — the read for a single configured value such as `site-title`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/taxonomies": { "get": { "tags": [ "Taxonomies" ], "operationId": "listTaxonomies", "summary": "List taxonomies", "description": "Every published taxonomy with its published-term count, root-atom bindings and the document types that offer it. `?status=draft` lists draft taxonomies too, each with its preset `content`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyList" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Taxonomies" ], "operationId": "createTaxonomy", "summary": "Create a taxonomy", "description": "Create a taxonomy — the term blueprint: root atom bindings, the molecules a term's content tree may hold at the top level and its preset tree, every reference a published row of this project, checked before anything is written (422 with `issues`). The plan's taxonomy cap applies (403 `LIMIT_EXCEEDED`). A draft by default; terms can be created under a draft taxonomy, but a document type can only offer a published one.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyCreated" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`) Also: LIMIT_EXCEEDED.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/taxonomies/{slug}": { "get": { "tags": [ "Taxonomies" ], "operationId": "getTaxonomy", "summary": "Get a taxonomy with a page of its terms", "description": "The taxonomy plus one page of its terms, each with its active version's content inline.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "description": "Page size, clamped to the server maximum (50)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "1-based page number. Ignored when `offset` is given." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Row offset — an alternative to `page`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Taxonomies" ], "operationId": "updateTaxonomy", "summary": "Edit a taxonomy", "description": "Edit a taxonomy in the working view. Every key of `TaxonomyWrite` is optional; `atoms`, `supports` and `content` each REPLACE the stored list or tree when sent (read it with `?status=draft` first). Existing terms keep their stored values. Unpublishing a taxonomy a document type offers or that has live terms is 409 `CANNOT_DRAFT_IN_USE`. Answers the working-view read.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyCreated" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken. Also: CANNOT_DRAFT_IN_USE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/taxonomies/{taxonomySlug}/terms": { "post": { "tags": [ "Taxonomies" ], "operationId": "createTerm", "summary": "Create a draft term", "description": "Create a draft term and its first version under the taxonomy. `parentSlug` must name a live term of the SAME taxonomy. Answers the working view of the new term.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "taxonomySlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The taxonomy slug — a path namespace, like `doctypeSlug`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/taxonomies/{taxonomySlug}/terms/{slug}": { "get": { "tags": [ "Taxonomies" ], "operationId": "getTerm", "summary": "Get a term", "description": "One term with its active version, hydrated like a document. `version` is `null` for a published term that never had a published version.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "taxonomySlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The taxonomy slug — a path namespace, like `doctypeSlug`." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "description": "`published` (default) reads live content. `draft` reads the **working view** — every non-trashed row, draft or published, with its latest working version — and needs a `read_write` token on a plan with API writes. Any other caller reads published, so a read token never learns what draft work exists." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" }, "post": { "tags": [ "Taxonomies" ], "operationId": "updateTerm", "summary": "Edit a term", "description": "Edit the working term: content first (lock check on), then the row — including `parentSlug` (`null` = top level; never itself).", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "taxonomySlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The taxonomy slug — a path namespace, like `doctypeSlug`." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermWrite" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/taxonomies/{taxonomySlug}/terms/{slug}/publish": { "post": { "tags": [ "Taxonomies" ], "operationId": "publishTerm", "summary": "Publish a term", "description": "Make the working version live and the term row published — **visible on the public read API, and in every published document tagged with it, at once**. Idempotent: an already-published working version is left alone. Lock-checked like any save. A term with no version publishes its row alone.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "taxonomySlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The taxonomy slug — a path namespace, like `doctypeSlug`." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/taxonomies/{taxonomySlug}/terms/{slug}/trash": { "post": { "tags": [ "Taxonomies" ], "operationId": "trashTerm", "summary": "Trash a term", "description": "Soft-trash the term. The slug is rewritten to `-trashed-` so the original is free again. A term any document is tagged with is 409 `CANNOT_TRASH_IN_USE`. No purge and no restore through the public surface — an admin restores from Studio.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "taxonomySlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The taxonomy slug — a path namespace, like `doctypeSlug`." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermTrashed" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken. Also: CANNOT_TRASH_IN_USE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/projects/{projectSlug}/taxonomies/{taxonomySlug}/terms/{slug}/unpublish": { "post": { "tags": [ "Taxonomies" ], "operationId": "unpublishTerm", "summary": "Unpublish a term", "description": "Move the term row back to draft. A term any document is tagged with is 409 `CANNOT_DRAFT_IN_USE`.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." }, { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project slug. Discover it with `GET /orgs/{org_id}/projects`. A project-narrowed token may only name its own project (403 `TOKEN_PROJECT_MISMATCH` otherwise)." }, { "name": "taxonomySlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The taxonomy slug — a path namespace, like `doctypeSlug`." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resource slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermRead" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform ; `TOKEN_SCOPE_READ_ONLY` — a `read` token (carries `requiredPlan`); `FEATURE_DISABLED` — the plan has no API writes (carries `requiredPlan`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`VERSION_LOCKED` — an editor holds the checkout (`holder.name`, `expiresAt`; nothing was written); `SLUG_CONFLICT` — the slug is taken. Also: CANNOT_DRAFT_IN_USE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the payload was refused; `fields` names each problem. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`PLATFORM_READ_ONLY` / `PLATFORM_MAINTENANCE` — writes are paused platform-wide; `Retry-After` says how long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read_write", "x-rate-limit": "publicApiWrite (60/min + 2,000/day per credential)" } }, "/orgs/{org_id}/token": { "get": { "tags": [ "Token" ], "operationId": "getToken", "summary": "Who am I", "description": "The presented token's scope, project narrowing, expiry and the public feature trio. A project-narrowed token is a valid caller here (there is no path project to mismatch) and is confined instead.", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The organization's public id — shown in Studio → Settings → API tokens and in the MCP server URL. Never the organization's uuid." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenWhoami" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } }, "/token": { "get": { "tags": [ "Token" ], "operationId": "getTokenOrgless", "summary": "Who am I (no organization)", "description": "The same answer as `GET /orgs/{org_id}/token` plus the organization the token belongs to — for a caller that does not know its organization yet (an MCP client connected by OAuth login). There is no path organization to cross-check; the token's own organization is used.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenWhoamiOrgless" } } } }, "401": { "description": "`API_TOKEN_REQUIRED` — no credential; `INVALID_API_TOKEN` — revoked, expired, unknown, or another organization's token (nested `{ error }` envelope from the authenticator).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "402": { "description": "`BILLING_TERMINATED` — the organization's subscription was terminated for non-payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`TOKEN_ORG_MISMATCH` / `TOKEN_PROJECT_MISMATCH` — the credential does not cover the URL's org or project; `ACCOUNT_CLOSED`; `DELIVERY_BLOCKED` — content delivery for the organization is blocked by the platform", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "404": { "description": "`NOT_FOUND` — unknown org id, project slug, or resource. Never distinguishes \"does not exist\" from \"not published\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — the per-credential limit was hit. `Retry-After` says how long to wait; draft-8 `RateLimit` headers name the policy.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`QUERY_FAILED` — the read or write could not complete. Never an empty 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "x-rate-limit": "publicApi (120/min per credential)" } } }, "components": { "securitySchemes": { "bearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "atk_…", "description": "`Authorization: Bearer atk_…` — an organization API token from Studio → Settings → API tokens." }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same token in an `X-API-Key` header." } }, "schemas": { "Error": { "type": "object", "description": "The flat error envelope handlers answer with (`src/errors/error-handler.js`). `message` is localized; `code` is the stable key to branch on.", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "requiredPlan": { "type": "string", "description": "Set (with `upgrade: true`) when a plan upgrade would unlock the call." }, "upgrade": { "type": "boolean" }, "feature": { "type": "string", "description": "The entitlement slug a `FEATURE_DISABLED` refusal names." }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "On `VALIDATION_ERROR` (422): one message per refused field, keyed by the field name as sent." }, "holder": { "type": "object", "description": "On `VERSION_LOCKED` (409): the display name of the editor holding the checkout — never their email or id.", "properties": { "name": { "type": "string" } } }, "expiresAt": { "type": "string", "format": "date-time", "description": "On `VERSION_LOCKED`: when the editor lock lapses." }, "issues": { "type": "array", "description": "On a structure create's `VALIDATION_ERROR` (atoms, molecules, document types): every refusal with its exact path (`atoms[2].condition.when`, `content[0].children[1].uuid`). `fields` then carries the same messages under the top-level body key.", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "ErrorEnvelope": { "type": "object", "description": "The nested shape middleware answers with — the token authenticator (401 `INVALID_API_TOKEN`, 403 `TOKEN_SCOPE_READ_ONLY`) and the raw design-token exports. Same fields as `Error`, one level down.", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/Error" } } }, "TokenWhoami": { "type": "object", "description": "GET /orgs/{org_id}/token — `shapePublicToken` + `shapePublicFeatures` (`routes/public-org.js`, `routes/public-api.js`).", "required": [ "token", "features" ], "properties": { "token": { "type": "object", "required": [ "prefix", "title", "scope", "projectUuid", "projectSlug", "expiresAt" ], "properties": { "prefix": { "type": "string", "description": "The 12-character display prefix — the only credential fragment that ever appears in a body." }, "title": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "read_write" ] }, "projectUuid": { "type": [ "string", "null" ], "format": "uuid", "description": "`null` for an organization-wide token." }, "projectSlug": { "type": [ "string", "null" ], "description": "`null` for an organization-wide token, or for a narrowed token whose project was deleted." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "features": { "type": "object", "description": "The fixed public feature trio — never the organization's whole entitlement map.", "required": [ "mcpServer", "apiTokensWrite", "removeBranding" ], "properties": { "mcpServer": { "type": "boolean" }, "apiTokensWrite": { "type": "boolean", "description": "Whether this token may write today (scope `read_write` AND the plan allows API writes)." }, "removeBranding": { "type": "boolean" } } }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "TokenWhoamiOrgless": { "type": "object", "description": "GET /token (CMS-687) — the TokenWhoami body plus the token's own organization (`routes/public-org.js`).", "required": [ "token", "org", "features" ], "properties": { "token": { "type": "object", "required": [ "prefix", "title", "scope", "projectUuid", "projectSlug", "expiresAt" ], "properties": { "prefix": { "type": "string", "description": "The 12-character display prefix — the only credential fragment that ever appears in a body." }, "title": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "read_write" ] }, "projectUuid": { "type": [ "string", "null" ], "format": "uuid", "description": "`null` for an organization-wide token." }, "projectSlug": { "type": [ "string", "null" ], "description": "`null` for an organization-wide token, or for a narrowed token whose project was deleted." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "org": { "type": "object", "required": [ "uuid", "slug", "title" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": [ "string", "null" ], "description": "The organization id used in `/orgs/{org_id}/…` paths." }, "title": { "type": [ "string", "null" ] } } }, "features": { "type": "object", "description": "The fixed public feature trio — never the organization's whole entitlement map.", "required": [ "mcpServer", "apiTokensWrite", "removeBranding" ], "properties": { "mcpServer": { "type": "boolean" }, "apiTokensWrite": { "type": "boolean", "description": "Whether this token may write today (scope `read_write` AND the plan allows API writes)." }, "removeBranding": { "type": "boolean" } } }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "Project": { "type": "object", "description": "`shapePublicProject` (`routes/public-org.js`).", "required": [ "uuid", "slug", "title" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" } } }, "ProjectList": { "type": "object", "description": "GET /orgs/{org_id}/projects — every live project for an organization-wide token; exactly its own for a project-narrowed one.", "required": [ "results", "count", "limit", "offset", "page" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "count": { "type": "integer", "description": "The TOTAL number of rows, not the page size." }, "limit": { "type": "integer", "description": "The effective page size after clamping to the server maximum (50)." }, "offset": { "type": "integer" }, "page": { "type": "integer", "description": "1-based page number." }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "Atom": { "type": "object", "description": "A field definition — `shapePublicAtom` (`routes/atomic-atoms.js`). `uuid` is the key a version's `rootAtoms` and content nodes reference the atom by. The working view (`?status=draft`) adds `status`.", "required": [ "uuid", "slug", "title", "description", "icon", "category", "fieldType", "fieldConfig", "multiple", "defaultValue" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "fieldType": { "type": "string", "description": "The editor field type (e.g. `text`, `textarea`, `image`, `select`)." }, "fieldConfig": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Per-field-type options (choices, limits, …)." }, "multiple": { "type": "boolean" }, "defaultValue": { "description": "Any JSON value." } } }, "AtomList": { "type": "object", "description": "GET …/atoms — every published atom in the project.", "required": [ "results", "count" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Atom" } }, "count": { "type": "integer", "description": "Equal to `results.length` — the list is never paginated." }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "AtomRead": { "type": "object", "required": [ "atom" ], "properties": { "atom": { "$ref": "#/components/schemas/Atom" }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "Molecule": { "type": "object", "description": "A reusable content block — `shapePublicMolecule` (`routes/molecules.js`). The working view (`?status=draft`) adds `status`.", "required": [ "uuid", "slug", "title", "description", "icon", "content", "atoms", "supports" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "content": { "type": [ "array", "object", "null" ], "description": "The molecule's content tree (nodes keyed by atom slug/uuid)." }, "atoms": { "type": "array", "items": { "$ref": "#/components/schemas/RootAtomBinding" }, "description": "The atoms an instance of this molecule carries, in editor order — a content node's `atoms` map is keyed by these atoms' slugs." }, "supports": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Uuids of the molecules that may nest inside this one (a node's `children`) — resolve against `/molecules`." } } }, "LibraryAtom": { "type": "object", "description": "A catalogue atom — `atomItem` (`library/index.js`).", "required": [ "kind", "slug", "title", "description", "icon", "category", "fieldType", "multiple" ], "properties": { "kind": { "type": "string", "enum": [ "atom" ] }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "fieldType": { "type": "string" }, "multiple": { "type": "integer", "enum": [ 0, 1 ] } } }, "LibraryMolecule": { "type": "object", "description": "A catalogue molecule — `moleculeItem` (`library/index.js`).", "required": [ "kind", "slug", "title", "description", "icon", "group", "groupTitle", "atoms", "supports", "dependencies" ], "properties": { "kind": { "type": "string", "enum": [ "molecule" ] }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "group": { "type": "string" }, "groupTitle": { "type": "string" }, "atoms": { "type": "array", "description": "The atoms it binds, in editor order.", "items": { "allOf": [ { "$ref": "#/components/schemas/LibraryAtom" }, { "type": "object", "required": [ "required", "locked" ], "properties": { "required": { "type": "boolean" }, "locked": { "type": "boolean" } } } ] } }, "supports": { "type": "array", "items": { "type": "string" }, "description": "Slugs of the molecules that may nest inside it." }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryItemRef" }, "description": "The full closure an insert brings in, minus the molecule itself." } } }, "LibraryItemRef": { "type": "object", "required": [ "kind", "slug" ], "properties": { "kind": { "type": "string", "enum": [ "atom", "molecule" ] }, "slug": { "type": "string" } } }, "LibraryCatalogue": { "type": "object", "description": "GET …/library — `listLibrary` (`library/index.js`).", "required": [ "version", "locale", "groups", "atoms", "molecules" ], "properties": { "version": { "type": "integer" }, "locale": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "required": [ "slug", "title" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" } } } }, "atoms": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryAtom" } }, "molecules": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryMolecule" } }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "LibraryPlanRow": { "type": "object", "required": [ "kind", "slug", "action" ], "properties": { "kind": { "type": "string", "enum": [ "atom", "molecule" ] }, "slug": { "type": "string" }, "action": { "type": "string", "enum": [ "add", "reuse", "publish" ] }, "uuid": { "type": "string", "format": "uuid", "description": "The target row. Absent from a plan's `add` rows (the row does not exist yet) and from its `publish` rows when the token cannot read drafts." } } }, "LibraryPlan": { "type": "object", "description": "The plan (GET …/library/plan) or the result (POST …/library/insert) — `shapeResult` (`atom-library-service.js`).", "required": [ "dryRun", "applied", "rows", "tables", "closure", "inserted", "reused", "published" ], "properties": { "dryRun": { "type": "boolean" }, "applied": { "type": "boolean" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryPlanRow" }, "description": "Every row of the closure, atoms first." }, "tables": { "type": "object", "description": "Counts: `{ atoms, molecules }`, each `{ add, reuse, publish }`." }, "closure": { "type": "object", "description": "The slugs involved: `{ atoms, molecules }`, in dependency order." }, "inserted": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryPlanRow" } }, "reused": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryPlanRow" } }, "published": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryPlanRow" } }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "LibraryInsert": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LibraryItemRef" } } } }, "MoleculeList": { "type": "object", "description": "GET …/molecules — every published molecule in the project.", "required": [ "results", "count" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Molecule" } }, "count": { "type": "integer", "description": "Equal to `results.length` — the list is never paginated." }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "MoleculeRead": { "type": "object", "required": [ "molecule" ], "properties": { "molecule": { "$ref": "#/components/schemas/Molecule" }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "RootAtomBinding": { "type": "object", "description": "An atom binding on a document type, taxonomy (its root atoms) or molecule, in editor order (`rootAtomBindingsColumn`, `queries/helpers/structure-aggregates.js`). Resolve `uuid` against `/atoms`.", "required": [ "uuid", "defaultValue", "locked", "required" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "defaultValue": { "description": "Any JSON value." }, "locked": { "type": "boolean" }, "required": { "type": "boolean" }, "condition": { "type": [ "object", "string", "null" ], "description": "Visibility condition, when one is set." } } }, "TaxonomySummary": { "type": "object", "required": [ "uuid", "slug", "title", "titlePlural", "icon" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "titlePlural": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] } } }, "DocumentTypeSummary": { "type": "object", "required": [ "uuid", "slug", "title", "titlePlural", "icon" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "titlePlural": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] } } }, "DocumentType": { "type": "object", "description": "`shapePublicDocumentType` (`services/public-doctype-service.js`). The preset editor content tree is deliberately not served.", "required": [ "uuid", "slug", "title", "titlePlural", "description", "icon", "status", "versioningEnabled", "dateCreated", "dateModified", "atoms", "supports", "documentCount", "taxonomies" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "titlePlural": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "`published`, or `draft` in the working view (`?status=draft`)." }, "versioningEnabled": { "type": "boolean" }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" }, "content": { "type": [ "array", "null" ], "description": "The preset tree — served in the working view only (`?status=draft`), for an author about to replace it." }, "atoms": { "type": "array", "items": { "$ref": "#/components/schemas/RootAtomBinding" } }, "supports": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Uuids of the molecules a document of this type may nest — resolve against `/molecules`." }, "documentCount": { "type": "integer", "description": "Published documents of this type." }, "taxonomies": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomySummary" }, "description": "The taxonomies this document type offers." } } }, "DocumentTypeList": { "type": "object", "description": "GET …/doctypes — every published document type in the project.", "required": [ "results", "count" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentType" } }, "count": { "type": "integer", "description": "Equal to `results.length` — the list is never paginated." }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "DocumentTypeRead": { "type": "object", "required": [ "documentType" ], "properties": { "documentType": { "$ref": "#/components/schemas/DocumentType" }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "AtomBindingWrite": { "type": "object", "description": "One atom bound into a molecule or document type, in editor order.", "required": [ "uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "A published atom of this project (`GET …/atoms`). Each atom once." }, "defaultValue": { "description": "This binding's default — a value of the atom's own field shape (see `AtomWrite.defaultValue`)." }, "locked": { "type": "boolean" }, "required": { "type": "boolean" }, "condition": { "type": [ "object", "null" ], "description": "Show this field only while a sibling binding matches: `{ when: , operator: equals | notEquals | isEmpty | isNotEmpty, value? }` (`value` required for equals / notEquals).", "properties": { "when": { "type": "string", "format": "uuid" }, "operator": { "type": "string", "enum": [ "equals", "notEquals", "isEmpty", "isNotEmpty" ] }, "value": {} } } } }, "PresetNode": { "type": "object", "description": "A molecule instance in a preset content tree. Every node is given a fresh `key`.", "required": [ "uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The molecule TEMPLATE uuid — at the top a molecule the parent `supports`, below a node a molecule its molecule supports." }, "atoms": { "type": "object", "additionalProperties": true, "description": "Values keyed by the molecule's bound atom SLUGS." }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Nested nodes, same shape." } } }, "AtomWrite": { "type": "object", "required": [ "title", "fieldType" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "description": "Omit to derive a unique slug from the title. Supplied, it is used as-is — a collision is a 409 `SLUG_CONFLICT`." }, "description": { "type": "string", "maxLength": 1024 }, "icon": { "type": "string", "pattern": "^mdi-[a-z0-9-]+$", "description": "A Material Design Icons name." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Only a published atom can be bound into a molecule or document type.", "default": "draft" }, "fieldType": { "type": "string", "enum": [ "text", "textarea", "html", "markdown", "number", "color", "image", "select", "range", "spacing", "date", "boolean", "icon", "link", "video", "file", "email", "tel", "slug" ] }, "category": { "type": "string", "enum": [ "style", "content", "media" ], "default": "content", "description": "Editor layout: `style` atoms edit in the right rail, `content` / `media` in the canvas." }, "multiple": { "type": "boolean", "default": false, "description": "An array of values instead of one." }, "fieldConfig": { "type": "object", "additionalProperties": true, "description": "Only the keys the field type reads: select `options` (required — `[{ value, text?, selected? }]` or strings); number / range `min`, `max`, `step`; html `toolbar` (the toolbar switches, `headings: [1–6]`); image `dragDropEnabled`; image / file / video `maxFileSizeBytes`. Any other key is refused." }, "defaultValue": { "description": "A value of the field's shape: a string for text-like types (a safe link for `link`); a number for number / range, within `min` / `max`; a boolean; one of the option values for select; `{ top?, right?, bottom?, left? }` numbers for spacing; an array of media uuids (or video URLs) for image / file / video. An array of those when `multiple`." } } }, "MoleculeWrite": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "description": "Omit to derive a unique slug from the title." }, "description": { "type": "string", "maxLength": 1024 }, "icon": { "type": "string", "pattern": "^mdi-[a-z0-9-]+$" }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Only a published molecule can be supported by another molecule or a document type.", "default": "draft" }, "atoms": { "type": "array", "items": { "$ref": "#/components/schemas/AtomBindingWrite" } }, "supports": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Published molecules of this project that may nest inside this one." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/PresetNode" }, "description": "The preset tree a fresh use of this molecule starts from — top-level nodes must be molecules in `supports`." } } }, "DocumentTypeWrite": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "titlePlural": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "description": "Omit to derive a unique slug from the title." }, "description": { "type": "string", "maxLength": 1024 }, "icon": { "type": "string", "pattern": "^mdi-[a-z0-9-]+$" }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Never `trashed` on the public surface — a trashed row is a plain 404.", "default": "draft" }, "versioningEnabled": { "type": "boolean", "default": true, "description": "Keep a version history (fork on publish)." }, "atoms": { "type": "array", "items": { "$ref": "#/components/schemas/AtomBindingWrite" }, "description": "The root atoms (top-level fields) of a document of this type." }, "supports": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Published molecules a document's content tree may hold at the top level." }, "taxonomies": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Published taxonomies of this project a document may be tagged in." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/PresetNode" }, "description": "The preset tree every new document starts from — top-level nodes must be molecules in `supports`." } } }, "AtomCreated": { "type": "object", "required": [ "atom" ], "properties": { "atom": { "allOf": [ { "$ref": "#/components/schemas/Atom" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Never `trashed` on the public surface — a trashed row is a plain 404." } } } ] } } }, "MoleculeCreated": { "type": "object", "required": [ "molecule" ], "properties": { "molecule": { "allOf": [ { "$ref": "#/components/schemas/Molecule" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Never `trashed` on the public surface — a trashed row is a plain 404." } } } ] } } }, "DocumentTypeCreated": { "type": "object", "required": [ "documentType" ], "description": "The document type as the working-view read (`GET …/doctypes/{slug}?status=draft`) serves it.", "properties": { "documentType": { "$ref": "#/components/schemas/DocumentType" } } }, "Setting": { "type": "object", "description": "`shapePublicSetting` (`routes/settings.js`) — an admin-defined config field with its configured value.", "required": [ "slug", "title", "description", "fieldType", "multiple", "value" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "fieldType": { "type": "string" }, "multiple": { "type": "boolean" }, "value": { "description": "The configured value — any JSON value, `null` when unset." } } }, "SettingList": { "type": "object", "description": "GET …/settings — every published setting in the project.", "required": [ "results", "count" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Setting" } }, "count": { "type": "integer", "description": "Equal to `results.length` — the list is never paginated." }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "SettingRead": { "type": "object", "required": [ "setting" ], "properties": { "setting": { "$ref": "#/components/schemas/Setting" }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "ColorValue": { "type": "object", "description": "A `color` token value expanded into every common format (`expandColor`, `requests/utilities/cast-design-token-results.js`).", "required": [ "hex", "hexa", "rgb", "rgba", "hsl", "hsla", "components" ], "properties": { "hex": { "type": "string", "example": "#6750A4" }, "hexa": { "type": "string", "example": "#6750A4FF" }, "rgb": { "type": "string", "example": "rgb(103, 80, 164)" }, "rgba": { "type": "string", "example": "rgba(103, 80, 164, 1)" }, "hsl": { "type": "string", "example": "hsl(256, 34%, 48%)" }, "hsla": { "type": "string", "example": "hsla(256, 34%, 48%, 1)" }, "components": { "type": "object", "required": [ "r", "g", "b", "a" ], "properties": { "r": { "type": "integer" }, "g": { "type": "integer" }, "b": { "type": "integer" }, "a": { "type": "number" } } } } }, "DesignToken": { "type": "object", "description": "A published design token row (`design_tokens`, cast by `castDesignTokenRow`). `schemeValues` maps scheme slug → value: a `ColorValue` for `color` tokens, the stored value verbatim for other token types; `schemeValuesRaw` keeps the stored strings.", "required": [ "uuid", "slug", "title", "status", "designTokenType", "schemeValues", "schemeValuesRaw" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "published", "draft" ], "description": "`draft` only in the `status=draft` working view." }, "sortOrder": { "type": [ "integer", "null" ] }, "designTokenType": { "type": "string", "description": "`color`, `typography`, `radius`, `elevation`, `state`, `motion`, `font-family` or `component`." }, "tokenCategory": { "type": [ "string", "null" ] }, "materialRole": { "type": [ "string", "null" ] }, "component": { "type": [ "string", "null" ] }, "componentCategory": { "type": [ "string", "null" ] }, "valueSource": { "type": [ "string", "null" ] }, "schemeValues": { "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/ColorValue" }, { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "schemeValuesRaw": { "type": "object", "additionalProperties": true }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "DesignTokenEdits": { "type": "object", "required": [ "tokens" ], "properties": { "tokens": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "description": "An existing token of this project." }, "schemeValues": { "type": "object", "additionalProperties": true, "description": "Merged into the stored map: scheme slug → hex (color roles), tone → hex (palettes), or `default` → the value (every other type)." }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "valueSource": { "type": "string", "enum": [ "generated", "manual" ], "description": "Color tokens only. `generated` regenerates the color from the theme." } }, "additionalProperties": false } } }, "additionalProperties": false }, "DesignTokenEditResult": { "type": "object", "required": [ "tokens", "updated", "unchanged" ], "properties": { "tokens": { "type": "array", "description": "The changed tokens as stored now.", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "designTokenType": { "type": "string" }, "component": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "valueSource": { "type": "string", "enum": [ "generated", "manual" ] }, "schemeValues": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "updated": { "type": "integer" }, "unchanged": { "type": "integer", "description": "Entries that matched what was stored." }, "regenerated": { "type": "object", "properties": { "generated": { "type": "integer" }, "skipped": { "type": "integer" } }, "description": "Present when a color was handed back to the generator." } }, "additionalProperties": true }, "DesignTheme": { "type": "object", "properties": { "sourceColor": { "type": [ "string", "null" ], "description": "#RRGGBB — what every palette is generated from." }, "variant": { "type": "string", "description": "The M3 scheme variant (`tonalSpot`, `vibrant`, …)." }, "secondaryColor": { "type": [ "string", "null" ] }, "tertiaryColor": { "type": [ "string", "null" ] }, "neutralColor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "DesignThemeRead": { "type": "object", "required": [ "theme", "variants" ], "properties": { "theme": { "$ref": "#/components/schemas/DesignTheme" }, "variants": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "DesignThemeWrite": { "type": "object", "properties": { "sourceColor": { "type": "string", "description": "#RRGGBB." }, "variant": { "type": "string" }, "secondaryColor": { "type": [ "string", "null" ], "description": "#RRGGBB, or null / \"\" to clear." }, "tertiaryColor": { "type": [ "string", "null" ] }, "neutralColor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "DesignThemeResult": { "type": "object", "required": [ "theme", "generated", "skipped" ], "properties": { "theme": { "$ref": "#/components/schemas/DesignTheme" }, "generated": { "type": "integer", "description": "Palette and color-role tokens written." }, "skipped": { "type": "integer", "description": "Manual color overrides left alone." } }, "additionalProperties": true }, "DesignTokenList": { "type": "object", "description": "GET …/design-tokens — every published token, optionally filtered by `?token_type=`.", "required": [ "results", "count" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/DesignToken" } }, "count": { "type": "integer", "description": "Equal to `results.length` — the list is never paginated." }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "DesignTokenScheme": { "type": "object", "description": "A published design token scheme row (`design_token_schemes`). A missing key in a token's `schemeValues` inherits from `baseSchemeSlug`.", "required": [ "uuid", "slug", "title", "status", "designTokenType" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "published" ] }, "sortOrder": { "type": [ "integer", "null" ] }, "designTokenType": { "type": "string" }, "baseSchemeSlug": { "type": [ "string", "null" ] }, "mode": { "type": [ "string", "null" ], "description": "`light` / `dark` for color schemes." }, "contrastLevel": { "type": [ "string", "number", "null" ] }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "DesignTokenSchemeList": { "type": "object", "description": "GET …/design-token-schemes — every published scheme.", "required": [ "results", "count" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/DesignTokenScheme" } }, "count": { "type": "integer", "description": "Equal to `results.length` — the list is never paginated." }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "W3CDesignTokens": { "type": "object", "description": "The W3C Design Tokens Community Group JSON (`toW3CTokens`, `services/design-token-export.js`): nested groups of `{ $type, $value }` leaves. Organizations without `removeBranding` carry the stamp in the top-level `$description`.", "properties": { "$description": { "type": "string" } }, "additionalProperties": true }, "Version": { "type": "object", "description": "The ten-field public version envelope shared by documents and terms — `shapePublicVersion` (`services/public-read-helpers.js`).", "required": [ "uuid", "title", "description", "status", "versionType", "dateCreated", "dateModified", "datePublished", "content", "rootAtoms" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Never `trashed` on the public surface — a trashed row is a plain 404." }, "versionType": { "type": [ "string", "null" ], "enum": [ "version", "template", null ] }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" }, "datePublished": { "type": [ "string", "null" ], "format": "date-time" }, "content": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true }, "description": "The content tree: an array of nodes keyed by atom/molecule slugs. `null` when the version has no content." }, "rootAtoms": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectedRootAtom" } } } }, "ProjectedRootAtom": { "type": "object", "description": "A root-atom VALUE projected against the container's current bindings (`projectVersionRootAtoms`, `queries/helpers/doctype-root-for-version.js`): atoms the type dropped are omitted, atoms it added surface with their default. Resolve `uuid` against `/atoms`.", "required": [ "uuid", "value", "locked", "required" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "value": { "description": "Any JSON value. An image field holds image uuid(s) — look them up in `referencedImages`. A file field holds media uuid(s) — look them up in `referencedFiles`; a non-uuid string there is an external URL written before file fields picked from the media library. A video field holds video uuid(s) — also in `referencedFiles` — and/or external video URLs (YouTube, Vimeo, …) as non-uuid strings." }, "locked": { "type": "boolean" }, "required": { "type": "boolean" } } }, "Image": { "type": "object", "description": "The public image shape — `shapePublicImage` (`routes/media.js`). `cdnUrl` and the thumbnails are absolute CDN URLs.", "required": [ "uuid", "title", "alt", "mime", "sizeBytes", "width", "height", "cdnUrl", "thumb256Url", "thumb1024Url", "dateCreated", "deduped" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "alt": { "type": [ "string", "null" ] }, "mime": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "cdnUrl": { "type": "string", "format": "uri" }, "thumb256Url": { "type": [ "string", "null" ], "format": "uri", "description": "`null` until the async thumbnail job has run." }, "thumb1024Url": { "type": [ "string", "null" ], "format": "uri" }, "dateCreated": { "type": "string", "format": "date-time" }, "deduped": { "type": "boolean", "description": "`true` when an upload matched an existing image by content hash and the existing row was returned." } } }, "ReferencedImage": { "type": "object", "description": "An image referenced by a version's image fields (content or root atoms), in the full image row shape (`castImageRow`). Carries at least the `Image` fields; other columns of the image row may be present.", "allOf": [ { "$ref": "#/components/schemas/Image" } ], "additionalProperties": true }, "ReferencedFile": { "type": "object", "description": "A media-library file or video referenced by a version's file or video fields (content or root atoms) — `shapeReferencedFile` (`queries/images/cast-image-row.js`). `url` is the absolute CDN URL.", "required": [ "uuid", "title", "url", "filename", "mime", "size" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "description": "The name the file was uploaded with." }, "mime": { "type": "string", "description": "The sniffed type, e.g. `application/pdf`." }, "size": { "type": "integer", "description": "Bytes." } } }, "Document": { "type": "object", "description": "The `document` half of a single document read — `shapePublicDocument` (`services/public-document-service.js`).", "required": [ "uuid", "slug", "title", "description", "icon", "status", "dateCreated", "dateModified", "datePublished", "parentUuid", "documentType" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Never `trashed` on the public surface — a trashed row is a plain 404." }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" }, "datePublished": { "type": [ "string", "null" ], "format": "date-time" }, "parentUuid": { "type": [ "string", "null" ], "format": "uuid" }, "documentType": { "$ref": "#/components/schemas/DocumentTypeSummary" } } }, "TaggedTerm": { "type": "object", "description": "A term tagged on a document, with its active version's content inline (`groupTermsByTaxonomy`).", "required": [ "uuid", "slug", "title", "description", "icon", "parentUuid", "parentSlug", "sortOrder", "datePublished", "content", "rootAtoms" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "parentUuid": { "type": [ "string", "null" ], "format": "uuid" }, "parentSlug": { "type": [ "string", "null" ], "description": "The parent term's slug when the parent is published; `null` at the top level." }, "sortOrder": { "type": "integer", "description": "The term's manual position among its siblings (terms sharing its parent); terms are listed in this order, then by title." }, "datePublished": { "type": [ "string", "null" ], "format": "date-time" }, "content": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "rootAtoms": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectedRootAtom" } } } }, "DocumentTaxonomy": { "type": "object", "description": "A taxonomy the document is tagged in, with the tagged terms grouped under it.", "required": [ "uuid", "slug", "title", "titlePlural", "description", "icon", "terms" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "titlePlural": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/TaggedTerm" } } } }, "DocumentRead": { "type": "object", "description": "One document with its version, tagged terms and referenced images. Every document write answers with this same shape (the working view), minus `poweredBy`.", "required": [ "document", "version", "taxonomies", "referencedImages", "referencedFiles" ], "properties": { "document": { "$ref": "#/components/schemas/Document" }, "version": { "oneOf": [ { "$ref": "#/components/schemas/Version" }, { "type": "null" } ] }, "taxonomies": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentTaxonomy" } }, "referencedImages": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedImage" } }, "referencedFiles": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedFile" } }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "ListedDocument": { "type": "object", "description": "One entry of a document list — `shapePublicListedDocument`: the document fields plus the active version's `content` and projected `rootAtoms` inline.", "required": [ "uuid", "slug", "title", "description", "icon", "status", "parentUuid", "dateCreated", "dateModified", "datePublished", "content", "rootAtoms" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Never `trashed` on the public surface — a trashed row is a plain 404." }, "parentUuid": { "type": [ "string", "null" ], "format": "uuid" }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" }, "datePublished": { "type": [ "string", "null" ], "format": "date-time" }, "content": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "rootAtoms": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectedRootAtom" } } } }, "DocumentList": { "type": "object", "description": "GET …/doctypes/{doctypeSlug}/documents — one page of the document type's documents; the page's referenced images ship once at the top level.", "required": [ "documentType", "documents", "referencedImages", "referencedFiles" ], "properties": { "documentType": { "$ref": "#/components/schemas/DocumentTypeSummary" }, "documents": { "type": "object", "required": [ "results", "count", "limit", "offset", "page" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ListedDocument" } }, "count": { "type": "integer", "description": "The TOTAL number of rows, not the page size." }, "limit": { "type": "integer", "description": "The effective page size after clamping to the server maximum (50)." }, "offset": { "type": "integer" }, "page": { "type": "integer", "description": "1-based page number." } } }, "referencedImages": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedImage" } }, "referencedFiles": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedFile" } }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "DocumentTrashed": { "type": "object", "required": [ "document" ], "properties": { "document": { "type": "object", "required": [ "uuid", "slug", "status" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "The rewritten slug `-trashed-` — the original slug is free again." }, "status": { "type": "string", "enum": [ "trashed" ] } } } } }, "DocumentWrite": { "type": "object", "description": "Body for creating or editing a document (`services/public-document-write-service.js`, validated by `validateContainerPayload`). `content` and `rootAtoms` may also be sent as JSON strings.", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Required on create; optional on edit." }, "slug": { "type": "string", "description": "Omit on create to derive a unique slug from the title (`-2`, `-3`, … on collision). Supplied, it is used as-is — a collision is a 409 `SLUG_CONFLICT`." }, "description": { "type": "string" }, "content": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The content tree — an array of nodes shaped like the document type's preset template." }, "rootAtoms": { "type": "object", "additionalProperties": true, "description": "Root-atom values keyed by ATOM UUID (the `uuid` of each entry in the document type's `atoms`). Unknown keys are refused with 422 naming the allowed list. Image fields take image uuid(s) from `POST …/media`." }, "taxonomyTerms": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Uuids of the terms to tag." } } }, "Taxonomy": { "type": "object", "description": "`shapePublicTaxonomy` (`services/public-taxonomy-service.js`). The preset editor content tree is served in the working view only.", "required": [ "uuid", "slug", "title", "titlePlural", "description", "icon", "status", "versioningEnabled", "dateCreated", "dateModified", "atoms", "supports", "termCount", "documentTypes" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "titlePlural": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "`published`, or `draft` in the working view (`?status=draft`). The detail read resolves the taxonomy in any live status — it is the namespace for its terms." }, "versioningEnabled": { "type": "boolean" }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" }, "content": { "type": [ "array", "null" ], "description": "The preset tree every new term starts from — served in the working view only (`?status=draft`), for an author about to replace it." }, "atoms": { "type": "array", "items": { "$ref": "#/components/schemas/RootAtomBinding" }, "description": "The root atoms a term of this taxonomy carries — what term writes validate `rootAtoms` against." }, "supports": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Uuids of the molecules a term's content tree may hold at the top level — resolve against `/molecules`." }, "termCount": { "type": "integer", "description": "Published terms — on the detail read in the working view (`?status=draft`), every non-trashed term (the term page's total)." }, "documentTypes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentTypeSummary" }, "description": "The document types that offer this taxonomy." } } }, "TaxonomyList": { "type": "object", "description": "GET …/taxonomies — every published taxonomy in the project (drafts too with `?status=draft`).", "required": [ "results", "count" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "count": { "type": "integer", "description": "Equal to `results.length` — the list is never paginated." }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "TaxonomyWrite": { "type": "object", "required": [ "title" ], "description": "Body for creating or editing a taxonomy (`services/public-structure-write-service.js`) — `DocumentTypeWrite` without `taxonomies` (document types list the taxonomies they offer).", "properties": { "title": { "type": "string", "maxLength": 255 }, "titlePlural": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "description": "Omit to derive a unique slug from the title." }, "description": { "type": "string", "maxLength": 1024 }, "icon": { "type": "string", "pattern": "^mdi-[a-z0-9-]+$" }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Only a published taxonomy can be offered by a document type.", "default": "draft" }, "versioningEnabled": { "type": "boolean", "default": true, "description": "Keep a version history of every term (fork on publish). Studio's create form defaults this off; the API takes the column default." }, "atoms": { "type": "array", "items": { "$ref": "#/components/schemas/AtomBindingWrite" }, "description": "The root atoms (top-level fields) of a term of this taxonomy." }, "supports": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Published molecules a term's content tree may hold at the top level." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/PresetNode" }, "description": "The preset tree every new term starts from — top-level nodes must be molecules in `supports`." } } }, "TaxonomyCreated": { "type": "object", "required": [ "taxonomy" ], "description": "The taxonomy as the working-view read (`GET …/taxonomies/{slug}?status=draft`) serves it, without the page of terms.", "properties": { "taxonomy": { "$ref": "#/components/schemas/Taxonomy" } } }, "Term": { "type": "object", "description": "`shapePublicTerm` (`services/public-taxonomy-service.js`).", "required": [ "uuid", "slug", "title", "description", "icon", "status", "parentUuid", "parentSlug", "sortOrder", "dateCreated", "dateModified", "datePublished" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Never `trashed` on the public surface — a trashed row is a plain 404." }, "parentUuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The parent term (`null` = top level) — terms are hierarchical within a taxonomy." }, "parentSlug": { "type": [ "string", "null" ], "description": "The parent term's slug when the parent is readable in the same view (published, or any live status in the `status=draft` view); `null` at the top level." }, "sortOrder": { "type": "integer", "description": "The term's manual position among its siblings (terms sharing its parent), as arranged in Studio. Term lists are ordered by it, then by title." }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" }, "datePublished": { "type": [ "string", "null" ], "format": "date-time" } } }, "ListedTerm": { "allOf": [ { "$ref": "#/components/schemas/Term" }, { "type": "object", "required": [ "content", "rootAtoms" ], "properties": { "content": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true }, "description": "`null` for a term that never had a published version." }, "rootAtoms": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectedRootAtom" } } } } ], "description": "One entry of a taxonomy's term page — the term fields plus its active version's content inline." }, "TaxonomyRead": { "type": "object", "description": "GET …/taxonomies/{slug} — the taxonomy plus one page of its published terms.", "required": [ "taxonomy", "terms", "referencedImages", "referencedFiles" ], "properties": { "taxonomy": { "$ref": "#/components/schemas/Taxonomy" }, "terms": { "type": "object", "required": [ "results", "count", "limit", "offset", "page" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ListedTerm" } }, "count": { "type": "integer", "description": "The TOTAL number of rows, not the page size." }, "limit": { "type": "integer", "description": "The effective page size after clamping to the server maximum (50)." }, "offset": { "type": "integer" }, "page": { "type": "integer", "description": "1-based page number." } } }, "referencedImages": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedImage" } }, "referencedFiles": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedFile" } }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "TermRead": { "type": "object", "description": "One term with its active version, hydrated like a document. `version` is `null` for a published term that never had a published version — a legitimate state for terms, unlike documents. Every term write answers with this same shape (the working view), minus `poweredBy`.", "required": [ "term", "version", "referencedImages", "referencedFiles" ], "properties": { "term": { "allOf": [ { "$ref": "#/components/schemas/Term" }, { "type": "object", "required": [ "taxonomy" ], "properties": { "taxonomy": { "$ref": "#/components/schemas/TaxonomySummary" } } } ] }, "version": { "oneOf": [ { "$ref": "#/components/schemas/Version" }, { "type": "null" } ] }, "referencedImages": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedImage" } }, "referencedFiles": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedFile" } }, "poweredBy": { "type": "string", "description": "Present on every read for organizations without the `removeBranding` entitlement (the value is `Powered by Hypervalent`). Never present on write responses." } } }, "TermTrashed": { "type": "object", "required": [ "term" ], "properties": { "term": { "type": "object", "required": [ "uuid", "slug", "status" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "The rewritten slug `-trashed-` — the original slug is free again." }, "status": { "type": "string", "enum": [ "trashed" ] } } } } }, "TermWrite": { "type": "object", "description": "Body for creating or editing a term (`services/public-term-write-service.js`). Same rules as `DocumentWrite`, plus hierarchy.", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Required on create; optional on edit." }, "slug": { "type": "string", "description": "Omit on create to derive a unique slug from the title." }, "description": { "type": "string" }, "parentSlug": { "type": [ "string", "null" ], "description": "The slug of a live term in the SAME taxonomy to nest under; `null` makes the term top-level; absent leaves the parent alone. Never the term itself." }, "content": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "rootAtoms": { "type": "object", "additionalProperties": true, "description": "Root-atom values keyed by atom uuid — must be atoms the taxonomy binds (`atoms` on the taxonomy read)." } } }, "MediaUploadByUrl": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "A public `http(s)` URL of an image, file or video, fetched server-side (max 3 redirects, 10 s). Private/loopback addresses, a served content type the library does not take and a body past the larger upload cap are refused with 422 — `fields.url` names the reason class (`URL_PRIVATE_ADDRESS`, `URL_TOO_LARGE`, `URL_NOT_ACCEPTED`, …). A fetched file over its own type's cap (20 MiB for images and files, 30 MiB for videos by default) is 413 `FILE_TOO_LARGE`, and a sniffed type the library does not take is 415 `UNSUPPORTED_MEDIA_TYPE`." }, "title": { "type": "string" }, "alt": { "type": "string" } } }, "MediaUploadMultipart": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "One image, file or video." }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Several images, files or videos (up to 25 parts per field)." }, "title": { "type": "string" }, "alt": { "type": "string" } } }, "MediaUploadResult": { "type": "object", "description": "A multipart upload answers `{ images, errors }`; a JSON `{ url }` upload answers `{ image }`.", "properties": { "image": { "$ref": "#/components/schemas/Image" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "errors": { "type": "array", "items": { "type": "object", "required": [ "filename", "error" ], "properties": { "filename": { "type": "string" }, "error": { "$ref": "#/components/schemas/Error" } } }, "description": "Per-file failures of a multipart upload (the request still answers 200 when at least one file was stored)." } } } } } }