{"openapi":"3.1.0","info":{"title":"Furnace v1 API","version":"1.0.0","description":"HTTP REST surface for the Furnace platform. Two-layer access: Bearer-token Layer-1 (`api:read` / `api:write`) gates whole verbs; per-namespace Layer-2 RBAC gates resource access. Use `/api/v1/auth/whoami` to verify your token resolves to the expected identity.\n\nPAT requests are limited to 600 requests per minute per user token, with a burst capacity of 100. The shared platform service key is exempt. Responses that run the limiter include `RateLimit` and `RateLimit-Policy`; exhausted requests return 429 with `Retry-After`.\n\n## Versioning and deprecation\n\nThe API is URL-versioned. Platform domains live under `/api/v1`; app operations live on the generated v2 surface, `POST /api/v2/<app>/<read|write>/<operation>` with the input as the JSON body, one operation per contract. Breaking changes ship under a new URL version. Removals use an expand/contract rollout and are announced as deprecated in this specification before removal: an operation marked `deprecated` names its successor in its description."},"servers":[{"url":"https://api.falcata.io","description":"Production"},{"url":"https://{deployment}.convex.site","description":"Per-task ephemeral development deployment","variables":{"deployment":{"default":"carefree-otter-000","description":"Deployment name reported by `bun tools/convex-env.ts status --json`"}}}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token (PAT) issued via access-control, or the platform service key. Security requirements name the Layer-1 `api:read` or `api:write` permission required by each operation; these are RBAC requirements, not OAuth scope strings. Layer-2 RBAC is enforced per resource."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization-code flow with PKCE. The authorization server currently issues only the `full` OAuth scope.","flows":{"authorizationCode":{"authorizationUrl":"https://api.falcata.io/oauth/authorize","tokenUrl":"https://api.falcata.io/oauth/token","scopes":{"full":"Full OAuth scope; Furnace RBAC still controls each operation and resource."}}}}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code when the response defines one"}}},"PaginationMeta":{"type":"object","required":["total","hasMore"],"properties":{"total":{"type":"integer","minimum":0},"hasMore":{"type":"boolean"}}},"PatScope":{"type":"object","description":"Least-privilege narrowing for a Personal Access Token. Each field only restricts — a token without a scope carries the user’s full authority.","properties":{"readOnly":{"type":"boolean","description":"When true, write-mode routes and MCP tools are denied regardless of api:write grants."},"namespaces":{"type":"array","items":{"type":"string"},"description":"Allowlisted app namespaces. Omitted = every namespace the user can already reach."},"permissions":{"type":"array","items":{"type":"string"},"description":"Permission allowlist ANDed with the user’s bundle (wildcard-aware). Omitted = every permission the user holds."},"expiresAt":{"type":"integer","description":"Epoch milliseconds after which the token stops resolving. Omitted = never."}}},"CallerInfo":{"oneOf":[{"type":"object","required":["kind"],"properties":{"kind":{"const":"service"}}},{"type":"object","required":["kind"],"properties":{"kind":{"const":"pat"},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"scope":{"$ref":"#/components/schemas/PatScope"}}}]},"MeBundle":{"type":["object","null"],"description":"Null when the account is banned, suspended, or deactivated.","properties":{"user":{"type":"object","required":["id","createdAt"],"properties":{"id":{"type":"string"},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive"]},"emailSubscribed":{"type":"boolean"},"notificationPrefs":{"$ref":"#/components/schemas/MeNotificationPrefs"},"aiPrefs":{"$ref":"#/components/schemas/MeAiPrefs"},"lastLogin":{"type":["number","null"]},"createdAt":{"type":"number"}}},"profile":{"type":["object","null"],"description":"Display profile KV entry (name, avatarUrl, …).","properties":{"name":{"type":"string"},"avatarUrl":{"type":"string"}},"additionalProperties":true},"subscription":{"type":["object","null"],"description":"Deprecated: the legacy (marozzo) app subscription only. Use `subscriptions`.","properties":{"status":{"type":"string"},"tier":{"type":"string"},"currentPeriodEnd":{"type":"number"},"cancelAtPeriodEnd":{"type":"boolean"}}},"subscriptions":{"type":"array","description":"One entry per app the caller subscribes to.","items":{"$ref":"#/components/schemas/MeSubscription"}}}},"MeSubscription":{"type":"object","required":["app","appName","status","tier","currentPeriodEnd","cancelAtPeriodEnd"],"properties":{"app":{"type":"string","description":"App slug the subscription belongs to."},"appName":{"type":"string","description":"App display name."},"status":{"type":"string"},"tier":{"type":"string"},"currentPeriodEnd":{"type":"number"},"cancelAtPeriodEnd":{"type":"boolean"}}},"MeEmailConsent":{"type":"object","required":["namespace","appName","status","subscribed"],"properties":{"namespace":{"type":"string"},"appName":{"type":"string"},"status":{"type":["string","null"],"enum":["subscribed","unsubscribed","bounced","complained",null],"description":"Subscriber status; null when never subscribed."},"subscribed":{"type":"boolean"}}},"MeNotificationPrefs":{"type":"object","description":"Suppressible notification type → enabled. Opt-out model: a missing key means enabled.","additionalProperties":{"type":"boolean"}},"MeAiPrefs":{"type":"object","description":"Catalogued AI feature key → enabled. Opt-out model: a missing key means enabled.","additionalProperties":{"type":"boolean"}},"MeAiFeatures":{"type":"object","description":"AI feature key → composed availability. `enabled` is the AND of plan entitlement, your preference, remaining budget, and, for credit-metered features while credits are enforced, enough AI credits; `reason` names the first one that failed.","additionalProperties":{"type":"object","required":["enabled","reason","preference","entitled","budget","credits"],"properties":{"enabled":{"type":"boolean"},"reason":{"type":"string","enum":["ok","not_entitled","preference_off","budget_exhausted","credits_exhausted"]},"preference":{"type":"boolean","description":"Your stored choice, independent of the verdict."},"entitled":{"type":"boolean"},"budget":{"type":["object","null"],"description":"Null when nothing is capped, or when usage cannot be attributed (anonymous callers).","properties":{"window":{"type":"string","enum":["day","month"]},"used":{"type":"number"},"limit":{"type":"number"},"remaining":{"type":"number"},"exhausted":{"type":"boolean"}}},"credits":{"type":["object","null"],"description":"Null unless the feature is credit-metered and credits are enforced for you. `needed` is what one turn holds.","properties":{"needed":{"type":"number"},"available":{"type":"number"},"resetsAt":{"type":"number","description":"When the monthly allowance resets (ms since epoch, UTC)."}}}}}},"MePermissionBundle":{"type":"object","required":["roles","permissions","directPermissions","updatedAt"],"properties":{"roles":{"type":"array","items":{"type":"string"}},"permissions":{"type":"array","items":{"type":"string"}},"directPermissions":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"number"}}},"MeSession":{"type":"object","required":["id","createdAt","expiresAt"],"properties":{"id":{"type":"string"},"createdAt":{"type":"number"},"expiresAt":{"type":"number"}}},"KvarkReminder":{"type":"object","required":["remindAt"],"properties":{"remindAt":{"type":"integer","minimum":0,"description":"Epoch milliseconds."},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"description":"Epoch milliseconds."},"channel":{"type":"string","enum":["notification","email","both"]}}},"KvarkAutomationTask":{"type":"object","required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"body":{"type":"string","description":"Plaintext body. Accepted only when the task is server-readable."},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"boardId":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","done"]},"dueAt":{"type":"integer","minimum":0,"description":"Epoch milliseconds."},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"description":"Epoch milliseconds."},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"description":"Epoch milliseconds."},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"]},"titled":{"type":"boolean","description":"True when the identity stores a title; false for derived entry labels."},"bodyReadable":{"type":"boolean","description":"False when the zero-knowledge body is opaque."},"description":{"type":"string","description":"Compatibility alias of body."},"columnId":{"type":"string"},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0},"updatedAt":{"type":"integer","minimum":0}}},"KvarkBoard":{"type":"object","required":["id","name","entryColumnId","order","archived","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"entryColumnId":{"type":"string"},"terminalColumnId":{"type":"string"},"defaultVisibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"ownerNukleonId":{"type":"string"},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0},"updatedAt":{"type":"integer","minimum":0}}},"KvarkBoardColumn":{"type":"object","required":["id","boardId","name","tone","order","archived","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"boardId":{"type":"string"},"name":{"type":"string"},"tone":{"type":"string","enum":["default","positive","warning","info"]},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0},"updatedAt":{"type":"integer","minimum":0}}},"KvarkBoardPlacement":{"type":"object","required":["itemId","boardId","columnId","order","createdAt","updatedAt"],"properties":{"itemId":{"type":"string"},"boardId":{"type":"string"},"columnId":{"type":"string"},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0},"updatedAt":{"type":"integer","minimum":0}}},"ContentAccess":{"type":"string","enum":["inherit","public","auth","membership"]},"ContentStatus":{"type":"string","enum":["draft","published","archived"]},"ContentSummary":{"type":"object","required":["id","title","description","tags","status","path","createdAt","updatedAt","publishedAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/ContentStatus"},"path":{"type":["string","null"]},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"publishedAt":{"type":["integer","null"]}}},"ContentVersion":{"type":"object","required":["body","savedAt","savedBy"],"properties":{"body":{"type":"string"},"savedAt":{"type":"integer"},"savedBy":{"type":"string"},"isPublished":{"type":"boolean"}}},"ContentAuthor":{"type":"object","properties":{"subject":{"type":"string"},"name":{"type":"string"}}},"ContentFeaturedImage":{"type":"object","required":["src","alt"],"properties":{"src":{"type":"string"},"alt":{"type":"string"},"caption":{"type":"string"},"blurhash":{"type":"string"},"assetId":{"type":"string"}}},"ContentTocEntry":{"type":"object","required":["id","text","level"],"properties":{"id":{"type":"string"},"text":{"type":"string"},"level":{"type":"integer"}}},"ContentDocument":{"type":"object","required":["id","title","description","tags","authors","draft","published","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"authors":{"type":"array","items":{"$ref":"#/components/schemas/ContentAuthor"}},"featuredImage":{"oneOf":[{"$ref":"#/components/schemas/ContentFeaturedImage"},{"type":"null"}]},"draft":{"type":"string","description":"Draft markdown body"},"published":{"type":["string","null"],"description":"Published markdown body, null if unpublished"},"toc":{"type":"array","items":{"$ref":"#/components/schemas/ContentTocEntry"}},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"publishedAt":{"type":["integer","null"]},"path":{"type":["string","null"],"description":"Resolved URL path within the namespace"},"customData":{"type":"object","additionalProperties":{"type":"string"}}}},"NavTreeNode":{"type":"object","required":["id","parentId","urlSegment","order","isCategory","status","access","cachedTitle"],"properties":{"id":{"type":"string"},"parentId":{"type":["string","null"]},"urlSegment":{"type":"string"},"order":{"type":"number"},"isCategory":{"type":"boolean"},"status":{"$ref":"#/components/schemas/ContentStatus"},"access":{"$ref":"#/components/schemas/ContentAccess"},"cachedTitle":{"type":"string"},"cachedDescription":{"type":["string","null"]},"hidden":{"type":"boolean","description":"Excluded from reader navigation; still addressable by URL"},"startsAt":{"type":["integer","null"],"description":"Epoch ms; reader visibility opens at this time"},"endsAt":{"type":["integer","null"],"description":"Epoch ms; reader visibility closes at this time"},"path":{"type":"string"}}},"NamespaceTree":{"type":"object","required":["nodes","updatedAt"],"properties":{"nodes":{"type":"array","items":{"$ref":"#/components/schemas/NavTreeNode"}},"updatedAt":{"type":"integer"}}},"ContentLayout":{"type":"object","required":["slug","label","document","createdAt","updatedAt","createdBy"],"properties":{"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"document":{"type":"object","description":"SDL layout document in the layout profile: a Stack/Row/Grid/Split/… tree whose leaves include `ContentSlot` nodes, one per editable region. Statics only — no data, vars, bindings, or conditionals. Validated on write; an invalid document is rejected, never stored."},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"createdBy":{"type":"string"}}},"ContentLayoutInput":{"type":"object","required":["slug","label","document"],"properties":{"slug":{"type":"string","description":"Lowercase-kebab, max 64 chars; `default` and `custom` are reserved"},"label":{"type":"string","description":"Max 120 characters"},"description":{"type":"string","description":"Max 500 characters"},"document":{"type":"object","description":"SDL layout document in the layout profile: a Stack/Row/Grid/Split/… tree whose leaves include `ContentSlot` nodes, one per editable region. Statics only — no data, vars, bindings, or conditionals. Validated on write; an invalid document is rejected, never stored."}}},"AnalyticsOverview":{"type":"object","required":["pageViews","sessions","users","events","pageViewsTrend","sessionsTrend","usersTrend","eventsTrend"],"properties":{"pageViews":{"type":"integer"},"sessions":{"type":"integer"},"users":{"type":"integer"},"events":{"type":"integer"},"pageViewsTrend":{"type":"integer","description":"Percent change vs prior window of equal length"},"sessionsTrend":{"type":"integer"},"usersTrend":{"type":"integer"},"eventsTrend":{"type":"integer"}}},"TimeSeriesPoint":{"type":"object","required":["timestamp","date","value","sessions","users","anonymous"],"properties":{"timestamp":{"type":"integer","description":"Bucket start, epoch ms"},"date":{"type":"string","description":"YYYY-MM-DD"},"value":{"type":"integer"},"sessions":{"type":"integer"},"users":{"type":"integer"},"anonymous":{"type":"integer","description":"Sessions with no authenticated event"}}},"TopPath":{"type":"object","required":["path","events","sessions","users","anonymous","eventsPerSession"],"properties":{"path":{"type":"string"},"events":{"type":"integer"},"sessions":{"type":"integer"},"users":{"type":"integer"},"anonymous":{"type":"integer"},"eventsPerSession":{"type":"number"}}},"TopReferrer":{"type":"object","required":["referrer","sessions","users","anonymous"],"properties":{"referrer":{"type":"string"},"sessions":{"type":"integer"},"users":{"type":"integer"},"anonymous":{"type":"integer"}}},"EventNameStat":{"type":"object","required":["name","count"],"properties":{"name":{"type":"string"},"count":{"type":"integer"}}},"AnalyticsEvent":{"type":"object","required":["namespace","name","timestamp"],"properties":{"namespace":{"type":"string"},"name":{"type":"string"},"timestamp":{"type":"integer","description":"Event time, epoch ms"},"sessionId":{"type":"string"},"userId":{"type":"string","description":"Hashed pseudonym"},"path":{"type":"string"},"referrer":{"type":"string"},"properties":{"type":"object","additionalProperties":true}}},"TopSearch":{"type":"object","required":["query","count","sessions","avgResultCount","zeroResultRate"],"properties":{"query":{"type":"string"},"count":{"type":"integer"},"sessions":{"type":"integer"},"avgResultCount":{"type":"integer"},"zeroResultRate":{"type":"integer","description":"Percent of runs returning no results"}}},"FeedbackStats":{"type":"object","required":["total","trend","timeSeries","withAttachments","attachmentRate"],"properties":{"total":{"type":"integer"},"trend":{"type":"integer","description":"Percent change vs prior window"},"timeSeries":{"type":"array","items":{"type":"object","required":["timestamp","date","value"],"properties":{"timestamp":{"type":"integer"},"date":{"type":"string"},"value":{"type":"integer"}}}},"withAttachments":{"type":"integer"},"attachmentRate":{"type":"integer"}}},"UserActivityStats":{"type":"object","required":["totalPageViews","totalSessions","sparklineData","topPages"],"properties":{"totalPageViews":{"type":"integer"},"totalSessions":{"type":"integer"},"sparklineData":{"type":"array","items":{"type":"integer"}},"topPages":{"type":"array","items":{"type":"object","required":["path","count"],"properties":{"path":{"type":"string"},"count":{"type":"integer"}}}}}},"StudioQuerySpec":{"type":"object","properties":{"source":{"type":"string","enum":["analytics"],"description":"Always \"analytics\"."},"namespace":{"type":"string","description":"Which app/tenant to query. Must be one of the namespaces listed as available to you in the system prompt."},"eventName":{"type":"string","description":"Optional: restrict to a single event name (e.g. \"page_view\", \"ai_chat\"). Omit to include all events."},"filters":{"type":"array","description":"Optional: up to 10 equality filters, all of which must match (AND).","items":{"type":"object","properties":{"field":{"type":"string","description":"One of: path, referrer, name, or properties.<key> (e.g. \"properties.tier\")."},"op":{"type":"string","enum":["eq","neq","in"],"description":"\"eq\"/\"neq\" compare to a single string value; \"in\" matches any value in an array."},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"A string for \"eq\"/\"neq\"; an array of strings for \"in\"."}},"required":["field","op","value"],"additionalProperties":false}},"groupBy":{"type":"object","description":"Optional: break the measure down by one dimension. Omit for a single total (big number).","properties":{"dimension":{"type":"string","description":"One of: path, referrer, name, time, or properties.<key>. Use \"time\" for a trend across the window."},"timeBucket":{"type":"string","enum":["hour","day","week"],"description":"Only with dimension \"time\": the bucket width. Defaults to \"day\"."}},"required":["dimension"],"additionalProperties":false},"series":{"type":"object","description":"Optional: split the measure into multiple series by a SECOND categorical dimension — e.g. groupBy \"time\" + series by \"name\" draws one line per event type; groupBy a category + series draws grouped bars. Requires groupBy and must differ from it. Use only when comparing a handful of categories across the primary axis.","properties":{"dimension":{"type":"string","description":"One of: path, referrer, name, or properties.<key>. NOT \"time\" — time is the primary axis."},"limit":{"type":"number","description":"Optional: keep only the top-N series by measure (default 6, max 8)."}},"required":["dimension"],"additionalProperties":false},"measure":{"type":"object","description":"What to compute over the matched events.","properties":{"fn":{"type":"string","enum":["count","sessions","users","anonymous","sum","avg","p50","p95"],"description":"count = number of events; sessions/users/anonymous = distinct counts; sum/avg/p50/p95 = numeric statistics over a property field."},"field":{"type":"string","description":"Required for sum/avg/p50/p95: a properties.<key> holding a number (e.g. \"properties.estimatedCostUsd\"). Omit for count/sessions/users/anonymous."}},"required":["fn"],"additionalProperties":false},"range":{"description":"The time window. Either a trailing number of days, or absolute since/until in epoch milliseconds. Capped server-side at 90 days.","anyOf":[{"type":"object","properties":{"days":{"type":"number","description":"Trailing window length in days (1–90)."}},"required":["days"],"additionalProperties":false},{"type":"object","properties":{"since":{"type":"number","description":"Window start, epoch milliseconds."},"until":{"type":"number","description":"Window end, epoch milliseconds. Defaults to now."}},"required":["since"],"additionalProperties":false}]},"limit":{"type":"number","description":"Optional: max rows for a categorical breakdown (1–100, default 50). Ignored for a time series, which is always returned whole."},"kind":{"type":"string","enum":["aggregate","experiment"],"description":"The query type. Omit or \"aggregate\" for the normal measure/groupBy analytics above. \"experiment\" instead measures an A/B experiment: it correlates flag exposures with a later outcome event to report per-variant conversion — set flagKey + outcomeEvent (and optionally exposureEvent) plus a range; measure/groupBy/series/filters/limit do not apply."},"flagKey":{"type":"string","description":"Experiment kind only: the experiment flag key whose variants to measure (matched against exposure events' properties.flag)."},"outcomeEvent":{"type":"string","description":"Experiment kind only: the event name that counts as a conversion (e.g. \"checkout_complete\", \"signup\"). A variant converts when an exposed identity emits this event at or after its first exposure."},"exposureEvent":{"type":"string","description":"Experiment kind only, optional: the exposure event name. Defaults to \"experiment_exposure\" (what the flag client emits on first variant read)."}},"required":["source","namespace","measure","range"],"additionalProperties":false},"StudioChartRef":{"type":"object","properties":{"kind":{"type":"string","enum":["stat","area","line","bar","column","table","multiLine","groupedBar","stackedBar","stackedArea"]},"title":{"type":"string"},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["analytics"],"description":"Always \"analytics\"."},"namespace":{"type":"string","description":"Which app/tenant to query. Must be one of the namespaces listed as available to you in the system prompt."},"eventName":{"type":"string","description":"Optional: restrict to a single event name (e.g. \"page_view\", \"ai_chat\"). Omit to include all events."},"filters":{"type":"array","description":"Optional: up to 10 equality filters, all of which must match (AND).","items":{"type":"object","properties":{"field":{"type":"string","description":"One of: path, referrer, name, or properties.<key> (e.g. \"properties.tier\")."},"op":{"type":"string","enum":["eq","neq","in"],"description":"\"eq\"/\"neq\" compare to a single string value; \"in\" matches any value in an array."},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"A string for \"eq\"/\"neq\"; an array of strings for \"in\"."}},"required":["field","op","value"],"additionalProperties":false}},"groupBy":{"type":"object","description":"Optional: break the measure down by one dimension. Omit for a single total (big number).","properties":{"dimension":{"type":"string","description":"One of: path, referrer, name, time, or properties.<key>. Use \"time\" for a trend across the window."},"timeBucket":{"type":"string","enum":["hour","day","week"],"description":"Only with dimension \"time\": the bucket width. Defaults to \"day\"."}},"required":["dimension"],"additionalProperties":false},"series":{"type":"object","description":"Optional: split the measure into multiple series by a SECOND categorical dimension — e.g. groupBy \"time\" + series by \"name\" draws one line per event type; groupBy a category + series draws grouped bars. Requires groupBy and must differ from it. Use only when comparing a handful of categories across the primary axis.","properties":{"dimension":{"type":"string","description":"One of: path, referrer, name, or properties.<key>. NOT \"time\" — time is the primary axis."},"limit":{"type":"number","description":"Optional: keep only the top-N series by measure (default 6, max 8)."}},"required":["dimension"],"additionalProperties":false},"measure":{"type":"object","description":"What to compute over the matched events.","properties":{"fn":{"type":"string","enum":["count","sessions","users","anonymous","sum","avg","p50","p95"],"description":"count = number of events; sessions/users/anonymous = distinct counts; sum/avg/p50/p95 = numeric statistics over a property field."},"field":{"type":"string","description":"Required for sum/avg/p50/p95: a properties.<key> holding a number (e.g. \"properties.estimatedCostUsd\"). Omit for count/sessions/users/anonymous."}},"required":["fn"],"additionalProperties":false},"range":{"description":"The time window. Either a trailing number of days, or absolute since/until in epoch milliseconds. Capped server-side at 90 days.","anyOf":[{"type":"object","properties":{"days":{"type":"number","description":"Trailing window length in days (1–90)."}},"required":["days"],"additionalProperties":false},{"type":"object","properties":{"since":{"type":"number","description":"Window start, epoch milliseconds."},"until":{"type":"number","description":"Window end, epoch milliseconds. Defaults to now."}},"required":["since"],"additionalProperties":false}]},"limit":{"type":"number","description":"Optional: max rows for a categorical breakdown (1–100, default 50). Ignored for a time series, which is always returned whole."},"kind":{"type":"string","enum":["aggregate","experiment"],"description":"The query type. Omit or \"aggregate\" for the normal measure/groupBy analytics above. \"experiment\" instead measures an A/B experiment: it correlates flag exposures with a later outcome event to report per-variant conversion — set flagKey + outcomeEvent (and optionally exposureEvent) plus a range; measure/groupBy/series/filters/limit do not apply."},"flagKey":{"type":"string","description":"Experiment kind only: the experiment flag key whose variants to measure (matched against exposure events' properties.flag)."},"outcomeEvent":{"type":"string","description":"Experiment kind only: the event name that counts as a conversion (e.g. \"checkout_complete\", \"signup\"). A variant converts when an exposed identity emits this event at or after its first exposure."},"exposureEvent":{"type":"string","description":"Experiment kind only, optional: the exposure event name. Defaults to \"experiment_exposure\" (what the flag client emits on first variant read)."}},"required":["source","namespace","measure","range"],"additionalProperties":false},"window":{"type":"object","description":"Generation-time snapshot of the resolved window. Stored, but not authoritative: `spec.range` decides the span a chart shows, so a relative `{days}` range slides forward on every load while this stays pinned. Send the window the spec resolves to now.","properties":{"since":{"type":"integer"},"until":{"type":"integer"}},"required":["since","until"]},"targetSlug":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"Optional kebab-case app slug this widget targets (cross-app dashboards)."}},"required":["kind","title","spec","window"],"additionalProperties":false},"StudioQueryResult":{"type":"object","required":["rows","rowCount","window","spec"],"properties":{"rows":{"type":"array","description":"Single-dimension aggregation: one row per group (or a single total when there is no groupBy).","items":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string","description":"Group value — a path/referrer/name, or the ISO date for a time bucket."},"bucket":{"type":"integer","description":"Bucket start (epoch ms) when grouping by time; absent otherwise."},"value":{"type":"number"}}}},"pivot":{"type":"object","description":"Present only when the spec carries a `series` split — the multi-series breakdown.","required":["seriesNames","rows"],"properties":{"seriesNames":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","required":["key","values"],"properties":{"key":{"type":"string"},"bucket":{"type":"integer"},"values":{"type":"array","items":{"type":"number"},"description":"Aligned with seriesNames."}}}}}},"rowCount":{"type":"integer"},"window":{"type":"object","required":["since","until"],"properties":{"since":{"type":"integer"},"until":{"type":"integer"}}},"spec":{"$ref":"#/components/schemas/StudioQuerySpec"}}},"StudioDashboard":{"type":"object","required":["id","name","charts","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"charts":{"type":"array","items":{"$ref":"#/components/schemas/StudioChartRef"}},"createdAt":{"type":"integer","description":"Epoch ms"},"updatedAt":{"type":"integer","description":"Epoch ms"}}},"MarozzoSource":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string"},"snippet":{"type":"string"}}},"MarozzoChatResult":{"oneOf":[{"type":"object","required":["threadId","message","sources","truncated"],"properties":{"threadId":{"type":"string"},"message":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/MarozzoSource"}},"truncated":{"type":"boolean"}}},{"type":"object","required":["refused"],"properties":{"refused":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}}}}]},"MarozzoMessage":{"type":"object","required":["id","role","content","createdAt"],"properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"createdAt":{"type":"integer"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/MarozzoSource"}}}},"MarozzoThreadHistory":{"type":"object","required":["thread","messages"],"properties":{"thread":{"type":"object","required":["id","createdAt"],"properties":{"id":{"type":"string"},"title":{"type":["string","null"]},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"takeaways":{"type":"array","items":{"type":"string"}}}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/MarozzoMessage"}}}},"DictionaryHit":{"type":"object","required":["source","headword","score","snippet","citation"],"properties":{"source":{"type":"string","enum":["florio","crusca"]},"headword":{"type":"string"},"score":{"type":"number"},"snippet":{"type":"string"},"citation":{"type":"string"}}},"TreatiseHit":{"type":"object","required":["source","book","chapter","title","score","snippet","citation"],"properties":{"source":{"type":"string","enum":["manciolino","opera_nova","dall_agocchie"]},"book":{"type":"integer"},"chapter":{"type":"integer"},"title":{"type":"string"},"score":{"type":"number"},"snippet":{"type":"string"},"citation":{"type":"string"}}},"HeroPromo":{"type":"object","required":["id","badge","message","ctaLabel","ctaHref","enabled","order","startsAt","endsAt","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"badge":{"type":"string"},"message":{"type":"string"},"ctaLabel":{"type":"string"},"ctaHref":{"type":"string"},"enabled":{"type":"boolean"},"order":{"type":"integer"},"startsAt":{"type":["integer","null"]},"endsAt":{"type":["integer","null"]},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"}}},"HeroPromoInput":{"type":"object","required":["badge","message","ctaHref","enabled"],"properties":{"badge":{"type":"string"},"message":{"type":"string"},"ctaLabel":{"type":"string","description":"Empty string makes the whole pill clickable"},"ctaHref":{"type":"string","description":"Internal path (starts with /) or external URL"},"enabled":{"type":"boolean"},"startsAt":{"type":["integer","null"],"description":"Epoch ms, or null for no lower bound"},"endsAt":{"type":["integer","null"],"description":"Epoch ms, or null for no upper bound"}}},"MediaReplaceFile":{"type":"object","properties":{"id":{"type":"string","description":"Existing mediaAssets id (must be type file)"},"mimeType":{"type":"string"},"originalName":{"type":"string"},"size":{"type":"integer"},"fileData":{"type":"string","description":"base64-encoded file bytes (no data: prefix), max 10 MB binary"},"extension":{"type":"string"}},"required":["mimeType","originalName","size","fileData","extension"]},"MediaAlias":{"type":"object","required":["assetId","visibility","updatedAt","updatedBy","url","mimeType","processingStatus","versions"],"properties":{"assetId":{"type":"string"},"visibility":{"type":"string","enum":["public","protected"]},"updatedAt":{"type":"number"},"updatedBy":{"type":"string"},"url":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"processingStatus":{"type":["string","null"],"enum":["pending","processing","ready","failed",null]},"versions":{"type":"array","items":{"type":"object","required":["v","assetId","setAt","setBy","url"],"properties":{"v":{"type":"integer"},"assetId":{"type":"string"},"size":{"type":"integer"},"sha256":{"type":"string","description":"SHA-256 hex of the original asset bytes, when stored"},"mimeType":{"type":"string"},"visibility":{"type":"string","enum":["public","protected"]},"processingStatus":{"type":"string","enum":["pending","processing","ready","failed"]},"setAt":{"type":"number"},"setBy":{"type":"string"},"label":{"type":"string","maxLength":80},"url":{"type":["string","null"]},"path":{"type":"string","description":"Versioned /x/ path; present only for public aliases"}}}}}},"ImageVariant":{"type":"object","required":["storageKey","width","height","size","mimeType"],"properties":{"storageKey":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"mimeType":{"type":"string"}}},"MediaAsset":{"type":"object","required":["_id","type","mimeType","originalName","size","visibility","processingStatus","createdAt"],"properties":{"_id":{"type":"string"},"type":{"type":"string","enum":["image","file","audio"]},"mimeType":{"type":"string"},"originalName":{"type":"string"},"displayName":{"type":"string"},"durationSec":{"type":"number"},"source":{"type":"string","enum":["recorder","upload"]},"storageKey":{"type":"string"},"sourceStorageKey":{"type":"string"},"imageVariantVersion":{"type":"integer"},"imageVariants":{"type":"object","properties":{"thumb":{"$ref":"#/components/schemas/ImageVariant"},"card":{"$ref":"#/components/schemas/ImageVariant"},"hero":{"$ref":"#/components/schemas/ImageVariant"},"full":{"$ref":"#/components/schemas/ImageVariant"},"square":{"$ref":"#/components/schemas/ImageVariant"}}},"size":{"type":"integer"},"tags":{"type":"array","items":{"type":"string"}},"visibility":{"type":"string","enum":["public","protected"]},"allowedNamespaces":{"type":"array","items":{"type":"string"},"description":"PROTECTED-only namespace allowlist for the signed-URL mint gate. Absent for public assets."},"processingStatus":{"type":"string","enum":["pending","processing","ready","failed"]},"blurhash":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"uploadedBy":{"type":"string"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"}}},"VideoAsset":{"type":"object","required":["_id","bunnyVideoId","bunnyLibraryId","title","visibility","createdAt"],"properties":{"_id":{"type":"string"},"bunnyVideoId":{"type":"string"},"bunnyLibraryId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","protected"]},"allowedNamespaces":{"type":"array","items":{"type":"string"},"description":"PROTECTED-only namespace allowlist for the signed-URL mint gate. Absent for public videos."},"duration":{"type":"number"},"thumbnailUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"uploadStatus":{"type":"string","enum":["uploading","processing","ready","failed"]},"uploadedBy":{"type":"string"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"}}},"PatListEntry":{"type":"object","required":["hash","label","createdAt"],"properties":{"hash":{"type":"string","description":"SHA-256 fingerprint of the token (not the secret)."},"label":{"type":"string"},"createdAt":{"type":"integer"},"lastUsedAt":{"type":"integer"},"revokedAt":{"type":"integer"},"scope":{"$ref":"#/components/schemas/PatScope"}}},"WebMeta":{"type":"object","required":["trace","ms"],"properties":{"trace":{"type":"string"},"ms":{"type":"number"}}},"WebSearchResult":{"type":"object","required":["url","title","snippet","bucket"],"properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippet":{"type":"string"},"time":{"type":"string"},"bucket":{"type":"string"}}},"WebExtractedPage":{"type":"object","required":["url","markdown","truncated"],"properties":{"url":{"type":"string","format":"uri"},"markdown":{"type":["string","null"]},"error":{"type":"string"},"truncated":{"type":"boolean"}}},"WebSearchResponse":{"type":"object","required":["results","related","extracted","meta"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/WebSearchResult"}},"related":{"type":"array","items":{"type":"string"}},"extracted":{"type":"array","items":{"$ref":"#/components/schemas/WebExtractedPage"}},"meta":{"$ref":"#/components/schemas/WebMeta"}}},"WebExtractResponse":{"type":"object","required":["pages","meta"],"properties":{"pages":{"type":"array","items":{"$ref":"#/components/schemas/WebExtractedPage"}},"meta":{"$ref":"#/components/schemas/WebMeta"}}},"WorkflowDefinition":{"oneOf":[{"type":"object","required":["schemaVersion","workflowKey","startNodeId","nodes"],"properties":{"schemaVersion":{"const":1},"workflowKey":{"type":"string"},"startNodeId":{"type":"string"},"nodes":{"type":"array","minItems":1,"maxItems":64,"items":{"oneOf":[{"type":"object","required":["id","kind","executorKey","executorVersion","config","input"],"properties":{"id":{"type":"string"},"kind":{"const":"task"},"executorVersion":{"const":1},"input":{"oneOf":[{"type":"object","required":["source"],"properties":{"source":{"const":"initial"}},"additionalProperties":false},{"type":"object","required":["source","nodeId"],"properties":{"source":{"const":"node"},"nodeId":{"type":"string"}},"additionalProperties":false}]},"nextNodeId":{"type":"string"},"retry":{"type":"object","required":["maxAttempts","initialBackoffMs"],"properties":{"maxAttempts":{"type":"integer","minimum":1,"maximum":10},"initialBackoffMs":{"type":"integer","minimum":1,"maximum":60000},"base":{"type":"number","minimum":1,"maximum":10,"default":2}},"additionalProperties":false},"executorKey":{"const":"artifact.identity"},"config":{"type":"object","additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["id","kind","executorKey","executorVersion","config","input"],"properties":{"id":{"type":"string"},"kind":{"const":"task"},"executorVersion":{"const":1},"input":{"oneOf":[{"type":"object","required":["source"],"properties":{"source":{"const":"initial"}},"additionalProperties":false},{"type":"object","required":["source","nodeId"],"properties":{"source":{"const":"node"},"nodeId":{"type":"string"}},"additionalProperties":false}]},"nextNodeId":{"type":"string"},"retry":{"type":"object","required":["maxAttempts","initialBackoffMs"],"properties":{"maxAttempts":{"type":"integer","minimum":1,"maximum":10},"initialBackoffMs":{"type":"integer","minimum":1,"maximum":60000},"base":{"type":"number","minimum":1,"maximum":10,"default":2}},"additionalProperties":false},"executorKey":{"const":"artifact.append"},"config":{"type":"object","required":["suffix"],"properties":{"suffix":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["id","kind","childNodeIds","nextNodeId"],"properties":{"id":{"type":"string"},"kind":{"const":"parallel"},"childNodeIds":{"type":"array","minItems":2,"maxItems":16,"items":{"type":"string"}},"nextNodeId":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["id","kind","input","equalsArtifactId","whenTrueNodeId","whenFalseNodeId"],"properties":{"id":{"type":"string"},"kind":{"const":"branch"},"input":{"oneOf":[{"type":"object","required":["source"],"properties":{"source":{"const":"initial"}},"additionalProperties":false},{"type":"object","required":["source","nodeId"],"properties":{"source":{"const":"node"},"nodeId":{"type":"string"}},"additionalProperties":false}]},"equalsArtifactId":{"type":"string"},"whenTrueNodeId":{"type":"string"},"whenFalseNodeId":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["id","kind","eventName","nextNodeId"],"properties":{"id":{"type":"string"},"kind":{"const":"wait"},"eventName":{"type":"string"},"nextNodeId":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["id","kind","input"],"properties":{"id":{"type":"string"},"kind":{"const":"output"},"input":{"oneOf":[{"type":"object","required":["source"],"properties":{"source":{"const":"initial"}},"additionalProperties":false},{"type":"object","required":["source","nodeId"],"properties":{"source":{"const":"node"},"nodeId":{"type":"string"}},"additionalProperties":false}]}},"additionalProperties":false}]}}},"additionalProperties":false},{"type":"object","required":["schemaVersion","workflowKey","startNodeId","nodes"],"properties":{"schemaVersion":{"const":2},"workflowKey":{"type":"string"},"startNodeId":{"type":"string"},"nodes":{"type":"array","minItems":1,"maxItems":64,"items":{"oneOf":[{"type":"object","required":["id","kind","executorKey","executorVersion","config","inputs"],"properties":{"id":{"type":"string"},"kind":{"const":"task"},"inputs":{"type":"array","minItems":1,"maxItems":4,"items":{"oneOf":[{"type":"object","required":["source"],"properties":{"source":{"const":"initial"}},"additionalProperties":false},{"type":"object","required":["source","nodeId"],"properties":{"source":{"const":"node"},"nodeId":{"type":"string"}},"additionalProperties":false}]}},"nextNodeId":{"type":"string"},"retry":{"type":"object","required":["maxAttempts","initialBackoffMs"],"properties":{"maxAttempts":{"type":"integer","minimum":1,"maximum":10},"initialBackoffMs":{"type":"integer","minimum":1,"maximum":60000},"base":{"type":"number","minimum":1,"maximum":10,"default":2}},"additionalProperties":false},"executorKey":{"const":"artifact.identity"},"executorVersion":{"const":1},"config":{"type":"object","additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["id","kind","executorKey","executorVersion","config","inputs"],"properties":{"id":{"type":"string"},"kind":{"const":"task"},"inputs":{"type":"array","minItems":1,"maxItems":4,"items":{"oneOf":[{"type":"object","required":["source"],"properties":{"source":{"const":"initial"}},"additionalProperties":false},{"type":"object","required":["source","nodeId"],"properties":{"source":{"const":"node"},"nodeId":{"type":"string"}},"additionalProperties":false}]}},"nextNodeId":{"type":"string"},"retry":{"type":"object","required":["maxAttempts","initialBackoffMs"],"properties":{"maxAttempts":{"type":"integer","minimum":1,"maximum":10},"initialBackoffMs":{"type":"integer","minimum":1,"maximum":60000},"base":{"type":"number","minimum":1,"maximum":10,"default":2}},"additionalProperties":false},"executorKey":{"const":"artifact.append"},"executorVersion":{"const":1},"config":{"type":"object","required":["suffix"],"properties":{"suffix":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["id","kind","childNodeIds","nextNodeId"],"properties":{"id":{"type":"string"},"kind":{"const":"parallel"},"childNodeIds":{"type":"array","minItems":2,"maxItems":16,"items":{"type":"string"}},"nextNodeId":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["id","kind","input","condition","whenTrueNodeId","whenFalseNodeId"],"properties":{"id":{"type":"string"},"kind":{"const":"branch"},"input":{"oneOf":[{"type":"object","required":["source"],"properties":{"source":{"const":"initial"}},"additionalProperties":false},{"type":"object","required":["source","nodeId"],"properties":{"source":{"const":"node"},"nodeId":{"type":"string"}},"additionalProperties":false}]},"condition":{"oneOf":[{"type":"object","required":["kind","equalsArtifactId"],"properties":{"kind":{"const":"artifact.equals"},"equalsArtifactId":{"type":"string"}},"additionalProperties":false}]},"whenTrueNodeId":{"type":"string"},"whenFalseNodeId":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["id","kind","eventName","nextNodeId"],"properties":{"id":{"type":"string"},"kind":{"const":"wait"},"eventName":{"type":"string"},"nextNodeId":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["id","kind","input"],"properties":{"id":{"type":"string"},"kind":{"const":"output"},"input":{"oneOf":[{"type":"object","required":["source"],"properties":{"source":{"const":"initial"}},"additionalProperties":false},{"type":"object","required":["source","nodeId"],"properties":{"source":{"const":"node"},"nodeId":{"type":"string"}},"additionalProperties":false}]}},"additionalProperties":false}]}}},"additionalProperties":false}]},"WorkflowDefinitionSummary":{"type":"object","required":["_id","_creationTime","namespace","workflowKey","retentionDays","latestRevision","createdBy","createdAt","updatedBy","updatedAt"],"properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"namespace":{"type":"string"},"workflowKey":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"retentionDays":{"type":"integer","minimum":1,"maximum":365},"latestRevision":{"type":"integer","minimum":1},"latestRevisionId":{"type":"string"},"createdBy":{"type":"string"},"createdAt":{"type":"number","description":"Epoch ms"},"updatedBy":{"type":"string"},"updatedAt":{"type":"number","description":"Epoch ms"}}},"WorkflowDefinitionRevision":{"type":"object","required":["_id","_creationTime","definitionId","namespace","workflowKey","revision","runtimeVersion","definition","createdBy","createdAt"],"properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"definitionId":{"type":"string"},"namespace":{"type":"string"},"workflowKey":{"type":"string"},"revision":{"type":"integer","minimum":1},"runtimeVersion":{"const":1},"definition":{"$ref":"#/components/schemas/WorkflowDefinition"},"createdBy":{"type":"string"},"createdAt":{"type":"number","description":"Epoch ms"}}},"WorkflowRun":{"type":"object","required":["_id","_creationTime","namespace","workflowKey","definitionId","revisionId","revision","runtimeVersion","status","executionEpoch","createdBy","createdAt","updatedAt","retentionDays"],"properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"namespace":{"type":"string"},"workflowKey":{"type":"string"},"definitionId":{"type":"string"},"revisionId":{"type":"string"},"revision":{"type":"integer","minimum":1},"runtimeVersion":{"const":1},"status":{"type":"string","enum":["queued","running","waiting","completed","failed","canceled"]},"executionEpoch":{"type":"integer","minimum":1},"initialArtifactId":{"type":"string"},"outputArtifactId":{"type":"string"},"waitingNodeId":{"type":"string"},"waitingEventName":{"type":"string"},"errorMessage":{"type":"string"},"createdBy":{"type":"string"},"createdAt":{"type":"number","description":"Epoch ms"},"startedAt":{"type":"number","description":"Epoch ms"},"updatedAt":{"type":"number","description":"Epoch ms"},"terminalAt":{"type":"number","description":"Epoch ms"},"retentionDays":{"type":"integer","minimum":1,"maximum":365},"retentionExpiresAt":{"type":"number","description":"Epoch ms"}}},"WorkflowRunEvent":{"type":"object","required":["_id","_creationTime","namespace","runId","executionEpoch","sequence","type","createdBy","createdAt"],"properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"namespace":{"type":"string"},"runId":{"type":"string"},"executionEpoch":{"type":"integer","minimum":1},"sequence":{"type":"integer","minimum":1},"type":{"type":"string","enum":["run_queued","run_started","run_waiting","run_restarted","run_cancel_requested","run_canceled","run_completed","run_failed","parallel_started","parallel_completed","branch_selected","wait_started","wait_completed","node_started","node_completed","node_failed","node_completion_ignored","external_event_sent","output_completed"]},"nodeId":{"type":"string"},"artifactId":{"type":"string"},"eventName":{"type":"string"},"nextNodeId":{"type":"string"},"errorMessage":{"type":"string"},"createdBy":{"type":"string"},"createdAt":{"type":"number","description":"Epoch ms"}}},"WorkflowArtifact":{"type":"object","required":["_id","_creationTime","namespace","runId","revisionId","executionEpoch","kind","contentType","sizeBytes","createdBy","createdAt"],"properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"namespace":{"type":"string"},"runId":{"type":"string"},"revisionId":{"type":"string"},"executionEpoch":{"type":"integer","minimum":1},"kind":{"type":"string","enum":["initial","node_output","event_input","node_report","node_document","media_evidence"]},"nodeId":{"type":"string"},"parentArtifactId":{"type":"string"},"contentType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0,"maximum":262144},"createdBy":{"type":"string"},"createdAt":{"type":"number","description":"Epoch ms"}}},"WorkflowArtifactSummary":{"type":"object","required":["_id","kind","contentType","createdAt"],"properties":{"_id":{"type":"string"},"kind":{"type":"string","enum":["initial","node_output","event_input","node_report","node_document","media_evidence"]},"contentType":{"type":"string"},"nodeId":{"type":"string"},"createdAt":{"type":"number","description":"Epoch ms"}}},"WorkflowArtifactResult":{"type":"object","required":["artifact","text"],"properties":{"artifact":{"$ref":"#/components/schemas/WorkflowArtifact"},"text":{"type":"string","description":"Full core-bounded text payload (maximum 256 KiB UTF-8)."}}},"WorkflowTextArtifactInput":{"type":"object","required":["contentType","text"],"properties":{"contentType":{"type":"string","description":"MIME type for the immutable text payload."},"text":{"type":"string","description":"Immutable UTF-8 text payload. Size is bounded by the control plane."}}}}},"paths":{"/api/v1/auth/whoami":{"get":{"tags":["system"],"summary":"Resolve the active token","description":"Returns the user the active Bearer token resolves to (or `kind: 'service'` for the platform key). Available even without `api:read` so callers can discover what their token is and why they may be locked out.","operationId":"get_auth_whoami","responses":{"200":{"description":"Token resolved","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CallerInfo"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["full"]}]}},"/api/v1/auth/token":{"delete":{"tags":["system"],"summary":"Revoke the calling Personal Access Token","description":"Revokes the PAT used to authenticate this request. The service key cannot be revoked through this endpoint.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_auth_token","responses":{"200":{"description":"Token revoked","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["revoked"],"properties":{"revoked":{"const":true}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/me":{"get":{"tags":["me"],"summary":"Get my account","description":"Consolidated view of your own account: identity, display profile, marketing consent, notification preferences, and subscription summary. Ownership-only — always the account the bearer token resolves to.","operationId":"get_me","responses":{"200":{"description":"Account bundle","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MeBundle"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/me/profile":{"patch":{"tags":["me"],"summary":"Update my profile","description":"Update your own display name and/or avatar URL. Pass `avatarUrl: null` to remove the avatar. Display-name changes propagate to content attribution in the background.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_me_profile","responses":{"200":{"description":"Updated profile","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"profile":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"avatarUrl":{"type":["string","null"]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/me/notification-prefs":{"get":{"tags":["me"],"summary":"Get my notification preferences","description":"Get my notification preferences","operationId":"get_me_notification_prefs","responses":{"200":{"description":"Preference map","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MeNotificationPrefs"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["me"],"summary":"Set a notification preference","description":"Enable or disable one suppressible notification type for yourself. Unknown types are rejected.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_me_notification_prefs","responses":{"200":{"description":"Updated preference map","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MeNotificationPrefs"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","enabled"],"properties":{"type":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/me/ai-prefs":{"get":{"tags":["me"],"summary":"Get my AI feature preferences","description":"Get my AI feature preferences","operationId":"get_me_ai_prefs","responses":{"200":{"description":"Preference map","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MeAiPrefs"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["me"],"summary":"Set an AI feature preference","description":"Turn one catalogued generative-AI feature on or off for yourself. Features outside the catalog are mandatory and are rejected.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_me_ai_prefs","responses":{"200":{"description":"Updated preference map","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MeAiPrefs"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["feature","enabled"],"properties":{"feature":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/me/ai-features":{"get":{"tags":["me"],"summary":"Get my AI feature availability","description":"Composed availability per feature: plan entitlement AND your preference AND remaining budget, with the reason for any denial.","operationId":"get_me_ai_features","responses":{"200":{"description":"Availability per feature","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MeAiFeatures"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"app","in":"query","required":false,"schema":{"type":"string"},"description":"App namespace, for app-scoped entitlements."}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/me/email-consents":{"get":{"tags":["me"],"summary":"Get my per-app email consents","description":"Your marketing email consent for every app that sends updates, one row per app with its display name and subscriber status.","operationId":"get_me_email_consents","responses":{"200":{"description":"Consent rows","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MeEmailConsent"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/me/email-consent":{"patch":{"tags":["me"],"summary":"Set my marketing email consent","description":"Pass `namespace` to set consent for one app (each app sends its own updates); omitting it sets the deprecated account-wide flag.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_me_email_consent","responses":{"200":{"description":"Updated consent","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["emailSubscribed"],"properties":{"emailSubscribed":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emailSubscribed"],"properties":{"emailSubscribed":{"type":"boolean"},"namespace":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/me/permissions":{"get":{"tags":["me"],"summary":"Get my permissions in a namespace","description":"Your own RBAC bundle in the given app namespace. A PAT scope may narrow what the token can actually do below what the bundle grants; `GET /api/v1/auth/whoami` reports the scope.","operationId":"get_me_permissions","responses":{"200":{"description":"Permission bundle","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MePermissionBundle"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/me/sessions":{"get":{"tags":["me"],"summary":"List my sessions","description":"Your own auth sessions (creation and expiry), newest first. Read-only.","operationId":"get_me_sessions","responses":{"200":{"description":"Sessions","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MeSession"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/kvark/tasks":{"get":{"tags":["kvark"],"summary":"List Kvark tasks","description":"Caller-owned canonical task aggregates. Zero-knowledge bodies are omitted. Uses opaque, filter-bound keyset cursors; exact totals are intentionally omitted. If tasks change between pages, restart without a cursor.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"get_kvark_tasks","responses":{"200":{"description":"Paginated task list","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KvarkAutomationTask"}},"meta":{"type":"object","required":["hasMore","nextCursor"],"properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"boardId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["todo","in_progress","done"]}},{"name":"tags","in":"query","description":"Comma-separated; all tags must match.","schema":{"type":"string"}},{"name":"archived","in":"query","schema":{"type":"boolean"}},{"name":"dueBefore","in":"query","schema":{"type":"integer","minimum":0}},{"name":"dueAfter","in":"query","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["kvark"],"summary":"Create a Kvark task","description":"Creates canonical identity, Action, and Placement records. Plaintext bodies require server-readable visibility.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_tasks","responses":{"201":{"description":"Created task","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/KvarkAutomationTask"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"body":{"type":"string","description":"Plaintext body. Accepted only when the task is server-readable."},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"boardId":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","done"]},"dueAt":{"type":"integer","minimum":0,"description":"Epoch milliseconds."},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"channel":{"type":"string","enum":["notification"]}},"required":["remindAt"]},"idempotencyKey":{"type":"string"}},"required":["title"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/tasks/{id}":{"get":{"tags":["kvark"],"summary":"Get a Kvark task","description":"Get a Kvark task\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"get_kvark_tasks_by_id","responses":{"200":{"description":"Kvark task","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/KvarkAutomationTask"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["kvark"],"summary":"Update a Kvark task","description":"Update a Kvark task\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"patch_kvark_tasks_by_id","responses":{"200":{"description":"Kvark task","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/KvarkAutomationTask"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"body":{"type":"string","description":"Plaintext body. Accepted only when the task is server-readable."},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"boardId":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","done"]},"dueAt":{"type":"integer","minimum":0,"description":"Epoch milliseconds."},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"channel":{"type":"string","enum":["notification"]}},"required":["remindAt"]},"clearDueAt":{"type":"boolean"},"clearReminder":{"type":"boolean"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["kvark"],"summary":"Delete a Kvark task","description":"Delete a Kvark task\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"delete_kvark_tasks_by_id","responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/tasks/{id}/move":{"patch":{"tags":["kvark"],"summary":"Move a Kvark task","description":"Move a Kvark task\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"patch_kvark_tasks_by_id_move","responses":{"200":{"description":"Updated Kvark task","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/KvarkAutomationTask"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["todo","in_progress","done"]},"boardId":{"type":"string"},"afterTaskId":{"type":"string"},"beforeTaskId":{"type":"string"}},"required":["status"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/tasks/{id}/complete":{"post":{"tags":["kvark"],"summary":"Complete a Kvark task","description":"Complete a Kvark task\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_tasks_by_id_complete","responses":{"200":{"description":"Updated Kvark task","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/KvarkAutomationTask"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"boardId":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/tasks/{id}/archive":{"post":{"tags":["kvark"],"summary":"Archive a Kvark task","description":"Archive a Kvark task\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_tasks_by_id_archive","responses":{"200":{"description":"Updated Kvark task","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/KvarkAutomationTask"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/tasks/{id}/restore":{"post":{"tags":["kvark"],"summary":"Restore a Kvark task","description":"Restore a Kvark task\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_tasks_by_id_restore","responses":{"200":{"description":"Updated Kvark task","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/KvarkAutomationTask"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/task-tags":{"get":{"tags":["kvark"],"summary":"List Kvark task tags","description":"Scans one bounded page of active task projections. Follow nextCursor and union the pages; tags may repeat between pages. If tasks change between pages, restart without a cursor.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"get_kvark_task_tags","responses":{"200":{"description":"One bounded page of sorted task tags","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"string"}},"meta":{"type":"object","required":["hasMore","nextCursor"],"properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"scanLimit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/kvark/task-index/backfill":{"post":{"tags":["kvark"],"summary":"Backfill the Kvark task projection index","description":"Processes one bounded, idempotent caller-owned batch. Repeat until complete before using task list automation.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_task_index_backfill","responses":{"200":{"description":"Backfill batch status","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["complete","processed","totalProcessed"],"properties":{"complete":{"type":"boolean"},"processed":{"type":"integer","minimum":0},"totalProcessed":{"type":"integer","minimum":0}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batchSize":{"type":"integer","minimum":1,"maximum":50}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/boards":{"get":{"tags":["kvark"],"summary":"List Kvark boards","description":"List Kvark boards\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"get_kvark_boards","responses":{"200":{"description":"Kvark Board response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["kvark"],"summary":"Create a Kvark task board","description":"Create a Kvark task board\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_boards","responses":{"201":{"description":"Kvark Board response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["board","columns"],"properties":{"board":{"$ref":"#/components/schemas/KvarkBoard"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/KvarkBoardColumn"}}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/boards/{id}":{"patch":{"tags":["kvark"],"summary":"Update a Kvark board","description":"Update a Kvark board\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"patch_kvark_boards_by_id","responses":{"200":{"description":"Kvark Board response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/KvarkBoard"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"defaultVisibility":{"type":"string","enum":["zero-knowledge","server-readable"]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["kvark"],"summary":"Archive a Kvark board","description":"Archive a Kvark board\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"delete_kvark_boards_by_id","responses":{"200":{"description":"Kvark Board response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/boards/{id}/columns":{"get":{"tags":["kvark"],"summary":"List Kvark Board columns","description":"List Kvark Board columns\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"get_kvark_boards_by_id_columns","responses":{"200":{"description":"Board columns","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KvarkBoardColumn"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/kvark/boards/{id}/placements":{"get":{"tags":["kvark"],"summary":"List Kvark Board placements","description":"List Kvark Board placements\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"get_kvark_boards_by_id_placements","responses":{"200":{"description":"Board placements","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KvarkBoardPlacement"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/kvark/write/capture_entry":{"post":{"tags":["kvark"],"summary":"Capture a Kvark entry with duplicate-safe delivery","description":"Capture one entry with a Journal or Canvas part, a legacy Journal plus Canvas pair, or a Journal plus ordered inline Canvases, using duplicate-safe delivery. Private and sealed modes accept ciphertext only; sealed capture remains Journal-only. Server-readable mode explicitly stores plaintext for authorized automation. Reuse the capture ID and identical content when retrying. Owner must match the authenticated caller.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_write_capture_entry","responses":{"200":{"description":"Capture a Kvark entry with duplicate-safe delivery","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"captureId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ownerSubject":{"type":"string","minLength":1,"maxLength":256},"content":{"anyOf":[{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"private"},"kind":{"type":"string","const":"journal"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"canvas":{"type":"object","properties":{"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256}},"required":["encryptedContent","iv"],"additionalProperties":false},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false}},"required":["mode","kind","encryptedContent","iv","dekEnvelope"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"private"},"kind":{"type":"string","const":"journal"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"inlineCanvases":{"minItems":1,"maxItems":64,"type":"array","items":{"type":"object","properties":{"blockId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256}},"required":["blockId","encryptedContent","iv"],"additionalProperties":false}},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false}},"required":["mode","kind","encryptedContent","iv","inlineCanvases","dekEnvelope"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"private"},"kind":{"type":"string","const":"canvas"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false}},"required":["mode","kind","encryptedContent","iv","dekEnvelope"],"additionalProperties":false}]},{"type":"object","properties":{"mode":{"type":"string","const":"sealed"},"kind":{"type":"string","const":"journal"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false}},"required":["mode","kind","encryptedContent","iv","sealedDek"],"additionalProperties":false},{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"server-readable"},"kind":{"type":"string","const":"journal"},"plainBody":{"type":"string","minLength":1,"maxLength":750000},"canvas":{"type":"object","properties":{"plainBody":{"type":"string","minLength":1,"maxLength":750000}},"required":["plainBody"],"additionalProperties":false}},"required":["mode","kind","plainBody"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"server-readable"},"kind":{"type":"string","const":"journal"},"plainBody":{"type":"string","minLength":1,"maxLength":750000},"inlineCanvases":{"minItems":1,"maxItems":64,"type":"array","items":{"type":"object","properties":{"blockId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"plainBody":{"type":"string","minLength":1,"maxLength":750000}},"required":["blockId","plainBody"],"additionalProperties":false}}},"required":["mode","kind","plainBody","inlineCanvases"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"server-readable"},"kind":{"type":"string","const":"canvas"},"plainBody":{"type":"string","minLength":1,"maxLength":750000}},"required":["mode","kind","plainBody"],"additionalProperties":false}]}]}},"required":["captureId","ownerSubject","content"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/write/create_sealed_capture":{"post":{"tags":["kvark"],"summary":"Create a Kvark sealed deposit","description":"Create one untitled sealed deposit from caller-sealed ciphertext and sealedDek. Seal locally with `furnace kvark sealed-deposit`; plaintext never crosses the wire. The deposit reveals only its existence, createdAt, and sealed flag, and no API surface can read its body until the vault owner unlocks.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_write_create_sealed_capture","responses":{"200":{"description":"Create a Kvark sealed deposit","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"identity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["note","task","drawing"]},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"everServerReadable":{"type":"boolean"},"vaultId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"boostedUntil":{"type":"number"},"combinePending":{"type":"object","properties":{"sourceIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"startedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sourceIds","startedAt","expiresAt"],"additionalProperties":false},"boardId":{"type":"string","minLength":1,"maxLength":128},"trashedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"purgeAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","tags","archived","createdAt","updatedAt"],"additionalProperties":false},"block":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"journal"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"canvas"},"placement":{"type":"string","const":"inline"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"list"},"childNukleonId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"renderStyle":{"default":"checklist","type":"string","enum":["checklist","board"]}},"required":["id","nukleonId","order","createdAt","updatedAt","kind","childNukleonId","renderStyle"],"additionalProperties":false}]},"content":{"type":"object","properties":{"encryptedContent":{"type":"string"},"iv":{"type":"string"},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false},"plainBody":{"type":"string"},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["encryptedContent","iv","updatedAt"],"additionalProperties":false}},"required":["identity","block","content"],"additionalProperties":false}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false}},"required":["encryptedContent","iv","sealedDek"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/kvark/read/get_capture_public_bundle":{"post":{"tags":["kvark"],"summary":"Get the Kvark sealed-deposit public bundle","description":"Return the caller's sealed-deposit public bundle, or null until the vault owner unlocks Kvark once. Bodies cross the wire only as ciphertext; seal locally with `furnace kvark sealed-deposit`. A deposit reveals only its existence, createdAt, and sealed flag, and no API surface can read its body until the vault owner unlocks.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_kvark_read_get_capture_public_bundle","responses":{"200":{"description":"Get the Kvark sealed-deposit public bundle","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"x25519":{"type":"string","minLength":1,"maxLength":256},"mlkem":{"type":"string","minLength":1,"maxLength":4096}},"required":["x25519","mlkem"],"additionalProperties":false},{"type":"null"}]}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content":{"get":{"tags":["content"],"summary":"List content in a namespace","description":"Reader-filtered list of content. Editors see drafts; readers see only published items they can access.","operationId":"get_content","responses":{"200":{"description":"Page of content summaries","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentSummary"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/tree":{"get":{"tags":["content"],"summary":"Get the namespace nav tree","description":"Returns the full reader-filtered nav tree (nodes with paths). Use this to build site navigation.","operationId":"get_content_by_namespace_tree","responses":{"200":{"description":"Namespace tree","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/NamespaceTree"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/by-path":{"get":{"tags":["content"],"summary":"Resolve content by URL path","description":"Resolve content by URL path","operationId":"get_content_by_namespace_by_path","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"path","in":"query","required":true,"description":"URL path within the namespace","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}":{"get":{"tags":["content"],"summary":"Get content by id","description":"Get content by id","operationId":"get_content_by_namespace_by_id","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["content"],"summary":"Update a content page","description":"Patch fields on a page. Editing `body` rotates the previous draft into version history. `customData` replaces the whole object — see the field description before sending it.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"body":{"type":"string","description":"Markdown — replaces current draft, prior draft rotates into history"},"tags":{"type":"array","items":{"type":"string"}},"featuredImage":{"type":["string","null"],"description":"Asset id or null to clear"},"customData":{"type":"object","additionalProperties":{"type":"string"},"description":"REPLACES the whole object — every key you want to keep must be included, or it is deleted. For layout changes use PATCH `/template` or `/custom-layout`, which merge a single key. `layoutDocument` is validated on write and rejected if invalid."}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["content"],"summary":"Delete a content page","description":"Pass `?deleteChildren=true` to cascade-delete descendants — otherwise the call fails if any exist.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_content_by_namespace_by_id","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"deletedIds":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"deleteChildren","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/versions":{"get":{"tags":["content"],"summary":"List version history (or read a specific version)","description":"Without `index`, returns the full version history. With `index`, returns one version body. By convention `-1` = current draft, `-2` = current published, `0..N` = stored versions newest-first.","operationId":"get_content_by_namespace_by_id_versions","responses":{"200":{"description":"History or single version","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentVersion"}}}},{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentVersion"}}}]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"index","in":"query","description":"Optional: read a single version by index","schema":{"type":"integer"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}":{"post":{"tags":["content"],"summary":"Create a content page","description":"`parentId` of `null` (or omitted) creates a root-level page; `urlSegment` is auto-generated from title if omitted. `customData` seeds the page-metadata bag at creation, so a new page never needs a follow-up PATCH to set its `template`.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace","responses":{"201":{"description":"Content created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"parentId":{"type":["string","null"]},"urlSegment":{"type":"string"},"body":{"type":"string","description":"Markdown"},"isCategory":{"type":"boolean"},"customData":{"type":"object","additionalProperties":{"type":"string"},"description":"Free-form string metadata. `template` names a page layout; `layoutDocument` is validated on write and rejected if invalid."}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/publish":{"post":{"tags":["content"],"summary":"Publish the current draft","description":"Publish the current draft\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_id_publish","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customPublishedAt":{"type":"integer","description":"Optional epoch ms backdate"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/unpublish":{"post":{"tags":["content"],"summary":"Revert a page to draft-only state","description":"Revert a page to draft-only state\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_id_unpublish","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/schedule":{"post":{"tags":["content"],"summary":"Schedule a page for future publication","description":"Schedule a page for future publication\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_id_schedule","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scheduledAt"],"properties":{"scheduledAt":{"type":"integer","description":"Epoch ms in the future"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/duplicate":{"post":{"tags":["content"],"summary":"Duplicate a page as a new draft sibling","description":"Duplicate a page as a new draft sibling\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_id_duplicate","responses":{"201":{"description":"Content created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/checkpoint":{"post":{"tags":["content"],"summary":"Save a version checkpoint","description":"Snapshot the current draft as a new version (newest at index 0). Use before risky edits.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_id_checkpoint","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/restore":{"post":{"tags":["content"],"summary":"Restore an earlier version into the draft","description":"Restore an earlier version into the draft\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_id_restore","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["versionIndex"],"properties":{"versionIndex":{"type":"integer","minimum":0}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/slots/{slotId}":{"patch":{"tags":["content"],"summary":"Replace one content slot","description":"Replaces only the named slot’s markdown in the current draft, leaving every other byte of the page untouched. Identical input is an idempotent no-op. Requires update:content in the namespace. Does not publish; call content_publish after updating. The slot must already exist exactly once and have a closing fence. Send exactly one of body or bodyAssetId, without the outer slot fence. For bodies too large to pass inline, upload by URL with media_create_upload mode \"url\", finalize with media_finalize_upload, then pass the assetId as bodyAssetId. Asset bodies require media:admin in media-library, UTF-8 text/markdown or text/plain, and at most 256 KiB. The resulting draft must fit within 900,000 UTF-8 bytes. Use ::::slot{#reports} with a four-colon closing fence when nesting :::sdl inside it; longer nested fences require a longer outer fence.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id_slots_by_slotId","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"slotId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"bodyAssetId":{"type":"string"}},"oneOf":[{"required":["body"]},{"required":["bodyAssetId"]}]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/template":{"patch":{"tags":["content"],"summary":"Set the page layout","description":"Points the page at a layout by id — a code layout the app ships, or a named layout from `/api/v1/content-layouts/{namespace}`. `null` returns the page to single-column. Merges the one key, so unlike PATCH `customData` it cannot drop sibling metadata. Unknown ids are accepted and degrade at render time.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id_template","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template"],"properties":{"template":{"type":["string","null"]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/custom-layout":{"patch":{"tags":["content"],"summary":"Set the page's one-off layout document","description":"Stores a layout document belonging to this page alone, as a JSON string, and sets `template` to `custom`. `null` clears both. Validated against the SDL layout profile on write and rejected if invalid. Merges the one key, so it cannot drop sibling metadata.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id_custom_layout","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":["string","null"],"description":"JSON-stringified SDL layout document, or null to clear"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/promote-layout":{"post":{"tags":["content"],"summary":"Promote the page's one-off layout to a named layout","description":"Creates a named layout from the page's one-off document and repoints the page at it, atomically. Requires both `update:content` and `manage:content_layouts`. Fails if the page has no one-off document or the slug is taken.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_id_promote_layout","responses":{"200":{"description":"Page repointed at the new named layout","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","slug"],"properties":{"id":{"type":"string"},"slug":{"type":"string"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","label"],"properties":{"slug":{"type":"string"},"label":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/move":{"patch":{"tags":["content"],"summary":"Re-parent a page","description":"Re-parent a page\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id_move","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["newParentId"],"properties":{"newParentId":{"type":["string","null"]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/url-segment":{"patch":{"tags":["content"],"summary":"Rename the URL segment","description":"Rename the URL segment\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id_url_segment","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["newSegment"],"properties":{"newSegment":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/reorder":{"patch":{"tags":["content"],"summary":"Reorder a page among its siblings","description":"Pin after `afterId` or before `beforeId`. Pass `null` for first/last.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id_reorder","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"afterId":{"type":["string","null"]},"beforeId":{"type":["string","null"]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/flags":{"patch":{"tags":["content"],"summary":"Set visibility flags on a page","description":"`hidden` removes the page from reader navigation while keeping it URL-addressable (per-node — descendants are not affected). `startsAt` opens the schedule window; `endsAt` closes it. Pass `null` for either to clear; omit a field to leave it unchanged.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id_flags","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hidden":{"type":"boolean"},"startsAt":{"type":["integer","null"]},"endsAt":{"type":["integer","null"]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/access":{"patch":{"tags":["content"],"summary":"Set page access level","description":"Set page access level\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_by_namespace_by_id_access","responses":{"200":{"description":"Content document","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentDocument"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["access"],"properties":{"access":{"$ref":"#/components/schemas/ContentAccess"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/stats":{"get":{"tags":["content"],"summary":"Reaction + view stats for a content item","description":"Requires `read:analytics` in the namespace. `path` is the resolved nav-tree path.","operationId":"get_content_by_namespace_by_id_stats","responses":{"200":{"description":"Stats (null if unauthorized)"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/reactions":{"get":{"tags":["content"],"summary":"Emoji reaction counts for a content item","description":"Emoji reaction counts for a content item","operationId":"get_content_by_namespace_by_id_reactions","responses":{"200":{"description":"Reaction map (empty if no access)"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{id}/comments":{"get":{"tags":["content"],"summary":"List comments on a content item","description":"Content-access gated. Flagged/rejected hidden unless caller holds moderate/edit:comments.","operationId":"get_content_by_namespace_by_id_comments","responses":{"200":{"description":"Comments, replies, reactions, pagination"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/comments-moderation":{"get":{"tags":["content"],"summary":"List comments for moderation","description":"Requires moderate:comments or edit:comments. Optional `status` filter.","operationId":"get_content_by_namespace_comments_moderation","responses":{"200":{"description":"Moderation queue, newest first"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","flagged","rejected"]}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{commentId}/moderate-comment":{"post":{"tags":["content"],"summary":"Set a comment moderation status","description":"Requires moderate:comments or edit:comments. `{commentId}` is the comment id.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_commentId_moderate_comment","responses":{"200":{"description":"Moderation status applied"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["approved","flagged","rejected"]},"reason":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/{commentId}/moderator-edit":{"post":{"tags":["content"],"summary":"Moderator-edit a comment body","description":"Requires moderate:comments or edit:comments. Locks and approves the comment.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_by_namespace_by_commentId_moderator_edit","responses":{"200":{"description":"Edited"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/nav-tree-paths":{"get":{"tags":["content"],"summary":"Nested nav tree with resolved paths","description":"Nested nav tree with resolved paths","operationId":"get_content_by_namespace_nav_tree_paths","responses":{"200":{"description":"Nested tree with path/depth/children"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/audit-schedule":{"get":{"tags":["content"],"summary":"Audit nav-tree schedule migration state (cross-namespace)","description":"Service token or super-admin (read:analytics in access-control) only. `{namespace}` is ignored.","operationId":"get_content_by_namespace_audit_schedule","responses":{"200":{"description":"Per-namespace legacy-shape counts"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/kv-list":{"get":{"tags":["content"],"summary":"List raw content KV entries","description":"Access-filtered KV listing. Editors see drafts; readers see published, permitted entries. Platform-owned families under the `__` sigil (`__layout:*`, `__content:card:*`, `__access:*`) are never listed — read those through their own endpoints.","operationId":"get_content_by_namespace_kv_list","responses":{"200":{"description":"Page of KV entries"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}},{"name":"prefix","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content/{namespace}/tags":{"get":{"tags":["content"],"summary":"List all unique tags in a namespace","description":"List all unique tags in a namespace","operationId":"get_content_by_namespace_tags","responses":{"200":{"description":"Sorted unique tags"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `docs`).","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/content-layouts/{namespace}":{"get":{"tags":["content_layouts"],"summary":"List named content layouts","description":"Slug-ordered layouts with their full SDL documents. Needs `manage:content_layouts` or `update:content`.","operationId":"get_content_layouts_by_namespace","responses":{"200":{"description":"Named content layouts","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentLayout"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `falcata-website`).","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["content_layouts"],"summary":"Create a named content layout","description":"Fails if the slug is already in use in this namespace.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_content_layouts_by_namespace","responses":{"201":{"description":"Layout created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentLayout"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `falcata-website`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentLayoutInput"}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content-layouts/{namespace}/{slug}":{"get":{"tags":["content_layouts"],"summary":"Read one named content layout","description":"Read one named content layout","operationId":"get_content_layouts_by_namespace_by_slug","responses":{"200":{"description":"Named content layout","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentLayout"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `falcata-website`).","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["content_layouts"],"summary":"Update a named content layout","description":"Omitted fields keep their stored value; `description: null` clears it. The slug is immutable.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_content_layouts_by_namespace_by_slug","responses":{"200":{"description":"Named content layout","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContentLayout"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `falcata-website`).","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"description":{"type":["string","null"]},"document":{"type":"object","description":"SDL layout document in the layout profile: a Stack/Row/Grid/Split/… tree whose leaves include `ContentSlot` nodes, one per editable region. Statics only — no data, vars, bindings, or conditionals. Validated on write; an invalid document is rejected, never stored."}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["content_layouts"],"summary":"Delete a named content layout","description":"Pages still naming it keep their content and fall back to the default single-column layout.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_content_layouts_by_namespace_by_slug","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"slug":{"type":"string"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `falcata-website`).","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/content-layouts/{namespace}/{slug}/usage":{"get":{"tags":["content_layouts"],"summary":"Count pages using a named content layout","description":"The scan is bounded at 1000 pages; `count: 1001` means the namespace is larger than the bound and the exact number is unknown.","operationId":"get_content_layouts_by_namespace_by_slug_usage","responses":{"200":{"description":"Usage count","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["slug","count"],"properties":{"slug":{"type":"string"},"count":{"type":"integer"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"description":"Content namespace (e.g. `marozzo`, `falcata-website`).","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/communications/config/enabled-namespaces":{"get":{"tags":["communications"],"summary":"Get enabled namespaces","description":"Runs the comms.enabledNamespaces capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_config_enabled_namespaces","responses":{"200":{"description":"Enabled namespace slugs"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["communications"],"summary":"Set enabled namespaces","description":"Runs the comms.setEnabledNamespaces capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_communications_config_enabled_namespaces","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespaces"],"properties":{"namespaces":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/{namespace}/subscribers":{"get":{"tags":["communications"],"summary":"List email subscribers","description":"Runs the comms.listSubscribers capability, through the same dispatch as POST /api/v2/platform/page/comms.listSubscribers; refusals answer with the platform statuses.","operationId":"get_communications_by_namespace_subscribers","responses":{"200":{"description":"Paginated subscribers","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string","description":"Send as `cursor` to read the next page."},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["subscribed","unsubscribed","bounced","complained"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["communications"],"summary":"Add a subscriber","description":"Runs the comms.addSubscriber capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_communications_by_namespace_subscribers","responses":{"200":{"description":"Subscriber id"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","source"],"properties":{"email":{"type":"string"},"source":{"type":"string","enum":["manual","signup","migration"]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["communications"],"summary":"Remove a subscriber","description":"Runs the comms.removeSubscriber capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_communications_by_namespace_subscribers","responses":{"200":{"description":"Removed"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/{namespace}/subscribers/tags":{"get":{"tags":["communications"],"summary":"List subscriber tags","description":"Runs the comms.subscriberTags capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_by_namespace_subscribers_tags","responses":{"200":{"description":"Unique tags"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/communications/{namespace}/subscribers/counts":{"get":{"tags":["communications"],"summary":"Subscriber status counts","description":"Runs the comms.subscriberCounts capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_by_namespace_subscribers_counts","responses":{"200":{"description":"Counts by status"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/communications/subscribers/{subscriberId}/tags":{"patch":{"tags":["communications"],"summary":"Update subscriber tags","description":"Runs the comms.updateSubscriberTags capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_communications_subscribers_by_subscriberId_tags","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"subscriberId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tags"],"properties":{"tags":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/{namespace}/campaigns":{"get":{"tags":["communications"],"summary":"List email campaigns","description":"Runs the comms.listCampaigns capability, through the same dispatch as POST /api/v2/platform/page/comms.listCampaigns; refusals answer with the platform statuses.","operationId":"get_communications_by_namespace_campaigns","responses":{"200":{"description":"Paginated campaigns","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string","description":"Send as `cursor` to read the next page."},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","sending","sent","failed","partially_sent"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["communications"],"summary":"Create a draft campaign","description":"Runs the comms.createCampaign capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_communications_by_namespace_campaigns","responses":{"200":{"description":"Campaign id"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject"],"properties":{"subject":{"type":"string"},"previewText":{"type":"string"},"mdBody":{"type":"string"},"audienceTags":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/campaigns/{campaignId}":{"get":{"tags":["communications"],"summary":"Get a campaign","description":"Runs the comms.campaign capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_campaigns_by_campaignId","responses":{"200":{"description":"Campaign"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["communications"],"summary":"Update a draft campaign","description":"Runs the comms.updateCampaign capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_communications_campaigns_by_campaignId","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"previewText":{"type":"string"},"mdBody":{"type":"string"},"audienceTags":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["communications"],"summary":"Delete a campaign","description":"Runs the comms.deleteCampaign capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_communications_campaigns_by_campaignId","responses":{"200":{"description":"Deleted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/campaigns/{campaignId}/stats":{"get":{"tags":["communications"],"summary":"Campaign delivery stats","description":"Runs the comms.campaignStats capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_campaigns_by_campaignId_stats","responses":{"200":{"description":"Delivery stats"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/communications/{namespace}/audience-size":{"get":{"tags":["communications"],"summary":"Estimate audience size","description":"Runs the comms.audienceSize capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_by_namespace_audience_size","responses":{"200":{"description":"Recipient count"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"tags","in":"query","schema":{"type":"string","description":"Comma-separated audience tags"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/communications/campaigns/{campaignId}/reset-draft":{"post":{"tags":["communications"],"summary":"Reset campaign to draft","description":"Runs the comms.resetCampaignToDraft capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_communications_campaigns_by_campaignId_reset_draft","responses":{"200":{"description":"Reset"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/campaigns/{campaignId}/duplicate":{"post":{"tags":["communications"],"summary":"Duplicate a campaign","description":"Runs the comms.duplicateCampaign capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_communications_campaigns_by_campaignId_duplicate","responses":{"200":{"description":"New campaign id"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/campaigns/{campaignId}/send":{"post":{"tags":["communications"],"summary":"Send a campaign","description":"Send a campaign\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_communications_campaigns_by_campaignId_send","responses":{"200":{"description":"Send started"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/campaigns/{campaignId}/test-email":{"post":{"tags":["communications"],"summary":"Send a test email","description":"Send a test email\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_communications_campaigns_by_campaignId_test_email","responses":{"200":{"description":"Test sent"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipientEmail"],"properties":{"recipientEmail":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/{namespace}/templates":{"get":{"tags":["communications"],"summary":"List email templates","description":"Runs the comms.templates capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_by_namespace_templates","responses":{"200":{"description":"Templates"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["communications"],"summary":"Create an email template","description":"Runs the comms.createTemplate capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_communications_by_namespace_templates","responses":{"200":{"description":"Template id"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","mdBody"],"properties":{"name":{"type":"string"},"mdBody":{"type":"string"},"audienceTags":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/templates/{templateId}":{"delete":{"tags":["communications"],"summary":"Delete an email template","description":"Runs the comms.deleteTemplate capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_communications_templates_by_templateId","responses":{"200":{"description":"Deleted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/{namespace}/config/legal":{"get":{"tags":["communications"],"summary":"Get legal footer config","description":"Runs the comms.legalConfig capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_by_namespace_config_legal","responses":{"200":{"description":"Legal config"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["communications"],"summary":"Set legal footer config","description":"Runs the comms.setLegalConfig capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_communications_by_namespace_config_legal","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"companyName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateRegion":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"unsubscribeNote":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/communications/{namespace}/config/email":{"get":{"tags":["communications"],"summary":"Get email sender config","description":"Runs the comms.emailConfig capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_communications_by_namespace_config_email","responses":{"200":{"description":"Email config"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["communications"],"summary":"Set email sender config","description":"Set email sender config\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_communications_by_namespace_config_email","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromAddress","fromName"],"properties":{"fromAddress":{"type":"string"},"fromName":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/ledger/read/{operation}":{"post":{"tags":["ledger"],"summary":"Run a Ledger read operation","description":"Supported operations: get_config, list_journal_entries, get_journal_entry, list_entry_audit, list_audit, search_journal_entries, list_counterparties, list_clearing_entries, clearing_count, list_scans, get_scan, list_customers, get_customer, list_work_types, list_customer_rates, list_all_customer_rates, list_time_entries, get_time_entry, list_unbilled_for_customer, summarize_uninvoiced, list_invoices, get_invoice, compute_vat_report, compute_oss_report, export_oss_csv, compute_tilinpaatos, get_tilinpaatos_config, list_saved_reports, get_saved_report, dashboard_summary. list_audit runs the ledger.audit capability, through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_ledger_read_by_operation","responses":{"200":{"description":"Ledger operation result"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"operation","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/ledger/write/{operation}":{"post":{"tags":["ledger"],"summary":"Run a Ledger write operation","description":"Supported operations: save_opening_balances, create_journal_entry, update_journal_entry, set_scan_extraction, attach_scans_to_entry, create_customer, update_customer, archive_customer, delete_customer, create_work_type, update_work_type, archive_work_type, delete_work_type, set_customer_rate, delete_customer_rate, create_time_entry, update_time_entry, delete_time_entry, create_invoice_draft, update_invoice_draft, delete_invoice_draft, issue_invoice, mark_invoice_paid, credit_invoice, save_tilinpaatos_config, save_report\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_ledger_write_by_operation","responses":{"200":{"description":"Ledger operation result"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"operation","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/ledger/action/read/{operation}":{"post":{"tags":["ledger"],"summary":"Run a Ledger read action","description":"Supported operations: get_attachment_url, find_dangling_attachments, extract_from_attachments, list_stripe_activity, list_revolut_activity, get_saved_report_pdf_url\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_ledger_action_read_by_operation","responses":{"200":{"description":"Ledger action result"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"operation","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/ledger/action/write/{operation}":{"post":{"tags":["ledger"],"summary":"Run a Ledger write action","description":"Supported operations: delete_journal_entry, delete_scan, delete_report, generate_invoice_pdf, verify_eu_vat_rates, upload_attachment, upload_scan, delete_attachment, sync_stripe_balance_transactions, sync_revolut_transactions, prepare_revolut_connect, generate_report_pdf\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.\n\nDeprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved.","deprecated":true,"operationId":"post_ledger_action_write_by_operation","responses":{"200":{"description":"Ledger action result"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"operation","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/overview":{"get":{"tags":["analytics"],"summary":"Period summary with prior-window trend","description":"Pass `days` for a trailing window, or `since`/`until` for a pinned range. Requires `read:analytics` in the namespace.","operationId":"get_analytics_by_namespace_overview","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AnalyticsOverview"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"},{"name":"since","in":"query","description":"Window start — ms timestamp or ISO 8601 string","schema":{"type":["integer","string"]}},{"name":"until","in":"query","description":"Window end — defaults to now","schema":{"type":["integer","string"]}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/timeseries":{"get":{"tags":["analytics"],"summary":"Bucketed event counts","description":"Group events by `period` (`hour` or `day`), optionally filtered by `eventName`.","operationId":"get_analytics_by_namespace_timeseries","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeSeriesPoint"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"},{"name":"since","in":"query","description":"Window start — ms timestamp or ISO 8601 string","schema":{"type":["integer","string"]}},{"name":"until","in":"query","description":"Window end — defaults to now","schema":{"type":["integer","string"]}},{"name":"period","in":"query","required":true,"schema":{"type":"string","enum":["hour","day"]}},{"name":"eventName","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/top-paths":{"get":{"tags":["analytics"],"summary":"Top paths by event volume","description":"Optional `eventName` narrows to a single event type — pass `page_view` for true page reads.","operationId":"get_analytics_by_namespace_top_paths","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopPath"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"},{"name":"since","in":"query","description":"Window start — ms timestamp or ISO 8601 string","schema":{"type":["integer","string"]}},{"name":"until","in":"query","description":"Window end — defaults to now","schema":{"type":["integer","string"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Default 25, capped at 100"},{"name":"eventName","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/top-referrers":{"get":{"tags":["analytics"],"summary":"Top cross-origin referrers by session volume","description":"Direct visits and same-origin navigation are excluded. Captured on `page_view` events only.","operationId":"get_analytics_by_namespace_top_referrers","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopReferrer"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"},{"name":"since","in":"query","description":"Window start — ms timestamp or ISO 8601 string","schema":{"type":["integer","string"]}},{"name":"until","in":"query","description":"Window end — defaults to now","schema":{"type":["integer","string"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Default 25, capped at 100"}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/event-names":{"get":{"tags":["analytics"],"summary":"Distinct event names in the window","description":"Distinct event names in the window","operationId":"get_analytics_by_namespace_event_names","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventNameStat"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"},{"name":"since","in":"query","description":"Window start — ms timestamp or ISO 8601 string","schema":{"type":["integer","string"]}},{"name":"until","in":"query","description":"Window end — defaults to now","schema":{"type":["integer","string"]}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/list-events":{"get":{"tags":["analytics"],"summary":"List raw analytics events","description":"Newest-first raw event rows, optionally filtered by `eventName` and time window. Max `limit` 1000.","operationId":"get_analytics_by_namespace_list_events","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsEvent"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"},{"name":"since","in":"query","description":"Window start — ms timestamp or ISO 8601 string","schema":{"type":["integer","string"]}},{"name":"until","in":"query","description":"Window end — defaults to now","schema":{"type":["integer","string"]}},{"name":"eventName","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/top-searches":{"get":{"tags":["analytics"],"summary":"Top palette search queries","description":"Ranks `palette_search` queries with sessions, average result count, and zero-result rate.","operationId":"get_analytics_by_namespace_top_searches","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopSearch"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"},{"name":"since","in":"query","description":"Window start — ms timestamp or ISO 8601 string","schema":{"type":["integer","string"]}},{"name":"until","in":"query","description":"Window end — defaults to now","schema":{"type":["integer","string"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Default 25, capped at 100"}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/feedback-stats":{"get":{"tags":["analytics"],"summary":"Feedback submission stats","description":"Aggregates `feedback_submitted` events with prior-window trend and a daily time series.","operationId":"get_analytics_by_namespace_feedback_stats","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/FeedbackStats"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"},{"name":"since","in":"query","description":"Window start — ms timestamp or ISO 8601 string","schema":{"type":["integer","string"]}},{"name":"until","in":"query","description":"Window end — defaults to now","schema":{"type":["integer","string"]}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/{namespace}/user-activity":{"get":{"tags":["analytics"],"summary":"Caller's own activity stats","description":"Per-user activity for the calling PAT's user. Service tokens receive null (no user identity). `data` is null when unavailable.","operationId":"get_analytics_by_namespace_user_activity","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/UserActivityStats"},{"type":"null"}]}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1},"description":"Trailing N-day window from now"}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/analytics/namespaces":{"get":{"tags":["analytics"],"summary":"List namespaces the caller can read analytics for","description":"Sorted app namespaces where the caller holds `read:analytics`. Service tokens see every namespace.","operationId":"get_analytics_namespaces","responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/studio/query":{"post":{"tags":["studio"],"summary":"Run a governed analytics query spec","description":"Submit a Studio query spec and get the computed rows plus an optional multi-series pivot. The flexible counterpart to the fixed analytics endpoints. Requires `read:analytics` in the spec namespace.","operationId":"post_studio_query","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioQueryResult"}}}}},"description":"Computed query result"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioQuerySpec"}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/studio/dashboards":{"get":{"tags":["studio"],"summary":"List the caller's saved dashboards","description":"Most-recently-updated first. Owner-scoped — requires a user-bound PAT (service tokens have no dashboards).","operationId":"get_studio_dashboards","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StudioDashboard"}}}}}},"description":"The caller’s dashboards"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["studio"],"summary":"Create or update a saved dashboard","description":"Omit `id` to create; include it to update. Owner-scoped (PAT). At most 50 dashboards per user, 24 charts each.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_studio_dashboards","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioDashboard"}}}}},"description":"Updated dashboard"},"201":{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioDashboard"}}}}},"description":"Created dashboard"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Omit to create a new dashboard; include to update an existing one."},"name":{"type":"string"},"description":{"type":"string"},"charts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["stat","area","line","bar","column","table","multiLine","groupedBar","stackedBar","stackedArea"]},"title":{"type":"string"},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["analytics"],"description":"Always \"analytics\"."},"namespace":{"type":"string","description":"Which app/tenant to query. Must be one of the namespaces listed as available to you in the system prompt."},"eventName":{"type":"string","description":"Optional: restrict to a single event name (e.g. \"page_view\", \"ai_chat\"). Omit to include all events."},"filters":{"type":"array","description":"Optional: up to 10 equality filters, all of which must match (AND).","items":{"type":"object","properties":{"field":{"type":"string","description":"One of: path, referrer, name, or properties.<key> (e.g. \"properties.tier\")."},"op":{"type":"string","enum":["eq","neq","in"],"description":"\"eq\"/\"neq\" compare to a single string value; \"in\" matches any value in an array."},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"A string for \"eq\"/\"neq\"; an array of strings for \"in\"."}},"required":["field","op","value"],"additionalProperties":false}},"groupBy":{"type":"object","description":"Optional: break the measure down by one dimension. Omit for a single total (big number).","properties":{"dimension":{"type":"string","description":"One of: path, referrer, name, time, or properties.<key>. Use \"time\" for a trend across the window."},"timeBucket":{"type":"string","enum":["hour","day","week"],"description":"Only with dimension \"time\": the bucket width. Defaults to \"day\"."}},"required":["dimension"],"additionalProperties":false},"series":{"type":"object","description":"Optional: split the measure into multiple series by a SECOND categorical dimension — e.g. groupBy \"time\" + series by \"name\" draws one line per event type; groupBy a category + series draws grouped bars. Requires groupBy and must differ from it. Use only when comparing a handful of categories across the primary axis.","properties":{"dimension":{"type":"string","description":"One of: path, referrer, name, or properties.<key>. NOT \"time\" — time is the primary axis."},"limit":{"type":"number","description":"Optional: keep only the top-N series by measure (default 6, max 8)."}},"required":["dimension"],"additionalProperties":false},"measure":{"type":"object","description":"What to compute over the matched events.","properties":{"fn":{"type":"string","enum":["count","sessions","users","anonymous","sum","avg","p50","p95"],"description":"count = number of events; sessions/users/anonymous = distinct counts; sum/avg/p50/p95 = numeric statistics over a property field."},"field":{"type":"string","description":"Required for sum/avg/p50/p95: a properties.<key> holding a number (e.g. \"properties.estimatedCostUsd\"). Omit for count/sessions/users/anonymous."}},"required":["fn"],"additionalProperties":false},"range":{"description":"The time window. Either a trailing number of days, or absolute since/until in epoch milliseconds. Capped server-side at 90 days.","anyOf":[{"type":"object","properties":{"days":{"type":"number","description":"Trailing window length in days (1–90)."}},"required":["days"],"additionalProperties":false},{"type":"object","properties":{"since":{"type":"number","description":"Window start, epoch milliseconds."},"until":{"type":"number","description":"Window end, epoch milliseconds. Defaults to now."}},"required":["since"],"additionalProperties":false}]},"limit":{"type":"number","description":"Optional: max rows for a categorical breakdown (1–100, default 50). Ignored for a time series, which is always returned whole."},"kind":{"type":"string","enum":["aggregate","experiment"],"description":"The query type. Omit or \"aggregate\" for the normal measure/groupBy analytics above. \"experiment\" instead measures an A/B experiment: it correlates flag exposures with a later outcome event to report per-variant conversion — set flagKey + outcomeEvent (and optionally exposureEvent) plus a range; measure/groupBy/series/filters/limit do not apply."},"flagKey":{"type":"string","description":"Experiment kind only: the experiment flag key whose variants to measure (matched against exposure events' properties.flag)."},"outcomeEvent":{"type":"string","description":"Experiment kind only: the event name that counts as a conversion (e.g. \"checkout_complete\", \"signup\"). A variant converts when an exposed identity emits this event at or after its first exposure."},"exposureEvent":{"type":"string","description":"Experiment kind only, optional: the exposure event name. Defaults to \"experiment_exposure\" (what the flag client emits on first variant read)."}},"required":["source","namespace","measure","range"],"additionalProperties":false},"window":{"type":"object","description":"Generation-time snapshot of the resolved window. Stored, but not authoritative: `spec.range` decides the span a chart shows, so a relative `{days}` range slides forward on every load while this stays pinned. Send the window the spec resolves to now.","properties":{"since":{"type":"integer"},"until":{"type":"integer"}},"required":["since","until"]},"targetSlug":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"Optional kebab-case app slug this widget targets (cross-app dashboards)."}},"required":["kind","title","spec","window"],"additionalProperties":false},"minItems":1}},"required":["name","charts"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/studio/dashboards/{id}":{"get":{"tags":["studio"],"summary":"Get a saved dashboard by id","description":"Get a saved dashboard by id","operationId":"get_studio_dashboards_by_id","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioDashboard"}}}}},"description":"The dashboard"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"delete":{"tags":["studio"],"summary":"Delete a saved dashboard by id","description":"Delete a saved dashboard by id\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_studio_dashboards_by_id","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"boolean"}}}}}}},"description":"Whether a dashboard was removed"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/marozzo/chat":{"post":{"tags":["marozzo"],"summary":"Send a turn to the Marozzo assistant","description":"Non-streaming. The server runs the full agentic loop and returns the complete reply. Pass `threadId` to continue a thread; omit to start a new one (the new id is in the response). Pass `retry=true` (with a `threadId` whose last turn is unanswered) to re-run a turn that previously failed mid-stream. Requires an active membership; service tokens cannot use this.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_marozzo_chat","responses":{"200":{"description":"Assistant turn","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MarozzoChatResult"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"User message. Required unless retry=true."},"threadId":{"type":"string"},"retry":{"type":"boolean"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/marozzo/threads/{id}":{"get":{"tags":["marozzo"],"summary":"Get full thread history","description":"Owner-only. Returns \"Thread not found\" both when the thread does not exist and when the calling user does not own it — owner existence is intentionally not leaked.","operationId":"get_marozzo_threads_by_id","responses":{"200":{"description":"Thread history","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MarozzoThreadHistory"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/dictionaries/search":{"get":{"tags":["dictionaries"],"summary":"Search Florio (1611) and Crusca (1612) dictionaries","description":"Dual-lane search (vector + keyword) across the two historical Italian dictionaries used by the Marozzo assistant for RAG. Merges results by similarity score. Pass `source=florio|crusca` to restrict to one dictionary.","operationId":"get_dictionaries_search","responses":{"200":{"description":"Dictionary hits ordered by similarity score.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DictionaryHit"}},"meta":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query."},{"name":"limit","in":"query","schema":{"type":"integer"},"description":"Maximum results (default 20, max 100)."},{"name":"source","in":"query","schema":{"type":"string","enum":["florio","crusca","all"]},"description":"Dictionary to search (default `all`)."}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/dictionaries/treatises/search":{"get":{"tags":["dictionaries"],"summary":"Search the three Bolognese treatises (1531 / 1550 / 1572)","description":"Dual-lane search (vector + Italian/English keyword) across Manciolino, Marozzo Opera Nova, and dall'Agocchie. Merges by similarity score. Pass `source=manciolino|opera_nova|dall_agocchie` to restrict.","operationId":"get_dictionaries_treatises_search","responses":{"200":{"description":"Treatise hits ordered by similarity score.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TreatiseHit"}},"meta":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query."},{"name":"limit","in":"query","schema":{"type":"integer"},"description":"Maximum results (default 20, max 100)."},{"name":"source","in":"query","schema":{"type":"string","enum":["manciolino","opera_nova","dall_agocchie","all"]},"description":"Treatise to search (default `all`)."}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/dictionaries/treatises/{source}/book/{book}":{"get":{"tags":["dictionaries"],"summary":"List all chapters of a treatise book","description":"Every chapter entry in one Libro. `source` is manciolino, opera_nova, or dall_agocchie.","operationId":"get_dictionaries_treatises_by_source_book_by_book","responses":{"200":{"description":"Chapter entries for the book.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string","enum":["manciolino","opera_nova","dall_agocchie"]}},{"name":"book","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/dictionaries/treatises/{source}/chapter/{book}/{chapter}":{"get":{"tags":["dictionaries"],"summary":"Read one treatise chapter","description":"Single chapter entry by book + chapter. Returns 404 if absent.","operationId":"get_dictionaries_treatises_by_source_chapter_by_book_by_chapter","responses":{"200":{"description":"The chapter entry.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string","enum":["manciolino","opera_nova","dall_agocchie"]}},{"name":"book","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"chapter","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/{namespace}/hero-promos":{"get":{"tags":["hero_promos"],"summary":"List hero promos","description":"Returns hero promos in display order. Pass `?activeOnly=true` to filter to currently visible ones (enabled + within any configured schedule window).","operationId":"get_by_namespace_hero_promos","responses":{"200":{"description":"Hero promos","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HeroPromo"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"activeOnly","in":"query","schema":{"type":"boolean"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["hero_promos"],"summary":"Create a hero promo","description":"Creates a hero promo and appends it to the end of the display order.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_by_namespace_hero_promos","responses":{"201":{"description":"Hero promo created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/HeroPromo"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeroPromoInput"}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/{namespace}/hero-promos/{id}":{"patch":{"tags":["hero_promos"],"summary":"Replace a hero promo (all fields required)","description":"Replace a hero promo (all fields required)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_by_namespace_hero_promos_by_id","responses":{"200":{"description":"Hero promo","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/HeroPromo"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeroPromoInput"}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["hero_promos"],"summary":"Delete a hero promo","description":"Delete a hero promo\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_by_namespace_hero_promos_by_id","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/{namespace}/hero-promos/reorder":{"post":{"tags":["hero_promos"],"summary":"Set the hero promo display order","description":"Pass an array of ids in the desired order. Unknown ids are dropped; promos missing from the list are appended in their current order.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_by_namespace_hero_promos_reorder","responses":{"200":{"description":"New order","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"ordered":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderedIds"],"properties":{"orderedIds":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/aliases/{namespace}/{slug}/v{version}":{"delete":{"tags":["media"],"summary":"Forget a media alias version","description":"Requires update:content in the namespace. Removes a history entry, preserving its asset. Refuses to remove the current version.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_media_aliases_by_namespace_by_slug_vby_version","responses":{"200":{"description":"Version forgotten"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}/replace-file":{"post":{"tags":["media"],"summary":"Replace an existing file (max 10 MB binary)","description":"Replace bytes for an existing file asset. Requires media:admin. The asset id is preserved and any media alias pointing at it keeps working. Prior storage objects are deleted; each replacement gets a new CDN object path so no stale cache is reused. Provide fileData as base64 with no data: prefix (max ~10 MB binary). The asset is ready when this call returns. Replacing mutates bytes for every alias version referencing this id. To preserve history, use media_upload_file then media_alias_set and never replace a history asset.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_by_id_replace_file","responses":{"200":{"description":"Replacement stored; asset id preserved"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaReplaceFile"}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/aliases/{namespace}/{slug}":{"put":{"tags":["media"],"summary":"Set a media alias","description":"Point a versioned media alias at a public or protected asset in an app namespace. Requires update:content in that namespace. The first version pins visibility; later assets must match. Only public aliases return /x/<slug> and /x/<slug>/v<version> paths. Each different asset appends a version. Setting the same asset returns the existing version (already current) without a write, before checking expectedVersion. Optional expectedVersion must match the current version; 0 requires a new alias. A mismatch writes nothing and reports the current version and assetId: re-read and retry. Roll back by setting an older version's assetId, which appends a new version. At the 1000-version cap, use media_alias_forget_version to forget the oldest version before appending. An optional label names the run (max 80 characters).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"put_media_aliases_by_namespace_by_slug","responses":{"200":{"description":"Alias set"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assetId"],"properties":{"assetId":{"type":"string"},"label":{"type":"string","maxLength":80},"expectedVersion":{"type":"integer","minimum":0,"description":"Require this current version before appending; 0 requires a new alias. Same-asset replay returns the existing version before this check."}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"get":{"tags":["media"],"summary":"Get a media alias","description":"Get a media alias","operationId":"get_media_aliases_by_namespace_by_slug","responses":{"200":{"description":"Alias metadata, or null if missing","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/MediaAlias"},{"type":"null"}]}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"delete":{"tags":["media"],"summary":"Delete a media alias","description":"Requires update:content in the target namespace. Deletes the alias only; the media asset is preserved. A missing alias still succeeds.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_media_aliases_by_namespace_by_slug","responses":{"200":{"description":"Alias deleted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/aliases/{namespace}":{"get":{"tags":["media"],"summary":"List media aliases","description":"List media aliases","operationId":"get_media_aliases_by_namespace","responses":{"200":{"description":"Aliases with namespace, slug, current, versions, and updatedAt"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/assets":{"get":{"tags":["media"],"summary":"List media assets","description":"List media assets","operationId":"get_media_assets","responses":{"200":{"description":"Paginated assets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["image","file","audio"]}},{"name":"visibility","in":"query","schema":{"type":"string","enum":["public","protected"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","ready","failed"]}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Comma-separated; asset must contain all","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}":{"get":{"tags":["media"],"summary":"Get a media asset","description":"Get a media asset","operationId":"get_media_assets_by_id","responses":{"200":{"description":"Asset","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MediaAsset"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["media"],"summary":"Update a media asset","description":"Runs the media.update capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_media_assets_by_id","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"visibility":{"type":"string","enum":["public","protected"]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["media"],"summary":"Delete a media asset","description":"Runs the media.remove capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_media_assets_by_id","responses":{"200":{"description":"Deleted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/batch-delete":{"post":{"tags":["media"],"summary":"Delete multiple media assets","description":"Runs the media.batchRemove capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_batch_delete","responses":{"200":{"description":"Deleted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/batch-tags":{"post":{"tags":["media"],"summary":"Add or remove tags across multiple assets","description":"Runs the media.batchAddTags or media.batchRemoveTags capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_batch_tags","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action","ids","tags"],"properties":{"action":{"type":"string","enum":["add","remove"]},"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}/url":{"post":{"tags":["media"],"summary":"Mint a signed URL for a protected asset","description":"Mint a signed URL for a protected asset\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_by_id_url","responses":{"200":{"description":"Signed URL"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transformClass":{"type":"string","enum":["thumb","card","hero","full","square"]},"expiresInSeconds":{"type":"integer"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}/namespaces":{"post":{"tags":["media"],"summary":"Set restricted asset availability (legacy)","description":"Legacy compatibility endpoint. Array means restricted availability; null or empty means library-only. Runs the media.setAllowedNamespaces capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_by_id_namespaces","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["allowedNamespaces"],"properties":{"allowedNamespaces":{"type":["array","null"],"items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}/usage-policy":{"post":{"tags":["media"],"summary":"Set where a media asset may be embedded","description":"Admin-only. Independent from public/protected visibility. Runs the media.setUsagePolicy capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_by_id_usage_policy","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["usagePolicy"],"properties":{"usagePolicy":{"oneOf":[{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["library-only","all"]}}},{"type":"object","required":["mode","namespaces"],"properties":{"mode":{"type":"string","enum":["restricted"]},"namespaces":{"type":"array","items":{"type":"string"}}}}]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}/replace":{"post":{"tags":["media"],"summary":"Replace an existing image (base64 in JSON, max ~10 MB)","description":"Re-upload bytes for an existing image asset. The asset id is preserved; prior CDN objects are deleted and variants regenerate asynchronously. Image assets only.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_by_id_replace","responses":{"200":{"description":"Replacement queued"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mimeType","originalName","size","imageData"],"properties":{"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif"]},"originalName":{"type":"string"},"size":{"type":"integer"},"imageData":{"type":"string","description":"base64-encoded bytes (no data: prefix)"},"aiDescribe":{"type":"boolean","description":"Queue AI metadata suggestions from the replacement file (default false)."}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}/regenerate-ai-metadata":{"post":{"tags":["media"],"summary":"Regenerate AI metadata suggestions for an image","description":"Re-fetch image bytes, run Sonnet tagging/description, and store the result in `aiSuggestion` without overwriting live metadata. Image assets only. Requires `media:admin`.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_by_id_regenerate_ai_metadata","responses":{"200":{"description":"Generation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"generated":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}/apply-ai-suggestion":{"post":{"tags":["media"],"summary":"Apply AI metadata suggestions to live fields","description":"Copy selected fields from `aiSuggestion` into the live asset. Each applied field is marked manually edited. Requires `media:admin`. Runs the media.applyAiSuggestion capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_assets_by_id_apply_ai_suggestion","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"applyDisplayName":{"type":"boolean"},"applyDescription":{"type":"boolean"},"applyTags":{"type":"boolean"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/upload/image":{"post":{"tags":["media"],"summary":"Upload an image (base64 in JSON, max ~10 MB)","description":"Upload an image (base64 in JSON, max ~10 MB)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_upload_image","responses":{"201":{"description":"Created"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mimeType","originalName","size","visibility","imageData"],"properties":{"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif"]},"originalName":{"type":"string"},"size":{"type":"integer"},"visibility":{"type":"string","enum":["public","protected"]},"tags":{"type":"array","items":{"type":"string"}},"imageData":{"type":"string","description":"base64-encoded bytes (no data: prefix)"},"allowedNamespaces":{"type":"array","items":{"type":"string"},"description":"Protected-only namespace allowlist binding, set at upload time."},"usagePolicy":{"oneOf":[{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["library-only","all"]}}},{"type":"object","required":["mode","namespaces"],"properties":{"mode":{"type":"string","enum":["restricted"]},"namespaces":{"type":"array","items":{"type":"string"}}}}]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/upload/file":{"post":{"tags":["media"],"summary":"Upload an arbitrary file (base64 in JSON)","description":"Upload an arbitrary file (base64 in JSON)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_upload_file","responses":{"201":{"description":"Created"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mimeType","originalName","size","visibility","fileData","extension"],"properties":{"mimeType":{"type":"string"},"originalName":{"type":"string"},"size":{"type":"integer"},"visibility":{"type":"string","enum":["public","protected"]},"tags":{"type":"array","items":{"type":"string"}},"fileData":{"type":"string"},"extension":{"type":"string"},"allowedNamespaces":{"type":"array","items":{"type":"string"},"description":"Protected-only namespace allowlist binding, set at upload time."},"usagePolicy":{"oneOf":[{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["library-only","all"]}}},{"type":"object","required":["mode","namespaces"],"properties":{"mode":{"type":"string","enum":["restricted"]},"namespaces":{"type":"array","items":{"type":"string"}}}}]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/upload/audio":{"post":{"tags":["media"],"summary":"Upload an audio clip (base64 in JSON, max 10 MB)","description":"Creates an audio asset and uploads its bytes before returning a ready asset id.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_upload_audio","responses":{"201":{"description":"Created and ready"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["audioData","mimeType","visibility"],"properties":{"audioData":{"type":"string","description":"base64-encoded audio bytes"},"mimeType":{"type":"string","enum":["audio/webm","audio/ogg","audio/mpeg","audio/mp4","audio/x-m4a","audio/aac","audio/wav","audio/x-wav","audio/flac"]},"filename":{"type":"string"},"durationSec":{"type":"number"},"visibility":{"type":"string","enum":["public","protected"]},"tags":{"type":"array","items":{"type":"string"}},"namespaces":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/audio/uploads":{"post":{"tags":["media"],"summary":"Open a multipart audio upload","description":"Creates a 24-hour upload session for an audio file up to 100 MiB.\n\nThis operation also accepts a live Convex session JWT in the Bearer header.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_audio_uploads","responses":{"201":{"description":"Upload session opened"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","mimeType","size","visibility"],"properties":{"filename":{"type":"string"},"mimeType":{"type":"string","enum":["audio/webm","audio/ogg","audio/mpeg","audio/mp4","audio/x-m4a","audio/aac","audio/wav","audio/x-wav","audio/flac"]},"size":{"type":"integer","minimum":1,"maximum":104857600},"durationSec":{"type":"number","minimum":0},"visibility":{"type":"string","enum":["public","protected"]},"tags":{"type":"array","items":{"type":"string"}},"namespaces":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/audio/uploads/{id}/parts/{part}":{"put":{"tags":["media"],"summary":"Upload one audio byte range","description":"Uploads one exact-length raw byte part. Re-sending the same part number and length safely overwrites that part.\n\nThis operation also accepts a live Convex session JWT in the Bearer header.","operationId":"put_media_audio_uploads_by_id_parts_by_part","responses":{"200":{"description":"Part stored"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"part","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/audio/uploads/{id}/complete":{"post":{"tags":["media"],"summary":"Complete a multipart audio upload","description":"Creates the pending asset and schedules streaming assembly. Poll the asset until it is ready.\n\nThis operation also accepts a live Convex session JWT in the Bearer header.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_audio_uploads_by_id_complete","responses":{"202":{"description":"Assembly scheduled"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/audio/uploads/{id}":{"get":{"tags":["media"],"summary":"Get multipart audio upload status","description":"Returns part receipt and assembly status for the caller-owned upload session.\n\nThis operation also accepts a live Convex session JWT in the Bearer header.","operationId":"get_media_audio_uploads_by_id","responses":{"200":{"description":"Upload status"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"delete":{"tags":["media"],"summary":"Abort a multipart audio upload","description":"Marks an open upload failed and schedules its stored parts for deletion.\n\nThis operation also accepts a live Convex session JWT in the Bearer header.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_media_audio_uploads_by_id","responses":{"200":{"description":"Upload aborted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/stats":{"get":{"tags":["media"],"summary":"Media library stats","description":"Runs the media.stats capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_media_stats","responses":{"200":{"description":"Stats"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/tags":{"get":{"tags":["media"],"summary":"Unique media tags","description":"Runs the media.uniqueTags capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_media_tags","responses":{"200":{"description":"Tags"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/cdn-config":{"get":{"tags":["media"],"summary":"CDN base URLs","description":"Runs the media.cdnConfig capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_media_cdn_config","responses":{"200":{"description":"CDN config"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/videos":{"get":{"tags":["media"],"summary":"List videos","description":"List videos","operationId":"get_media_videos","responses":{"200":{"description":"Paginated videos"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/{id}":{"get":{"tags":["media"],"summary":"Get a video","description":"Get a video","operationId":"get_media_videos_by_id","responses":{"200":{"description":"Video","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VideoAsset"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["media"],"summary":"Update a video","description":"Runs the media.updateVideo capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_media_videos_by_id","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["media"],"summary":"Delete a video","description":"Runs the media.removeVideo capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_media_videos_by_id","responses":{"200":{"description":"Deleted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/by-bunny-id/{bunnyVideoId}":{"get":{"tags":["media"],"summary":"Resolve video metadata by Bunny id","description":"Resolve video metadata by Bunny id","operationId":"get_media_videos_by_bunny_id_by_bunnyVideoId","responses":{"200":{"description":"Video metadata"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"bunnyVideoId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/upload":{"post":{"tags":["media"],"summary":"Begin a video upload (TUS)","description":"Begin a video upload (TUS)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_videos_upload","responses":{"201":{"description":"TUS session"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/{id}/finalize":{"post":{"tags":["media"],"summary":"Finalize a video upload","description":"Finalize a video upload\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_videos_by_id_finalize","responses":{"200":{"description":"Encoding state"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/{id}/cancel":{"post":{"tags":["media"],"summary":"Cancel an in-flight video upload","description":"Cancel an in-flight video upload\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_videos_by_id_cancel","responses":{"200":{"description":"Cancelled"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/{id}/namespaces":{"post":{"tags":["media"],"summary":"Set restricted video availability (legacy)","description":"Legacy compatibility endpoint. Array means restricted availability; null or empty means library-only. Runs the media.setVideoAllowedNamespaces capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_videos_by_id_namespaces","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["allowedNamespaces"],"properties":{"allowedNamespaces":{"type":["array","null"],"items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/{id}/usage-policy":{"post":{"tags":["media"],"summary":"Set where a video may be embedded","description":"Admin-only. Independent from public/protected visibility. Runs the media.setVideoUsagePolicy capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_videos_by_id_usage_policy","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["usagePolicy"],"properties":{"usagePolicy":{"oneOf":[{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["library-only","all"]}}},{"type":"object","required":["mode","namespaces"],"properties":{"mode":{"type":"string","enum":["restricted"]},"namespaces":{"type":"array","items":{"type":"string"}}}}]}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/{bunnyVideoId}/signed-url":{"post":{"tags":["media"],"summary":"Mint a signed embed URL for a protected video","description":"Mint a signed embed URL for a protected video","operationId":"post_media_videos_by_bunnyVideoId_signed_url","responses":{"200":{"description":"Signed URL"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"bunnyVideoId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/{bunnyVideoId}/thumbnails":{"post":{"tags":["media"],"summary":"Mint signed thumbnail URLs for a video","description":"Mint signed thumbnail URLs for a video\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_videos_by_bunnyVideoId_thumbnails","responses":{"200":{"description":"Poster and preview URLs"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"bunnyVideoId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/batch-delete":{"post":{"tags":["media"],"summary":"Delete multiple videos","description":"Runs the media.batchRemoveVideos capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_videos_batch_delete","responses":{"200":{"description":"Deleted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/batch-tags":{"post":{"tags":["media"],"summary":"Add/remove tags on multiple videos","description":"Runs the media.batchAddVideoTags or media.batchRemoveVideoTags capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_media_videos_batch_tags","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/stats":{"get":{"tags":["media"],"summary":"Video library stats","description":"Video library stats","operationId":"get_media_videos_stats","responses":{"200":{"description":"Stats"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/videos/tags":{"get":{"tags":["media"],"summary":"Unique video tags","description":"Runs the media.uniqueVideoTags capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_media_videos_tags","responses":{"200":{"description":"Tags"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/{id}/resolve":{"get":{"tags":["media"],"summary":"Resolve a CDN URL for an asset","description":"Public assets return a direct CDN URL. Protected assets return a marker — call POST /assets/{id}/url for a time-limited signed URL.","operationId":"get_media_assets_by_id_resolve","responses":{"200":{"description":"Resolved URL or marker"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"transformClass","in":"query","schema":{"type":"string"},"description":"Optional Bunny image transform class."}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/resolve-urls":{"post":{"tags":["media"],"summary":"Resolve CDN URLs for up to 100 (assetId, transformClass) pairs","description":"Results are positionally aligned with `items` — a missing or hidden asset yields `null` in its slot rather than shifting the array.","operationId":"post_media_assets_resolve_urls","responses":{"200":{"description":"Resolved URLs or markers, one per requested item","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":["object","null"],"properties":{"url":{"type":["string","null"]},"requiresSignedUrl":{"type":"boolean"},"blurhash":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"variants":{"description":"Same-crop-geometry srcset candidates (ascending width), present on public assets with more than one rendition of the resolved framing.","type":"array","items":{"type":"object","required":["url","width"],"properties":{"url":{"type":"string"},"width":{"type":"integer"}}}}}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":100,"items":{"type":"object","required":["assetId"],"properties":{"assetId":{"type":"string"},"transformClass":{"type":"string","enum":["thumb","card","hero","full","square"]}}}}}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/media/assets/by-ids":{"post":{"tags":["media"],"summary":"Batch-fetch up to 100 media assets by id","description":"Batch-fetch up to 100 media assets by id","operationId":"post_media_assets_by_ids","responses":{"200":{"description":"Matching assets (missing ids are omitted)"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"maxItems":100}}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/schema":{"get":{"tags":["platform"],"summary":"Get app schema","description":"Get app schema","operationId":"get_platform_apps_by_slug_schema","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/artifact":{"put":{"tags":["platform"],"summary":"Write app artifact envelope","description":"Write app artifact envelope\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"put_platform_apps_by_slug_artifact","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"The expected base no longer matches the stored artifact; nothing was written","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["sdl","app-schema","function"]},"document":{"type":"string"},"def":{"type":"object"},"page":{"type":"string"},"fn":{"type":"string"},"function":{"type":"object"},"origin":{"type":"object","properties":{"source":{"type":"string","enum":["generation","refinement","manual","restore"]},"runId":{"type":"string"},"revision":{"type":"number"},"engine":{"type":"string","enum":["workflow","interactive"]}},"required":["source"]},"expected":{"type":"object","properties":{"version":{"type":"number"},"canonicalHash":{"type":"string"}}}},"required":["kind"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"get":{"tags":["platform"],"summary":"Get app artifact envelope (authoring)","description":"Get app artifact envelope (authoring)","operationId":"get_platform_apps_by_slug_artifact","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"fn","in":"query","required":false,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/artifact/functions":{"get":{"tags":["platform"],"summary":"List stored function rows","description":"List stored function rows","operationId":"get_platform_apps_by_slug_artifact_functions","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/artifact/pages":{"get":{"tags":["platform"],"summary":"List SDL page rows","description":"List SDL page rows","operationId":"get_platform_apps_by_slug_artifact_pages","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/artifact/versions":{"get":{"tags":["platform"],"summary":"List artifact version snapshots","description":"List artifact version snapshots","operationId":"get_platform_apps_by_slug_artifact_versions","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"fn","in":"query","required":false,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/artifact/versions/{version}":{"get":{"tags":["platform"],"summary":"Get one artifact version snapshot","description":"Get one artifact version snapshot","operationId":"get_platform_apps_by_slug_artifact_versions_by_version","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"fn","in":"query","required":false,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/entities/{entity}":{"get":{"tags":["platform"],"summary":"List entity rows","description":"List entity rows","operationId":"get_platform_apps_by_slug_entities_by_entity","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string"}},{"name":"sort_key","in":"query","schema":{"type":"string"}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"filters","in":"query","description":"Optional JSON-encoded filter array. Empty values are inactive; active filters use AND semantics and the DataTable operators contains, equals, not_equals, in, not_in, starts_with, and ends_with.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["platform"],"summary":"Create entity row","description":"Create entity row\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_platform_apps_by_slug_entities_by_entity","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"object"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/entities/{entity}/{id}":{"get":{"tags":["platform"],"summary":"Get entity row","description":"Get entity row","operationId":"get_platform_apps_by_slug_entities_by_entity_by_id","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["platform"],"summary":"Update entity row","description":"Update entity row\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_platform_apps_by_slug_entities_by_entity_by_id","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"patch":{"type":"object"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["platform"],"summary":"Delete entity row","description":"Policy-aware removal. For trash-enabled entities this moves the row to managed trash (recoverable until purged); for hard-delete entities it removes permanently. The app schema declares which policy applies.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_platform_apps_by_slug_entities_by_entity_by_id","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/entities/{entity}/tombstones":{"get":{"tags":["platform"],"summary":"List entity trash","description":"List tombstones for a trash-enabled entity, newest deletion first. Requires read-trash.","operationId":"get_platform_apps_by_slug_entities_by_entity_tombstones","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"number"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/entities/{entity}/tombstones/{tombstoneId}/restore":{"post":{"tags":["platform"],"summary":"Restore entity row from trash","description":"Conflict-safe restore: refused if a live row occupies the original key, if the snapshot no longer validates against the current schema, or if it references rows that no longer exist. The tombstone survives a refused restore.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_platform_apps_by_slug_entities_by_entity_tombstones_by_tombstoneId_restore","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string"}},{"name":"tombstoneId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/entities/{entity}/tombstones/{tombstoneId}":{"delete":{"tags":["platform"],"summary":"Purge entity tombstone","description":"Permanently remove a tombstone. Not implied by delete permission; requires purge.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_platform_apps_by_slug_entities_by_entity_tombstones_by_tombstoneId","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string"}},{"name":"tombstoneId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/platform/schema-info":{"get":{"tags":["platform"],"summary":"Introspect the Convex database schema","description":"Returns 403 if the caller lacks manage:database in dev-launcher.","operationId":"get_platform_schema_info","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/namespaces":{"get":{"tags":["platform"],"summary":"List manageable platform RBAC namespaces","description":"List manageable platform RBAC namespaces","operationId":"get_platform_namespaces","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps":{"post":{"tags":["platform"],"summary":"Create a platform-hosted app","description":"Create a platform-hosted app\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_platform_apps","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","displayName"],"properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/platform/register":{"post":{"tags":["platform"],"summary":"Register an app namespace with RBAC","description":"Register an app namespace with RBAC\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_platform_register","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appSlug","appInfo"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/platform/apps/{slug}/settings":{"patch":{"tags":["platform"],"summary":"Set a single app setting","description":"Set a single app setting\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_platform_apps_by_slug_settings","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"value":{}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/html-apps":{"post":{"tags":["html-apps"],"summary":"Create an HTML app","description":"Deprecated: use `POST /api/v2/platform/action/htmlApp.create` or the MCP tool of the same capability, which this route now runs.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_html_apps","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["ok","slug"],"properties":{"ok":{"const":true},"slug":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"},"displayName":{"type":"string","minLength":1},"description":{"type":"string"},"icon":{"type":"string"}},"required":["slug","displayName"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/html-apps/{slug}/versions":{"post":{"tags":["html-apps"],"summary":"Upload an HTML app version","description":"Deprecated: use `POST /api/v2/platform/action/htmlApp.putVersion` or the MCP tool of the same capability, which this route now runs.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_html_apps_by_slug_versions","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"html":{"type":"string","description":"HTML file as a JSON string, at most 3,000,000 UTF-8 bytes."},"note":{"type":"string","maxLength":1000},"retention":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ttlMs":{"type":"integer","minimum":60000,"maximum":2592000000}},"required":["ttlMs"],"additionalProperties":false}},"required":["html"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"get":{"tags":["html-apps"],"summary":"List HTML app versions","description":"Deprecated: use `POST /api/v2/platform/read/htmlApp.listVersions` or the MCP tool of the same capability, which this route now runs.","operationId":"get_html_apps_by_slug_versions","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"bytes":{"type":"integer","minimum":0,"maximum":3000000},"authorSubject":{"type":"string"},"createdAt":{"type":"integer","minimum":0,"maximum":9999999999999},"note":{"type":"string","maxLength":1000},"deleting":{"type":"boolean"},"declaredCapabilities":{"maxItems":32,"type":"array","items":{"type":"string"}},"approvedCapabilities":{"type":"object","properties":{"names":{"maxItems":32,"type":"array","items":{"type":"string"}},"by":{"type":"string"},"at":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["names","by","at"],"additionalProperties":false}},"required":["hash","bytes","authorSubject","createdAt"],"additionalProperties":false}},"isDone":{"type":"boolean"},"continueCursor":{"type":["string","null"]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},{"name":"cursor","in":"query","schema":{"type":"string","pattern":"^__html:log:\\d{13}:[a-f0-9]{64}$","description":"continueCursor from the previous page; omit to start the list."}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/html-apps/{slug}/edits":{"post":{"tags":["html-apps"],"summary":"Edit an HTML app version","description":"Store a new version made by applying `edits` to the version `baseHash`, without sending the whole file. Requires manage:app on the slug. Read the version first with html_app_get_source and copy each `search` from it. If an edit does not apply, nothing is stored and the error names the edit. With `makeCurrent`, the new version becomes current only if `baseHash` still is; otherwise it stays stored, `madeCurrent` is false and `staleBase` names the current version.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_html_apps_by_slug_edits","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["hash","baseHash","bytes","edits","madeCurrent"],"properties":{"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"baseHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"bytes":{"type":"integer","description":"Size of the new version in UTF-8 bytes."},"edits":{"type":"integer"},"madeCurrent":{"type":"boolean"},"staleBase":{"type":"object","required":["currentHash"],"properties":{"currentHash":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]}},"description":"Present when `makeCurrent` was asked and `baseHash` was no longer current."}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseHash":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"The version the edits apply to, as html_app_get_source returned it."},"edits":{"type":"array","minItems":1,"maxItems":100,"description":"Replacements applied in order, each to the text the ones before it left. `search` must occur exactly once: exactly, or line by line ignoring trailing whitespace.","items":{"type":"object","properties":{"search":{"type":"string","minLength":1},"replace":{"type":"string"}},"required":["search","replace"],"additionalProperties":false}},"note":{"type":"string","maxLength":1000},"makeCurrent":{"type":"boolean","description":"Make the new version current, only if `baseHash` still is. Default false."}},"required":["baseHash","edits"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/html-apps/{slug}/current":{"put":{"tags":["html-apps"],"summary":"Select the current HTML app version","description":"Deprecated: use `POST /api/v2/platform/write/htmlApp.setCurrent` or the MCP tool of the same capability, which this route now runs.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"put_html_apps_by_slug_current","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expectedCurrent":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Move the pointer only if this hash is still current."}},"required":["hash"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"get":{"tags":["html-apps"],"summary":"Get the current HTML app version","description":"Deprecated: use `POST /api/v2/platform/read/htmlApp.current` or the MCP tool of the same capability, which this route now runs.","operationId":"get_html_apps_by_slug_current","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"anyOf":[{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"bytes":{"type":"integer","minimum":0,"maximum":3000000},"authorSubject":{"type":"string"},"createdAt":{"type":"integer","minimum":0,"maximum":9999999999999},"note":{"type":"string","maxLength":1000},"deleting":{"type":"boolean"},"declaredCapabilities":{"maxItems":32,"type":"array","items":{"type":"string"}},"approvedCapabilities":{"type":"object","properties":{"names":{"maxItems":32,"type":"array","items":{"type":"string"}},"by":{"type":"string"},"at":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["names","by","at"],"additionalProperties":false}},"required":["hash","bytes","authorSubject","createdAt"],"additionalProperties":false},{"type":"null"}]}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/html-apps/grounding":{"get":{"tags":["html-apps"],"summary":"Get the HTML app grounding","description":"Return the Markdown reference for writing an HTML app: the frame rules (what breaks in the sandbox), the design tokens, the component tags every app on the app shell already has, and reference apps. Read it before writing a version for html_app_put_version. Build controls from the components, which bring Furnace's look and behaviour with no CSS; free-form HTML, CSS and JavaScript styled with the tokens is welcome where no component fits.","operationId":"get_html_apps_grounding","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"string","description":"The grounding bundle as Markdown."}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The grounding bundle could not be fetched from the app shell host; nothing is cached."}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/html-apps/{slug}/members":{"get":{"tags":["html-apps"],"summary":"List the people an HTML app is shared with","description":"Deprecated: use `POST /api/v2/platform/read/htmlApp.members` or the MCP tool of the same capability, which this route now runs.","operationId":"get_html_apps_by_slug_members","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["members","truncated"],"properties":{"members":{"type":"array","items":{"type":"object","required":["memberId","name","email","role","isYou"],"properties":{"memberId":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"},"role":{"type":"string","enum":["admin","viewer","editor","other"]},"isYou":{"type":"boolean"}}}},"truncated":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["html-apps"],"summary":"Share an HTML app with a person","description":"Deprecated: use `POST /api/v2/platform/write/htmlApp.shareByEmail` or the MCP tool of the same capability, which this route now runs.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_html_apps_by_slug_members","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","minLength":3,"description":"The email address of the person to share with."},"role":{"type":"string","enum":["viewer","editor"],"description":"viewer opens the app; editor may also change it."}},"required":["email","role"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["html-apps"],"summary":"Stop sharing an HTML app with a person","description":"Deprecated: use `POST /api/v2/platform/write/htmlApp.unshare` or the MCP tool of the same capability, which this route now runs.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_html_apps_by_slug_members","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["removed","stillHasAccess"],"properties":{"removed":{"type":"boolean"},"stillHasAccess":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"memberId":{"type":"string","minLength":1}},"required":["memberId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/html-apps/{slug}/removal":{"get":{"tags":["html-apps"],"summary":"Show what removing an HTML app deletes","description":"Deprecated: use `POST /api/v2/platform/read/htmlApp.removalSummary` or the MCP tool of the same capability, which this route now runs.","operationId":"get_html_apps_by_slug_removal","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["dataRows","versions","people","sharedWithOthers"],"properties":{"dataRows":{"type":"object","required":["count","capped"],"properties":{"count":{"type":"integer"},"capped":{"type":"boolean"}}},"versions":{"type":"object","required":["count","capped"],"properties":{"count":{"type":"integer"},"capped":{"type":"boolean"}}},"people":{"type":"object","required":["count","capped"],"properties":{"count":{"type":"integer"},"capped":{"type":"boolean"}}},"sharedWithOthers":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/html-apps/{slug}":{"delete":{"tags":["html-apps"],"summary":"Remove an HTML app","description":"Permanently remove the app with its versions, saved data, sharing and conversations. This cannot be undone. Requires manage:roles on the slug. Before calling, show the person html_app_removal_summary and get their explicit confirmation; then pass the slug again as `confirmSlug`.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_html_apps_by_slug","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["ok","slug"],"properties":{"ok":{"const":true},"slug":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmSlug":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},"required":["confirmSlug"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/html-apps/{slug}/source":{"get":{"tags":["html-apps"],"summary":"Read an HTML app version’s source","description":"Return the HTML of the current version, or of `hash`, with its metadata. Requires access:app on the slug. Read the current version before writing the next one with html_app_put_version. `startLine` and `lineCount` return only those lines, joined by newlines, so a large file can be read in parts; `totalLines` says how many the file has.","operationId":"get_html_apps_by_slug_source","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["hash","createdAt","bytes","totalLines","startLine","endLine","html"],"properties":{"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"note":{"type":"string","maxLength":1000},"createdAt":{"type":"integer"},"bytes":{"type":"integer","description":"Size of the whole file in UTF-8 bytes."},"totalLines":{"type":"integer"},"startLine":{"type":"integer"},"endLine":{"type":"integer"},"html":{"type":"string","description":"The whole file as stored, or the requested lines."}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":31,"pattern":"^[a-z][a-z0-9-]{1,30}$"}},{"name":"hash","in":"query","schema":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Version to read; omit for the current version."}},{"name":"startLine","in":"query","schema":{"type":"integer","minimum":1,"description":"First line to return, counted from 1."}},{"name":"lineCount","in":"query","schema":{"type":"integer","minimum":1,"description":"Most lines to return; omit for the rest of the file."}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/roles":{"get":{"tags":["access"],"summary":"List role definitions for a namespace","description":"List role definitions for a namespace","operationId":"get_access_roles","responses":{"200":{"description":"Role definitions","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"appNamespace","in":"query","required":true,"schema":{"type":"string"}},{"name":"adminNamespace","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["access"],"summary":"Define or update a role","description":"Create or update a role definition. Requires manage:roles in the namespace.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_access_roles","responses":{"200":{"description":"Role definition","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appNamespace","roleName","permissions"],"properties":{"appNamespace":{"type":"string"},"roleName":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"adminNamespace":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/users/{subject}/{aspect}":{"get":{"tags":["access"],"summary":"Get a user’s roles, direct permissions, or bundle","description":"aspect ∈ roles|permissions|bundle. Own is free; others require read:users.","operationId":"get_access_users_by_subject_by_aspect","responses":{"200":{"description":"RBAC data","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object"}},{"type":"object"},{"type":"null"}]}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"subject","in":"path","required":true,"schema":{"type":"string"}},{"name":"aspect","in":"path","required":true,"schema":{"type":"string","enum":["roles","permissions","bundle"]}},{"name":"appNamespace","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/namespaces":{"get":{"tags":["access"],"summary":"List accessible app namespaces","description":"List accessible app namespaces","operationId":"get_access_namespaces","responses":{"200":{"description":"Namespace list","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/auth-events":{"get":{"tags":["access"],"summary":"Recent auth events","description":"Recent auth events","operationId":"get_access_auth_events","responses":{"200":{"description":"Auth events","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/alerts":{"get":{"tags":["access"],"summary":"List security alerts","description":"List security alerts","operationId":"get_access_alerts","responses":{"200":{"description":"Alerts","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/alerts/{id}":{"patch":{"tags":["access"],"summary":"Update alert status or ban from alert","description":"Update alert status or ban from alert\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_access_alerts_by_id","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/bans":{"post":{"tags":["access"],"summary":"Issue a ban / suspension / warning","description":"Issue a ban / suspension / warning\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_access_bans","responses":{"201":{"description":"Ban issued","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/bans/{id}":{"delete":{"tags":["access"],"summary":"Revoke an active ban","description":"{id} is the ban id. Shares the path template with GET, where {id} is a user subject.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_access_bans_by_id","responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"get":{"tags":["access"],"summary":"List bans for a user","description":"{id} is the user subject. Shares the path template with DELETE, where {id} is a ban id.","operationId":"get_access_bans_by_id","responses":{"200":{"description":"Bans for the user","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/pats":{"get":{"tags":["access"],"summary":"List the caller’s personal access tokens","description":"Owner-scoped metadata for every PAT belonging to the calling user. Includes optional scope when the token was minted with least-privilege narrowing.","operationId":"get_access_pats","responses":{"200":{"description":"PAT metadata","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PatListEntry"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/subscribers":{"get":{"tags":["access"],"summary":"List subscribers","description":"List subscribers","operationId":"get_access_subscribers","responses":{"200":{"description":"Subscribers","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/subscribers/grant":{"post":{"tags":["access"],"summary":"Grant a complimentary subscription","description":"Grant a complimentary subscription\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_access_subscribers_grant","responses":{"200":{"description":"Granted","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/members/stats":{"get":{"tags":["access"],"summary":"Member stats over a window","description":"Member stats over a window","operationId":"get_access_members_stats","responses":{"200":{"description":"Member stats","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"days","in":"query","required":true,"schema":{"type":"integer"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/members/timeseries":{"get":{"tags":["access"],"summary":"Member count time series","description":"Member count time series","operationId":"get_access_members_timeseries","responses":{"200":{"description":"Member time series","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"days","in":"query","required":true,"schema":{"type":"integer"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/members/breakdown":{"get":{"tags":["access"],"summary":"Active members by subscription tier","description":"Active members by subscription tier","operationId":"get_access_members_breakdown","responses":{"200":{"description":"Member breakdown","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/members/recent-activity":{"get":{"tags":["access"],"summary":"Recently active members","description":"Recently active members","operationId":"get_access_members_recent_activity","responses":{"200":{"description":"Recent member activity","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/roles/{name}":{"get":{"tags":["access"],"summary":"Get a role definition","description":"Get a role definition","operationId":"get_access_roles_by_name","responses":{"200":{"description":"Role definition","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":["object","null"]}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"appNamespace","in":"query","required":true,"schema":{"type":"string"}},{"name":"adminNamespace","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"delete":{"tags":["access"],"summary":"Delete a role and strip it from all members","description":"Delete a role and strip it from all members\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_access_roles_by_name","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"appNamespace","in":"query","required":true,"schema":{"type":"string"}},{"name":"adminNamespace","in":"query","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/roles/{name}/members":{"get":{"tags":["access"],"summary":"List the members holding a role","description":"List the members holding a role","operationId":"get_access_roles_by_name_members","responses":{"200":{"description":"Role members","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"appNamespace","in":"query","required":true,"schema":{"type":"string"}},{"name":"adminNamespace","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/auth-events/stats":{"get":{"tags":["access"],"summary":"Auth-event stats","description":"Auth-event stats","operationId":"get_access_auth_events_stats","responses":{"200":{"description":"Auth-event stats","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"days","in":"query","schema":{"type":"integer"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/auth-events/by-user/{userId}":{"get":{"tags":["access"],"summary":"Auth-event history for a user","description":"Auth-event history for a user","operationId":"get_access_auth_events_by_user_by_userId","responses":{"200":{"description":"Auth events for the user","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/alerts/stats":{"get":{"tags":["access"],"summary":"Security alert stats","description":"Security alert stats","operationId":"get_access_alerts_stats","responses":{"200":{"description":"Alert stats","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/bans/active":{"get":{"tags":["access"],"summary":"List all active bans","description":"List all active bans","operationId":"get_access_bans_active","responses":{"200":{"description":"Active bans","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/subscribers/stats":{"get":{"tags":["access"],"summary":"Subscriber stats","description":"Subscriber stats","operationId":"get_access_subscribers_stats","responses":{"200":{"description":"Subscriber stats","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/subscribers/revoke":{"post":{"tags":["access"],"summary":"Revoke a complimentary subscription","description":"Revoke a complimentary subscription\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_access_subscribers_revoke","responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userSubject"],"properties":{"userSubject":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/gdpr/export":{"post":{"tags":["access"],"summary":"Request a GDPR data export (self-service)","description":"Request a GDPR data export (self-service)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_access_gdpr_export","responses":{"201":{"description":"Export requested","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"get":{"tags":["access"],"summary":"Get the caller’s GDPR export status","description":"Get the caller’s GDPR export status","operationId":"get_access_gdpr_export","responses":{"200":{"description":"Export status","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":["object","null"]}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/roles/{name}/{action}":{"post":{"tags":["access"],"summary":"Assign or revoke a role for a user","description":"action ∈ assign|revoke. Requires assign:roles in the namespace.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_access_roles_by_name_by_action","responses":{"200":{"description":"Assignment result","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","enum":["assign","revoke"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appNamespace","userSubject"],"properties":{"appNamespace":{"type":"string"},"userSubject":{"type":"string"},"adminNamespace":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/users/{subject}/permissions":{"post":{"tags":["access"],"summary":"Grant a direct permission to a user","description":"Grant a direct permission to a user\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_access_users_by_subject_permissions","responses":{"201":{"description":"Permission granted","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"subject","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appNamespace","permission"],"properties":{"appNamespace":{"type":"string"},"permission":{"type":"string"},"adminNamespace":{"type":"string"},"expiresAt":{"type":"integer","description":"Epoch ms; omit for no expiry"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/users/{subject}/permissions/{permission}":{"delete":{"tags":["access"],"summary":"Revoke a direct permission from a user","description":"Revoke a direct permission from a user\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_access_users_by_subject_permissions_by_permission","responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"subject","in":"path","required":true,"schema":{"type":"string"}},{"name":"permission","in":"path","required":true,"schema":{"type":"string"}},{"name":"appNamespace","in":"query","required":true,"schema":{"type":"string"}},{"name":"adminNamespace","in":"query","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/access/users/by-subjects":{"post":{"tags":["access"],"summary":"Resolve subject ids to user records","description":"Resolve subject ids to user records","operationId":"post_access_users_by_subjects","responses":{"200":{"description":"Resolved users","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subjects"],"properties":{"subjects":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/users/search":{"get":{"tags":["access"],"summary":"Search users by email/name (security dashboard)","description":"Search users by email/name (security dashboard)","operationId":"get_access_users_search","responses":{"200":{"description":"Matching users","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/subscribers/search":{"get":{"tags":["access"],"summary":"Search users for a complimentary subscription grant","description":"Search users for a complimentary subscription grant","operationId":"get_access_subscribers_search","responses":{"200":{"description":"Matching users + subscription status","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/access/subscribers/stripe-prefix":{"get":{"tags":["access"],"summary":"Stripe dashboard URL prefix (test/live)","description":"Stripe dashboard URL prefix (test/live)","operationId":"get_access_subscribers_stripe_prefix","responses":{"200":{"description":"Prefix string","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"string"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/feature-flags":{"get":{"tags":["feature_flags"],"summary":"List feature flags","description":"List feature flags","operationId":"get_feature_flags","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","archived"]}},{"name":"kind","in":"query","schema":{"type":"string","enum":["flag","entitlement","config"]}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["feature_flags"],"summary":"Create a feature flag","description":"Create a feature flag\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_feature_flags","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","type","defaultValue","description"],"properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["flag","entitlement","config"]},"type":{"type":"string","enum":["boolean","string","number","json"]},"defaultValue":{},"description":{"type":"string"},"rules":{"type":"array","items":{"type":"object"}},"experiment":{"type":"object"},"appNamespaces":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/feature-flags/{key}":{"get":{"tags":["feature_flags"],"summary":"Get a feature flag by key","description":"Get a feature flag by key","operationId":"get_feature_flags_by_key","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["feature_flags"],"summary":"Update a feature flag","description":"Update a feature flag\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_feature_flags_by_key","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/feature-flags/{key}/activate":{"patch":{"tags":["feature_flags"],"summary":"Activate a draft flag","description":"Activate a draft flag\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_feature_flags_by_key_activate","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/feature-flags/{key}/deactivate":{"patch":{"tags":["feature_flags"],"summary":"Deactivate a flag (kill-switch)","description":"Deactivate a flag (kill-switch)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_feature_flags_by_key_deactivate","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/feature-flags/{key}/archive":{"patch":{"tags":["feature_flags"],"summary":"Archive a flag (soft delete)","description":"Archive a flag (soft delete)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_feature_flags_by_key_archive","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found"},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/feature-flags/{key}/duplicate":{"patch":{"tags":["feature_flags"],"summary":"Duplicate a flag","description":"Duplicate a flag\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_feature_flags_by_key_duplicate","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["newKey"],"properties":{"newKey":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/ops/read/{operation}":{"post":{"tags":["ops"],"summary":"Run an ops read operation","description":"Supported operations: list_audit_log, search, get_index_health, admin_search, admin_search_all, get_api_usage, ai_usage, alerts_list, alerts_get, tasks_recent, html_app_run_failures, tasks_stuck, task_crons_list, task_crons_supported_types, app_purge_status, app_runtime_controls, app_functions_inventory, platform_capability_controls. alerts_list runs the alert.adminList capability; alerts_get runs the alert.adminGet capability, through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"post_ops_read_by_operation","responses":{"200":{"description":"Ops operation result"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"operation","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/ops/write/{operation}":{"post":{"tags":["ops"],"summary":"Run an ops write operation","description":"Supported operations: ai_credit_grant, alerts_create, alerts_update, alerts_activate, alerts_deactivate, alerts_delete, tasks_retrigger, task_crons_upsert, task_crons_set_enabled, task_crons_delete, task_crons_run_now, app_purge_dry_run, app_purge_run, app_unregister, app_runtime_control_set, platform_capability_control_set. alerts_create runs the alert.adminCreate capability; alerts_update runs the alert.adminUpdate capability; alerts_activate runs the alert.adminActivate capability; alerts_deactivate runs the alert.adminDeactivate capability; alerts_delete runs the alert.adminDelete capability; tasks_retrigger runs the durableJob.retrigger capability, through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_ops_write_by_operation","responses":{"200":{"description":"Ops operation result"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"operation","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/notifications":{"get":{"tags":["notifications"],"summary":"List notification broadcasts","description":"Runs the broadcast.list capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_notifications","responses":{"200":{"description":"Broadcasts, newest first"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["notifications"],"summary":"Create a draft broadcast","description":"Runs the broadcast.create capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_notifications","responses":{"200":{"description":"New broadcast id"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/notifications/{id}":{"get":{"tags":["notifications"],"summary":"Get a notification broadcast","description":"Runs the broadcast.get capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_notifications_by_id","responses":{"200":{"description":"Broadcast"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"patch":{"tags":["notifications"],"summary":"Update a draft broadcast","description":"Runs the broadcast.update capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_notifications_by_id","responses":{"200":{"description":"Updated"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"content":{"type":"object","description":"Optional static, display-only SDL detail. Keep body as the plain-text fallback.","properties":{"kind":{"type":"string","enum":["sdl"]},"document":{"type":"object"}},"required":["kind","document"]},"recipientSubjects":{"type":"array","items":{"type":"string"}},"actions":{"type":"array","items":{"type":"object"}}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]},"delete":{"tags":["notifications"],"summary":"Delete a draft notification broadcast","description":"Permanently deletes a draft. Sent broadcasts cannot be deleted. Runs the broadcast.delete capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"delete_notifications_by_id","responses":{"200":{"description":"Draft deleted"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/notifications/{id}/send":{"patch":{"tags":["notifications"],"summary":"Send a draft broadcast","description":"Fans the broadcast out to all recipients and marks it sent. Runs the broadcast.send capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"patch_notifications_by_id_send","responses":{"200":{"description":"Sent; returns recipientCount"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/notifications/users/search":{"get":{"tags":["notifications"],"summary":"Search users for broadcast recipients","description":"Search users by email/name (max 10 results). Returned `subject` values can be used as recipientSubjects. Runs the broadcast.searchUsers capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"get_notifications_users_search","responses":{"200":{"description":"Matching users"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/notifications/users/by-subjects":{"post":{"tags":["notifications"],"summary":"Resolve a list of subjects to {subject,email,name}","description":"Runs the broadcast.usersBySubjects capability through the same dispatch as POST /api/v2/platform/<kind>/<capability>; refusals answer with the platform statuses.","operationId":"post_notifications_users_by_subjects","responses":{"200":{"description":"Resolved users"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subjects"],"properties":{"subjects":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/health":{"get":{"tags":["embeddings"],"summary":"Embedding health for a namespace","description":"Embedding health for a namespace","operationId":"get_embeddings_health","responses":{"200":{"description":"Embedding health summary"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/docs":{"get":{"tags":["embeddings"],"summary":"List indexed + unindexed docs","description":"List indexed + unindexed docs","operationId":"get_embeddings_docs","responses":{"200":{"description":"Indexed + unindexed doc lists"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/active-task":{"get":{"tags":["embeddings"],"summary":"Active embedding task for a namespace","description":"Active embedding task for a namespace","operationId":"get_embeddings_active_task","responses":{"200":{"description":"Active task or null"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/chunks/{kvId}":{"get":{"tags":["embeddings"],"summary":"Embedded chunks for a KV doc","description":"Embedded chunks for a KV doc","operationId":"get_embeddings_chunks_by_kvId","responses":{"200":{"description":"Per-chunk text + model"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"kvId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/transcript/{videoId}":{"get":{"tags":["embeddings"],"summary":"Video transcript + smart actions","description":"Video transcript + smart actions","operationId":"get_embeddings_transcript_by_videoId","responses":{"200":{"description":"Transcript + smart actions + status"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"videoId","in":"path","required":true,"description":"Video asset id for the video-only path adapter. Audio requests supply mediaKind and mediaId explicitly.","schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/search":{"post":{"tags":["embeddings"],"summary":"Semantic (vector) search","description":"Semantic (vector) search","operationId":"post_embeddings_search","responses":{"200":{"description":"Scored, deduped results"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","query"],"properties":{"namespace":{"type":"string"},"query":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":20}}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/generate":{"post":{"tags":["embeddings"],"summary":"Trigger embedding generation","description":"Trigger embedding generation\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_embeddings_generate","responses":{"200":{"description":"started | already_running with taskId"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace"],"properties":{"namespace":{"type":"string"},"forceReEmbed":{"type":"boolean"}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/transcript/{videoId}/requeue":{"post":{"tags":["embeddings"],"summary":"Re-queue video transcription (fresh STT)","description":"Re-queue video transcription (fresh STT)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_embeddings_transcript_by_videoId_requeue","responses":{"200":{"description":"Queued"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"videoId","in":"path","required":true,"description":"Video asset id for the video-only path adapter. Audio requests supply mediaKind and mediaId explicitly.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/transcript/{videoId}/requeue-smart":{"post":{"tags":["embeddings"],"summary":"Re-queue video smart actions (no re-STT)","description":"Re-queue video smart actions (no re-STT)\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_embeddings_transcript_by_videoId_requeue_smart","responses":{"200":{"description":"Queued"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"videoId","in":"path","required":true,"description":"Video asset id for the video-only path adapter. Audio requests supply mediaKind and mediaId explicitly.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/transcript/{videoId}/save-edit":{"post":{"tags":["embeddings"],"summary":"Save a manual transcript edit","description":"Save a manual transcript edit\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_embeddings_transcript_by_videoId_save_edit","responses":{"200":{"description":"Saved"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"videoId","in":"path","required":true,"description":"Video asset id for the video-only path adapter. Audio requests supply mediaKind and mediaId explicitly.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/embeddings/video-transcript-search":{"post":{"tags":["embeddings"],"summary":"Search video transcripts semantically","description":"Search video transcripts semantically","operationId":"post_embeddings_video_transcript_search","responses":{"200":{"description":"Search hits"},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/web/search":{"post":{"tags":["web"],"summary":"Search the web","description":"Returns normalized web results, related queries, optional extracted markdown, and trace metadata. Requires `platform:web-search` in `system`.","operationId":"post_web_search","responses":{"200":{"description":"Normalized web search response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WebSearchResponse"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":400},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Maximum results returned per provider bucket, not across the whole response."},"page":{"type":"integer","minimum":1,"maximum":10},"safeSearch":{"type":"boolean"},"lensId":{"type":"string"},"filters":{"type":"object","properties":{"region":{"type":"string","description":"ISO 3166-1 alpha-2 country code."},"after":{"type":"string","description":"Return pages published or updated after this date."},"before":{"type":"string","description":"Return pages published or updated before this date."}},"additionalProperties":false},"lens":{"type":"object","properties":{"sitesIncluded":{"type":"array","maxItems":10,"items":{"type":"string"}},"sitesExcluded":{"type":"array","maxItems":10,"items":{"type":"string"}},"keywordsIncluded":{"type":"array","maxItems":5,"items":{"type":"string"}},"keywordsExcluded":{"type":"array","maxItems":5,"items":{"type":"string"}},"fileType":{"type":"string"},"timeAfter":{"type":"string"},"timeBefore":{"type":"string"},"timeRelative":{"type":"string"},"searchRegion":{"type":"string"}},"additionalProperties":false},"extract":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":5},"timeout":{"type":"number","exclusiveMinimum":0,"maximum":30}},"required":["count"],"additionalProperties":false}},"required":["query"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/web/extract":{"post":{"tags":["web"],"summary":"Extract web pages as markdown","description":"Returns bounded markdown or a page-specific error for each provider result, plus trace metadata. Requires `platform:web-search` in `system`.","operationId":"post_web_extract","responses":{"200":{"description":"Normalized page extraction response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WebExtractResponse"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri","pattern":"^https://"}}},"required":["urls"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/workflows/definitions":{"get":{"tags":["workflows"],"summary":"List workflow definitions","description":"List immutable workflow definition summaries in a namespace. Requires `read:workflow_definitions`. Runs the workflow.listDefinitions capability, through the same dispatch as POST /api/v2/platform/page/workflow.listDefinitions; refusals answer with the platform statuses.","operationId":"get_workflows_definitions","responses":{"200":{"description":"Paginated workflow definition summaries","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowDefinitionSummary"}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string"},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"query","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/workflows/definitions/{key}/revisions/{revision}":{"get":{"tags":["workflows"],"summary":"Get a workflow revision","description":"Get one immutable, executable workflow revision. Requires `read:workflow_definitions`.","operationId":"get_workflows_definitions_by_key_revisions_by_revision","responses":{"200":{"description":"Workflow revision","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WorkflowDefinitionRevision"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"revision","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"namespace","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/workflows/definitions/{key}/revisions":{"post":{"tags":["workflows"],"summary":"Publish a workflow revision","description":"Compile and publish a new immutable revision. The definition key must match the path key. Requires `manage:workflow_definitions`.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_workflows_definitions_by_key_revisions","responses":{"201":{"description":"Published revision identifiers","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["definitionId","revisionId","revision"],"properties":{"definitionId":{"type":"string"},"revisionId":{"type":"string"},"revision":{"type":"integer","minimum":1}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","definition"],"properties":{"namespace":{"type":"string"},"definition":{"$ref":"#/components/schemas/WorkflowDefinition"},"displayName":{"type":"string"},"description":{"type":"string"},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"default":30},"expectedLatestRevision":{"type":"integer","minimum":0,"description":"Optimistic concurrency guard. Use 0 when creating a definition."}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/workflows/runs":{"get":{"tags":["workflows"],"summary":"List workflow runs","description":"List runs in a namespace, optionally filtered by workflow key and lifecycle status. Requires `read:workflow_runs`. Runs the workflow.listRuns capability, through the same dispatch as POST /api/v2/platform/page/workflow.listRuns; refusals answer with the platform statuses.","operationId":"get_workflows_runs","responses":{"200":{"description":"Paginated workflow runs","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRun"}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string"},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"namespace","in":"query","required":true,"schema":{"type":"string"}},{"name":"workflowKey","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["queued","running","waiting","completed","failed","canceled"]}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["workflows"],"summary":"Start a workflow run","description":"Start an asynchronous run pinned to a published revision. Returns 200 when an idempotency key reuses an existing run, otherwise 201. Requires `create:workflow_runs`.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_workflows_runs","responses":{"200":{"description":"Existing idempotent run reused","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["run","reused"],"properties":{"run":{"$ref":"#/components/schemas/WorkflowRun"},"reused":{"type":"boolean"}}}}}}}},"201":{"description":"Workflow run started","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["run","reused"],"properties":{"run":{"$ref":"#/components/schemas/WorkflowRun"},"reused":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","workflowKey","initialArtifact"],"properties":{"namespace":{"type":"string"},"workflowKey":{"type":"string"},"revision":{"type":"integer","minimum":1,"description":"Omit to use the latest published revision."},"initialArtifact":{"$ref":"#/components/schemas/WorkflowTextArtifactInput"},"idempotencyKey":{"type":"string","maxLength":256}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/workflows/runs/{runId}":{"get":{"tags":["workflows"],"summary":"Get a workflow run","description":"Get current state for one workflow run. Requires `read:workflow_runs`.","operationId":"get_workflows_runs_by_runId","responses":{"200":{"description":"Workflow run","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WorkflowRun"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/workflows/runs/{runId}/events":{"get":{"tags":["workflows"],"summary":"List workflow run events","description":"List the durable event timeline for a run. Requires `read:workflow_runs`; a run that does not exist or that the caller cannot read answers 404. Runs the workflow.listRunEvents capability, through the same dispatch as POST /api/v2/platform/page/workflow.listRunEvents; refusals answer with the platform statuses.","operationId":"get_workflows_runs_by_runId_events","responses":{"200":{"description":"Paginated workflow run events","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunEvent"}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string"},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]},"post":{"tags":["workflows"],"summary":"Send an event to a workflow run","description":"Resume a declared wait node with an immutable text artifact. Returns 200 when the idempotency key reuses an existing event, otherwise 201. Requires `send:workflow_events`.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_workflows_runs_by_runId_events","responses":{"200":{"description":"Existing idempotent event reused","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["event","reused"],"properties":{"event":{"$ref":"#/components/schemas/WorkflowRunEvent"},"reused":{"type":"boolean"}}}}}}}},"201":{"description":"Workflow event delivered","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["event","reused"],"properties":{"event":{"$ref":"#/components/schemas/WorkflowRunEvent"},"reused":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nodeId","eventName","artifact","idempotencyKey"],"properties":{"nodeId":{"type":"string"},"eventName":{"type":"string"},"artifact":{"$ref":"#/components/schemas/WorkflowTextArtifactInput"},"idempotencyKey":{"type":"string","minLength":1,"maxLength":256}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/workflows/runs/{runId}/artifacts":{"get":{"tags":["workflows"],"summary":"List workflow run artifacts","description":"List artifact metadata for a workflow run without payloads. Requires `read:workflow_artifacts`.","operationId":"get_workflows_runs_by_runId_artifacts","responses":{"200":{"description":"Paginated workflow artifact metadata","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowArtifactSummary"}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string"},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque pagination cursor."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v1/workflows/runs/{runId}/cancel":{"post":{"tags":["workflows"],"summary":"Cancel a workflow run","description":"Cancel a non-terminal workflow run. Cancellation is cooperative for actions already in flight. Requires `manage:workflow_runs`.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_workflows_runs_by_runId_cancel","responses":{"200":{"description":"Canceled workflow run","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WorkflowRun"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/workflows/runs/{runId}/restart":{"post":{"tags":["workflows"],"summary":"Restart a workflow run from a parallel boundary","description":"Restart a failed run from a parallel node declared by its pinned revision. A required idempotency key makes retries safe; `reused` reports whether the prior restart was returned. Arbitrary component step names are rejected. Requires `manage:workflow_runs`.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_workflows_runs_by_runId_restart","responses":{"200":{"description":"New or reused idempotent workflow restart","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["run","reused"],"properties":{"run":{"$ref":"#/components/schemas/WorkflowRun"},"reused":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["parallelNodeId","idempotencyKey"],"properties":{"parallelNodeId":{"type":"string"},"idempotencyKey":{"type":"string","minLength":1,"maxLength":256}}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v1/workflows/artifacts/{artifactId}":{"get":{"tags":["workflows"],"summary":"Get a workflow artifact","description":"Get artifact metadata and the immutable text payload. The core bounds payload size to 256 KiB. Requires `read:workflow_artifacts`.","operationId":"get_workflows_artifacts_by_artifactId","responses":{"200":{"description":"Workflow artifact and text payload","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WorkflowArtifactResult"}}}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"artifactId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/apply_column_transition":{"post":{"tags":["kvark-v2"],"summary":"Apply a current-column transition to move and retag one caller-owned Kvark item.","description":"Apply a current-column transition to move and retag one caller-owned Kvark item.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_apply_column_transition","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"placement":{"type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","boardId","columnId","order","createdAt","updatedAt"],"additionalProperties":false},"tags":{"type":"array","items":{"type":"string"}}},"required":["placement","tags"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"boardId":{"type":"string","minLength":1,"maxLength":128},"itemId":{"type":"string","minLength":1,"maxLength":128},"transitionId":{"type":"string","minLength":1,"maxLength":64},"expectedPlacementUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["boardId","itemId","transitionId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/archive_automation_task":{"post":{"tags":["kvark-v2"],"summary":"Archive one caller-owned Kvark task without deleting its Action, body, or Placements.","description":"Archive one caller-owned Kvark task without deleting its Action, body, or Placements.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_archive_automation_task","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"titled":{"type":"boolean"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"bodyReadable":{"type":"boolean"},"body":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"order":{"type":"number"},"archived":{"type":"boolean"},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"taskId":{"type":"string","minLength":1,"maxLength":128}},"required":["taskId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/archive_board":{"post":{"tags":["kvark-v2"],"summary":"Archive a caller-owned Kvark Board while preserving its stable structural records.","description":"Archive a caller-owned Kvark Board while preserving its stable structural records.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_archive_board","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"boardId":{"type":"string","minLength":1,"maxLength":128},"expectedVersions":{"type":"object","properties":{"boardUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"placementUpdatedAts":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":128},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"required":["boardUpdatedAt","placementUpdatedAts"],"additionalProperties":false}},"required":["boardId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/backfill_automation_task_projections":{"post":{"tags":["kvark-v2"],"summary":"Rebuild caller-owned task projections and remove stale rows in bounded batches. Pass restart: true to repair a completed backfill. In-progress repairs always resume; stop when complete.","description":"Rebuild caller-owned task projections and remove stale rows in bounded batches. Pass restart: true to repair a completed backfill. In-progress repairs always resume; stop when complete.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_backfill_automation_task_projections","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"complete":{"type":"boolean"},"processed":{"type":"integer","minimum":0,"maximum":9007199254740991},"totalProcessed":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["complete","processed","totalProcessed"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"batchSize":{"type":"integer","minimum":1,"maximum":50},"restart":{"description":"Restart a completed backfill. In-progress repairs always resume, even when true. Stop when complete.","type":"boolean"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/backfill_feed_index":{"post":{"tags":["kvark-v2"],"summary":"Build the caller-owned chronological feed index in bounded, resumable, idempotent batches.","description":"Build the caller-owned chronological feed index in bounded, resumable, idempotent batches.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_backfill_feed_index","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"complete":{"type":"boolean"},"processed":{"type":"integer","minimum":0,"maximum":9007199254740991},"totalProcessed":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["complete","processed","totalProcessed"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"batchSize":{"type":"integer","minimum":1,"maximum":50}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/capture_entry":{"post":{"tags":["kvark-v2"],"summary":"Capture one entry with a Journal or Canvas part, a legacy Journal plus Canvas pair, or a Journal plus ordered inline Canvases, using duplicate-safe delivery. Private and sealed modes accept ciphertext only; sealed capture remains Journal-only. Server-readable mode explicitly stores plaintext for authorized automation. Reuse the capture ID and identical content when retrying. Owner must match the authenticated caller.","description":"Capture one entry with a Journal or Canvas part, a legacy Journal plus Canvas pair, or a Journal plus ordered inline Canvases, using duplicate-safe delivery. Private and sealed modes accept ciphertext only; sealed capture remains Journal-only. Server-readable mode explicitly stores plaintext for authorized automation. Reuse the capture ID and identical content when retrying. Owner must match the authenticated caller.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_capture_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"captureId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ownerSubject":{"type":"string","minLength":1,"maxLength":256},"content":{"anyOf":[{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"private"},"kind":{"type":"string","const":"journal"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"canvas":{"type":"object","properties":{"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256}},"required":["encryptedContent","iv"],"additionalProperties":false},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false}},"required":["mode","kind","encryptedContent","iv","dekEnvelope"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"private"},"kind":{"type":"string","const":"journal"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"inlineCanvases":{"minItems":1,"maxItems":64,"type":"array","items":{"type":"object","properties":{"blockId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256}},"required":["blockId","encryptedContent","iv"],"additionalProperties":false}},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false}},"required":["mode","kind","encryptedContent","iv","inlineCanvases","dekEnvelope"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"private"},"kind":{"type":"string","const":"canvas"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false}},"required":["mode","kind","encryptedContent","iv","dekEnvelope"],"additionalProperties":false}]},{"type":"object","properties":{"mode":{"type":"string","const":"sealed"},"kind":{"type":"string","const":"journal"},"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false}},"required":["mode","kind","encryptedContent","iv","sealedDek"],"additionalProperties":false},{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"server-readable"},"kind":{"type":"string","const":"journal"},"plainBody":{"type":"string","minLength":1,"maxLength":750000},"canvas":{"type":"object","properties":{"plainBody":{"type":"string","minLength":1,"maxLength":750000}},"required":["plainBody"],"additionalProperties":false}},"required":["mode","kind","plainBody"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"server-readable"},"kind":{"type":"string","const":"journal"},"plainBody":{"type":"string","minLength":1,"maxLength":750000},"inlineCanvases":{"minItems":1,"maxItems":64,"type":"array","items":{"type":"object","properties":{"blockId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"plainBody":{"type":"string","minLength":1,"maxLength":750000}},"required":["blockId","plainBody"],"additionalProperties":false}}},"required":["mode","kind","plainBody","inlineCanvases"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"server-readable"},"kind":{"type":"string","const":"canvas"},"plainBody":{"type":"string","minLength":1,"maxLength":750000}},"required":["mode","kind","plainBody"],"additionalProperties":false}]}]}},"required":["captureId","ownerSubject","content"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/complete_automation_task":{"post":{"tags":["kvark-v2"],"summary":"Complete a task through its Action and Placement; recurring tasks advance and return to the entry column.","description":"Complete a task through its Action and Placement; recurring tasks advance and return to the entry column.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_complete_automation_task","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"titled":{"type":"boolean"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"bodyReadable":{"type":"boolean"},"body":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"order":{"type":"number"},"archived":{"type":"boolean"},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"taskId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128}},"required":["taskId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/complete_item":{"post":{"tags":["kvark-v2"],"summary":"Complete an Item Action, advancing recurrence independently of its Item kind or column label.","description":"Complete an Item Action, advancing recurrence independently of its Item kind or column label.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_complete_item","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"number"},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"number"},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"completedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"now":{"type":"integer","minimum":0,"maximum":9007199254740991},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expectedPlacementUpdatedAts":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":128},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"required":["itemId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/create_automation_task":{"post":{"tags":["kvark-v2"],"summary":"Create a caller-owned Kvark task. Automation plaintext is stored only when visibility is server-readable.","description":"Create a caller-owned Kvark task. Automation plaintext is stored only when visibility is server-readable.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_create_automation_task","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"titled":{"type":"boolean"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"bodyReadable":{"type":"boolean"},"body":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"order":{"type":"number"},"archived":{"type":"boolean"},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"body":{"type":"string","maxLength":750000},"description":{"type":"string","maxLength":750000},"tags":{"maxItems":64,"type":"array","items":{"type":"string","maxLength":120}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200},"boardId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"channel":{"type":"string","const":"notification"}},"required":["remindAt"],"additionalProperties":false}},"required":["title"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/create_block":{"post":{"tags":["kvark-v2"],"summary":"Append or insert one block into a caller-owned Kvark Nukleon. Journal and Canvas blocks may use a fresh caller-supplied block ID; only an empty inline Canvas adopts an existing matching block on retry.","description":"Append or insert one block into a caller-owned Kvark Nukleon. Journal and Canvas blocks may use a fresh caller-supplied block ID; only an empty inline Canvas adopts an existing matching block on retry.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_create_block","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"block":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"journal"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"canvas"},"placement":{"type":"string","const":"inline"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"list"},"childNukleonId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"renderStyle":{"default":"checklist","type":"string","enum":["checklist","board"]}},"required":["id","nukleonId","order","createdAt","updatedAt","kind","childNukleonId","renderStyle"],"additionalProperties":false}]},"content":{"type":"object","properties":{"encryptedContent":{"type":"string"},"iv":{"type":"string"},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false},"plainBody":{"type":"string"},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["encryptedContent","iv","updatedAt"],"additionalProperties":false}},"required":["block"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"kind":{"type":"string","enum":["journal","canvas"]},"blockId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"placement":{"type":"string","const":"inline"},"afterBlockId":{"type":"string","minLength":1,"maxLength":128},"beforeBlockId":{"type":"string","minLength":1,"maxLength":128},"initialContent":{"type":"object","properties":{"encryptedContent":{"type":"string","maxLength":750000},"iv":{"type":"string","maxLength":256},"plainBody":{"type":"string","maxLength":750000}},"required":["encryptedContent","iv"],"additionalProperties":false}},"required":["nukleonId","kind"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/create_board_with_columns":{"post":{"tags":["kvark-v2"],"summary":"Create one caller-owned Kvark Board and its ordered columns atomically.","description":"Create one caller-owned Kvark Board and its ordered columns atomically.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_create_board_with_columns","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"board":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"entryColumnId":{"type":"string","minLength":1,"maxLength":128},"terminalColumnId":{"type":"string","minLength":1,"maxLength":128},"defaultVisibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"ownerNukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","name","entryColumnId","order","archived","createdAt","updatedAt"],"additionalProperties":false},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":200},"tone":{"type":"string","enum":["default","positive","warning","info"]},"transitions":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"label":{"type":"string","minLength":1,"maxLength":40},"tone":{"type":"string","enum":["default","positive","warning","info"]},"toColumnId":{"type":"string","minLength":1,"maxLength":128},"addTags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"clearTags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}}},"required":["id","label","toColumnId"],"additionalProperties":false}},"notifyOnEnter":{"type":"boolean"},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","boardId","name","tone","order","archived","createdAt","updatedAt"],"additionalProperties":false}}},"required":["board","columns"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"defaultVisibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"columns":{"minItems":2,"maxItems":24,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"tone":{"type":"string","enum":["default","positive","warning","info"]}},"required":["name","tone"],"additionalProperties":false}},"entryColumnIndex":{"type":"integer","minimum":0,"maximum":9007199254740991},"terminalColumnIndex":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["name","columns","entryColumnIndex","terminalColumnIndex"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/create_nukleon":{"post":{"tags":["kvark-v2"],"summary":"Create one Kvark Nukleon identity and an optional first content quark atomically; zero-knowledge content remains encrypted and opaque.","description":"Create one Kvark Nukleon identity and an optional first content quark atomically; zero-knowledge content remains encrypted and opaque.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_create_nukleon","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["note","task","drawing"]},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"everServerReadable":{"type":"boolean"},"vaultId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"boostedUntil":{"type":"number"},"combinePending":{"type":"object","properties":{"sourceIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"startedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sourceIds","startedAt","expiresAt"],"additionalProperties":false},"boardId":{"type":"string","minLength":1,"maxLength":128},"trashedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"purgeAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","tags","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","maxLength":500},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"tags":{"maxItems":64,"type":"array","items":{"type":"string","maxLength":120}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"initialContent":{"type":"object","properties":{"kind":{"type":"string","enum":["journal","canvas"]},"encryptedContent":{"type":"string","maxLength":750000},"iv":{"type":"string","maxLength":256},"plainBody":{"type":"string","maxLength":750000}},"required":["kind","encryptedContent","iv"],"additionalProperties":false}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/create_sealed_capture":{"post":{"tags":["kvark-v2"],"summary":"Create one untitled sealed deposit from caller-sealed ciphertext and sealedDek. Seal locally with `furnace kvark sealed-deposit`; plaintext never crosses the wire. The deposit reveals only its existence, createdAt, and sealed flag, and no API surface can read its body until the vault owner unlocks.","description":"Create one untitled sealed deposit from caller-sealed ciphertext and sealedDek. Seal locally with `furnace kvark sealed-deposit`; plaintext never crosses the wire. The deposit reveals only its existence, createdAt, and sealed flag, and no API surface can read its body until the vault owner unlocks.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_create_sealed_capture","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"identity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["note","task","drawing"]},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"everServerReadable":{"type":"boolean"},"vaultId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"boostedUntil":{"type":"number"},"combinePending":{"type":"object","properties":{"sourceIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"startedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sourceIds","startedAt","expiresAt"],"additionalProperties":false},"boardId":{"type":"string","minLength":1,"maxLength":128},"trashedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"purgeAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","tags","archived","createdAt","updatedAt"],"additionalProperties":false},"block":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"journal"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"canvas"},"placement":{"type":"string","const":"inline"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"list"},"childNukleonId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"renderStyle":{"default":"checklist","type":"string","enum":["checklist","board"]}},"required":["id","nukleonId","order","createdAt","updatedAt","kind","childNukleonId","renderStyle"],"additionalProperties":false}]},"content":{"type":"object","properties":{"encryptedContent":{"type":"string"},"iv":{"type":"string"},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false},"plainBody":{"type":"string"},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["encryptedContent","iv","updatedAt"],"additionalProperties":false}},"required":["identity","block","content"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"encryptedContent":{"type":"string","minLength":1,"maxLength":750000},"iv":{"type":"string","minLength":1,"maxLength":256},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false}},"required":["encryptedContent","iv","sealedDek"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/delete_automation_task":{"post":{"tags":["kvark-v2"],"summary":"Permanently delete one caller-owned Kvark task aggregate. Archive when recovery is required.","description":"Permanently delete one caller-owned Kvark task aggregate. Archive when recovery is required.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_delete_automation_task","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"taskId":{"type":"string","minLength":1,"maxLength":128}},"required":["taskId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/delete_nukleon":{"post":{"tags":["kvark-v2"],"summary":"Move one caller-owned Kvark Nukleon to recoverable Trash for 30 days.","description":"Move one caller-owned Kvark Nukleon to recoverable Trash for 30 days.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_delete_nukleon","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128}},"required":["nukleonId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/download_server_readable_attachment_chunk":{"post":{"tags":["kvark-v2"],"summary":"REST-only download of one bounded chunk from a caller-owned attachment. Server-readable attachments only; zero-knowledge attachments are reported as not found.","description":"REST-only download of one bounded chunk from a caller-owned attachment. Server-readable attachments only; zero-knowledge attachments are reported as not found.","operationId":"post_api_v2_kvark_read_download_server_readable_attachment_chunk","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"string","maxLength":699052},"chunkCount":{"type":"integer","exclusiveMinimum":0,"maximum":32}},"required":["data","chunkCount"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"attachmentId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"chunkIndex":{"type":"integer","minimum":0,"maximum":31}},"required":["itemId","attachmentId","chunkIndex"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/get_automation_task":{"post":{"tags":["kvark-v2"],"summary":"Get one caller-owned Kvark task. A zero-knowledge task returns no body.","description":"Get one caller-owned Kvark task. A zero-knowledge task returns no body.","operationId":"post_api_v2_kvark_read_get_automation_task","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"titled":{"type":"boolean"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"bodyReadable":{"type":"boolean"},"body":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"order":{"type":"number"},"archived":{"type":"boolean"},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"taskId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128}},"required":["taskId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/get_block_content":{"post":{"tags":["kvark-v2"],"summary":"Read one caller-owned notebook block: encrypted ciphertext for zero-knowledge items, plaintext only for server-readable items.","description":"Read one caller-owned notebook block: encrypted ciphertext for zero-knowledge items, plaintext only for server-readable items.","operationId":"post_api_v2_kvark_read_get_block_content","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"encryptedContent":{"type":"string"},"iv":{"type":"string"},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false},"plainBody":{"type":"string"},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["encryptedContent","iv","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"blockId":{"type":"string","minLength":1,"maxLength":128}},"required":["nukleonId","blockId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/get_block_contents":{"post":{"tags":["kvark-v2"],"summary":"Read up to 200 caller-owned block content rows by notebook and block reference; zero-knowledge ciphertext stays opaque.","description":"Read up to 200 caller-owned block content rows by notebook and block reference; zero-knowledge ciphertext stays opaque.","operationId":"post_api_v2_kvark_read_get_block_contents","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"encryptedContent":{"type":"string"},"iv":{"type":"string"},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false},"plainBody":{"type":"string"},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"blockId":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128}},"required":["encryptedContent","iv","updatedAt","blockId","nukleonId"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"refs":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"blockId":{"type":"string","minLength":1,"maxLength":128}},"required":["nukleonId","blockId"],"additionalProperties":false}}},"required":["refs"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/get_capture_public_bundle":{"post":{"tags":["kvark-v2"],"summary":"Return the caller's sealed-deposit public bundle, or null until the vault owner unlocks Kvark once. Bodies cross the wire only as ciphertext; seal locally with `furnace kvark sealed-deposit`. A deposit reveals only its existence, createdAt, and sealed flag, and no API surface can read its body until the vault owner unlocks.","description":"Return the caller's sealed-deposit public bundle, or null until the vault owner unlocks Kvark once. Bodies cross the wire only as ciphertext; seal locally with `furnace kvark sealed-deposit`. A deposit reveals only its existence, createdAt, and sealed flag, and no API surface can read its body until the vault owner unlocks.","operationId":"post_api_v2_kvark_read_get_capture_public_bundle","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"x25519":{"type":"string","minLength":1,"maxLength":256},"mlkem":{"type":"string","minLength":1,"maxLength":4096}},"required":["x25519","mlkem"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/get_nukleon":{"post":{"tags":["kvark-v2"],"summary":"Read one caller-owned body-free Kvark Nukleon identity; encrypted content remains available only through content-quark operations.","description":"Read one caller-owned body-free Kvark Nukleon identity; encrypted content remains available only through content-quark operations.","operationId":"post_api_v2_kvark_read_get_nukleon","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["note","task","drawing"]},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"everServerReadable":{"type":"boolean"},"vaultId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"boostedUntil":{"type":"number"},"combinePending":{"type":"object","properties":{"sourceIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"startedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sourceIds","startedAt","expiresAt"],"additionalProperties":false},"boardId":{"type":"string","minLength":1,"maxLength":128},"trashedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"purgeAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","tags","archived","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128}},"required":["nukleonId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_actions":{"post":{"tags":["kvark-v2"],"summary":"List caller-owned Item Action facets.","description":"List caller-owned Item Action facets.","operationId":"post_api_v2_kvark_read_list_actions","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"number"},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"number"},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"completedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_attachments":{"post":{"tags":["kvark-v2"],"summary":"List attachment metadata for one caller-owned available Kvark item. Zero-knowledge attachment bytes remain opaque.","description":"List attachment metadata for one caller-owned available Kvark item. Zero-knowledge attachment bytes remain opaque.","operationId":"post_api_v2_kvark_read_list_attachments","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"itemId":{"type":"string","minLength":1,"maxLength":128},"filename":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"type":"string","minLength":1,"maxLength":255},"size":{"type":"integer","minimum":0,"maximum":9007199254740991},"durationMs":{"type":"number","minimum":0},"protection":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"server-readable"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"zero-knowledge"},"algorithm":{"type":"string","const":"AES-GCM"},"iv":{"type":"string","minLength":1,"maxLength":256},"itemDekVersion":{"type":"number","const":1}},"required":["mode","algorithm","iv","itemDekVersion"],"additionalProperties":false}]},"status":{"type":"string","enum":["pending","ready","deleting"]},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"uploadedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"storedSize":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","itemId","filename","mimeType","size","protection","status","createdAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128}},"required":["itemId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_automation_task_tags":{"post":{"tags":["kvark-v2"],"summary":"List tags from one bounded projection scan. Pages may repeat a tag; callers should union tags while following nextCursor and restart if tasks change.","description":"List tags from one bounded projection scan. Pages may repeat a tag; callers should union tags while following nextCursor and restart if tasks change.","operationId":"post_api_v2_kvark_read_list_automation_task_tags","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["tags","hasMore","nextCursor"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cursor":{"type":"string","maxLength":32768,"pattern":"^[A-Za-z0-9_-]+$"},"scanLimit":{"type":"integer","minimum":1,"maximum":200}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_automation_tasks":{"post":{"tags":["kvark-v2"],"summary":"List caller-owned Kvark task projections with bounded keyset paging, tag and due filters. Cursors fail closed if tasks change between pages. Zero-knowledge bodies remain opaque.","description":"List caller-owned Kvark task projections with bounded keyset paging, tag and due filters. Cursors fail closed if tasks change between pages. Zero-knowledge bodies remain opaque.","operationId":"post_api_v2_kvark_read_list_automation_tasks","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"titled":{"type":"boolean"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"bodyReadable":{"type":"boolean"},"body":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"order":{"type":"number"},"archived":{"type":"boolean"},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"additionalProperties":false}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["tasks","hasMore","nextCursor"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"columnId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"tags":{"maxItems":64,"type":"array","items":{"type":"string","maxLength":120}},"archived":{"type":"boolean"},"dueBefore":{"type":"integer","minimum":0,"maximum":9007199254740991},"dueAfter":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":1,"maximum":200},"cursor":{"type":"string","maxLength":32768,"pattern":"^[A-Za-z0-9_-]+$"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_block_contents":{"post":{"tags":["kvark-v2"],"summary":"List every block content row in one caller-owned Nukleon: encrypted ciphertext or explicitly server-readable plaintext.","description":"List every block content row in one caller-owned Nukleon: encrypted ciphertext or explicitly server-readable plaintext.","operationId":"post_api_v2_kvark_read_list_block_contents","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"encryptedContent":{"type":"string"},"iv":{"type":"string"},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false},"plainBody":{"type":"string"},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"blockId":{"type":"string","minLength":1,"maxLength":128}},"required":["encryptedContent","iv","updatedAt","blockId"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128}},"required":["nukleonId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_blocks":{"post":{"tags":["kvark-v2"],"summary":"List the ordered blocks one caller-owned Kvark Nukleon is composed of.","description":"List the ordered blocks one caller-owned Kvark Nukleon is composed of.","operationId":"post_api_v2_kvark_read_list_blocks","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"journal"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"canvas"},"placement":{"type":"string","const":"inline"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"list"},"childNukleonId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"renderStyle":{"default":"checklist","type":"string","enum":["checklist","board"]}},"required":["id","nukleonId","order","createdAt","updatedAt","kind","childNukleonId","renderStyle"],"additionalProperties":false}]}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128}},"required":["nukleonId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_board_columns":{"post":{"tags":["kvark-v2"],"summary":"List one caller-owned Kvark Board’s columns in stored order.","description":"List one caller-owned Kvark Board’s columns in stored order.","operationId":"post_api_v2_kvark_read_list_board_columns","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":200},"tone":{"type":"string","enum":["default","positive","warning","info"]},"transitions":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"label":{"type":"string","minLength":1,"maxLength":40},"tone":{"type":"string","enum":["default","positive","warning","info"]},"toColumnId":{"type":"string","minLength":1,"maxLength":128},"addTags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"clearTags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}}},"required":["id","label","toColumnId"],"additionalProperties":false}},"notifyOnEnter":{"type":"boolean"},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","boardId","name","tone","order","archived","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"boardId":{"type":"string","minLength":1,"maxLength":128}},"required":["boardId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_board_placements":{"post":{"tags":["kvark-v2"],"summary":"List caller-owned placements for one Kvark Board.","description":"List caller-owned placements for one Kvark Board.","operationId":"post_api_v2_kvark_read_list_board_placements","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","boardId","columnId","order","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"boardId":{"type":"string","minLength":1,"maxLength":128}},"required":["boardId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_boards":{"post":{"tags":["kvark-v2"],"summary":"List caller-owned Kvark Boards in stored order.","description":"List caller-owned Kvark Boards in stored order.","operationId":"post_api_v2_kvark_read_list_boards","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"entryColumnId":{"type":"string","minLength":1,"maxLength":128},"terminalColumnId":{"type":"string","minLength":1,"maxLength":128},"defaultVisibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"ownerNukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","name","entryColumnId","order","archived","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_feed":{"post":{"tags":["kvark-v2"],"summary":"List the caller-owned Kvark stream newest-first from immutable creation timestamps. Cursors fail closed when identity state changes.","description":"List the caller-owned Kvark stream newest-first from immutable creation timestamps. Cursors fail closed when identity state changes.","operationId":"post_api_v2_kvark_read_list_feed","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"tags":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"boostedUntil":{"type":"integer","minimum":0,"maximum":9007199254740991},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"boardId":{"type":"string","minLength":1,"maxLength":128},"blockKinds":{"type":"array","items":{"type":"string","enum":["journal","canvas","list"]}}},"required":["id","tags","archived","createdAt","updatedAt","visibility","blockKinds"],"additionalProperties":false}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["entries","hasMore","nextCursor"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"archived":{"type":"boolean"},"before":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","maxLength":8192,"pattern":"^[A-Za-z0-9_-]+$"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_item_placements":{"post":{"tags":["kvark-v2"],"summary":"List every caller-owned placement for one Item, across Boards.","description":"List every caller-owned placement for one Item, across Boards.","operationId":"post_api_v2_kvark_read_list_item_placements","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","boardId","columnId","order","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128}},"required":["itemId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_nukleons":{"post":{"tags":["kvark-v2"],"summary":"List caller-owned body-free Kvark Nukleon identities; encrypted content remains available only through content-quark operations.","description":"List caller-owned body-free Kvark Nukleon identities; encrypted content remains available only through content-quark operations.","operationId":"post_api_v2_kvark_read_list_nukleons","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["note","task","drawing"]},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"everServerReadable":{"type":"boolean"},"vaultId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"boostedUntil":{"type":"number"},"combinePending":{"type":"object","properties":{"sourceIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"startedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sourceIds","startedAt","expiresAt"],"additionalProperties":false},"boardId":{"type":"string","minLength":1,"maxLength":128},"trashedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"purgeAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","tags","archived","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_trashed_nukleons":{"post":{"tags":["kvark-v2"],"summary":"List caller-owned Kvark Nukleons in recoverable Trash, ordered by deletion time.","description":"List caller-owned Kvark Nukleons in recoverable Trash, ordered by deletion time.","operationId":"post_api_v2_kvark_read_list_trashed_nukleons","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["note","task","drawing"]},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"everServerReadable":{"type":"boolean"},"vaultId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"boostedUntil":{"type":"number"},"combinePending":{"type":"object","properties":{"sourceIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"startedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sourceIds","startedAt","expiresAt"],"additionalProperties":false},"boardId":{"type":"string","minLength":1,"maxLength":128},"trashedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"purgeAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","tags","archived","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_vault_block_contents":{"post":{"tags":["kvark-v2"],"summary":"List every caller-owned block representation for client search: encrypted ciphertext stays opaque and server-readable plaintext is explicit.","description":"List every caller-owned block representation for client search: encrypted ciphertext stays opaque and server-readable plaintext is explicit.","operationId":"post_api_v2_kvark_read_list_vault_block_contents","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generation":{"type":"integer","minimum":0,"maximum":9007199254740991},"contents":{"type":"array","items":{"type":"object","properties":{"encryptedContent":{"type":"string"},"iv":{"type":"string"},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false},"plainBody":{"type":"string"},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"blockId":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128}},"required":["encryptedContent","iv","updatedAt","blockId","nukleonId"],"additionalProperties":false}}},"required":["generation","contents"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_vault_blocks":{"post":{"tags":["kvark-v2"],"summary":"List every caller-owned Kvark block in one vault scan, for desk badges and composition previews.","description":"List every caller-owned Kvark block in one vault scan, for desk badges and composition previews.","operationId":"post_api_v2_kvark_read_list_vault_blocks","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"journal"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"canvas"},"placement":{"type":"string","const":"inline"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"list"},"childNukleonId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"renderStyle":{"default":"checklist","type":"string","enum":["checklist","board"]}},"required":["id","nukleonId","order","createdAt","updatedAt","kind","childNukleonId","renderStyle"],"additionalProperties":false}]}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/read/list_vault_content_manifest":{"post":{"tags":["kvark-v2"],"summary":"List caller-owned block content metadata without returning ciphertext or plaintext bodies.","description":"List caller-owned block content metadata without returning ciphertext or plaintext bodies.","operationId":"post_api_v2_kvark_read_list_vault_content_manifest","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generation":{"type":"integer","minimum":0,"maximum":9007199254740991},"entries":{"type":"array","items":{"type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"blockId":{"type":"string","minLength":1,"maxLength":128},"kind":{"type":"string","enum":["journal","canvas"]},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"size":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["nukleonId","blockId","kind","updatedAt","size"],"additionalProperties":false}}},"required":["generation","entries"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/move_automation_task":{"post":{"tags":["kvark-v2"],"summary":"Move a Kvark task through canonical Board Placement state. No hill-chart metadata is read or written.","description":"Move a Kvark task through canonical Board Placement state. No hill-chart metadata is read or written.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_move_automation_task","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"titled":{"type":"boolean"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"bodyReadable":{"type":"boolean"},"body":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"order":{"type":"number"},"archived":{"type":"boolean"},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"taskId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"afterTaskId":{"type":"string","minLength":1,"maxLength":128},"beforeTaskId":{"type":"string","minLength":1,"maxLength":128}},"required":["taskId","status"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/move_block":{"post":{"tags":["kvark-v2"],"summary":"Reorder one caller-owned Kvark block among its siblings without touching its encrypted content.","description":"Reorder one caller-owned Kvark block among its siblings without touching its encrypted content.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_move_block","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"journal"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"canvas"},"placement":{"type":"string","const":"inline"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"list"},"childNukleonId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"renderStyle":{"default":"checklist","type":"string","enum":["checklist","board"]}},"required":["id","nukleonId","order","createdAt","updatedAt","kind","childNukleonId","renderStyle"],"additionalProperties":false}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"blockId":{"type":"string","minLength":1,"maxLength":128},"afterBlockId":{"type":"string","minLength":1,"maxLength":128},"beforeBlockId":{"type":"string","minLength":1,"maxLength":128},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["nukleonId","blockId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/move_item":{"post":{"tags":["kvark-v2"],"summary":"Move one Board placement to an active same-Board column using fractional order.","description":"Move one Board placement to an active same-Board column using fractional order.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_move_item","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","boardId","columnId","order","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"afterItemId":{"type":"string","minLength":1,"maxLength":128},"beforeItemId":{"type":"string","minLength":1,"maxLength":128},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expectedActionUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expectedPlacementUpdatedAts":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":128},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"required":["itemId","boardId","columnId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/place_item":{"post":{"tags":["kvark-v2"],"summary":"Place one caller-owned Item into a Board’s entry column without copying the Item.","description":"Place one caller-owned Item into a Board’s entry column without copying the Item.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_place_item","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","boardId","columnId","order","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128}},"required":["itemId","boardId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/purge_nukleon":{"post":{"tags":["kvark-v2"],"summary":"Permanently purge one caller-owned Kvark Nukleon already in Trash.","description":"Permanently purge one caller-owned Kvark Nukleon already in Trash.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_purge_nukleon","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"complete":{"type":"boolean"}},"required":["ok","complete"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128}},"required":["nukleonId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/put_block_content":{"post":{"tags":["kvark-v2"],"summary":"Create or compare-and-replace one notebook block body in the representation selected by its owner: encrypted ciphertext or server-readable plaintext.","description":"Create or compare-and-replace one notebook block body in the representation selected by its owner: encrypted ciphertext or server-readable plaintext.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_put_block_content","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"encryptedContent":{"type":"string"},"iv":{"type":"string"},"sealedDek":{"type":"object","properties":{"ephX25519":{"type":"string","minLength":1,"maxLength":256},"mlkemCt":{"type":"string","minLength":1,"maxLength":4096},"iv":{"type":"string","minLength":1,"maxLength":256},"wrapped":{"type":"string","minLength":1,"maxLength":512}},"required":["ephX25519","mlkemCt","iv","wrapped"],"additionalProperties":false},"plainBody":{"type":"string"},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["encryptedContent","iv","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"blockId":{"type":"string","minLength":1,"maxLength":128},"encryptedContent":{"type":"string","maxLength":750000},"iv":{"type":"string","maxLength":256},"plainBody":{"type":"string","maxLength":750000},"expectedUpdatedAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["nukleonId","blockId","encryptedContent","iv","expectedUpdatedAt"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/reconfigure_board_columns":{"post":{"tags":["kvark-v2"],"summary":"Reorder, rename, add, archive populated, or delete empty Board columns.","description":"Reorder, rename, add, archive populated, or delete empty Board columns.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_reconfigure_board_columns","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":200},"tone":{"type":"string","enum":["default","positive","warning","info"]},"transitions":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"label":{"type":"string","minLength":1,"maxLength":40},"tone":{"type":"string","enum":["default","positive","warning","info"]},"toColumnId":{"type":"string","minLength":1,"maxLength":128},"addTags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"clearTags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}}},"required":["id","label","toColumnId"],"additionalProperties":false}},"notifyOnEnter":{"type":"boolean"},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","boardId","name","tone","order","archived","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"boardId":{"type":"string","minLength":1,"maxLength":128},"columns":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":200},"tone":{"type":"string","enum":["default","positive","warning","info"]},"transitions":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"label":{"type":"string","minLength":1,"maxLength":40},"tone":{"type":"string","enum":["default","positive","warning","info"]},"toColumnId":{"type":"string","minLength":1,"maxLength":128},"addTags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"clearTags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}}},"required":["id","label","toColumnId"],"additionalProperties":false}},"notifyOnEnter":{"type":"boolean"}},"required":["name","tone"],"additionalProperties":false}},"entryColumnIndex":{"type":"integer","minimum":0,"maximum":9007199254740991},"terminalColumnIndex":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"archiveDestinations":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":128},"additionalProperties":{"type":"string","minLength":1,"maxLength":128}},"expectedVersions":{"type":"object","properties":{"boardUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"columnUpdatedAts":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":128},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}},"placementUpdatedAts":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":128},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"required":["boardUpdatedAt","columnUpdatedAts","placementUpdatedAts"],"additionalProperties":false}},"required":["boardId","columns"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/remove_block":{"post":{"tags":["kvark-v2"],"summary":"Remove one block from a caller-owned Kvark Nukleon, destroying its encrypted content but never its referenced child notebook.","description":"Remove one block from a caller-owned Kvark Nukleon, destroying its encrypted content but never its referenced child notebook.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_remove_block","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"blockId":{"type":"string","minLength":1,"maxLength":128},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["nukleonId","blockId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/remove_item_from_board":{"post":{"tags":["kvark-v2"],"summary":"Remove one placement while preserving the Item and every placement on other Boards.","description":"Remove one placement while preserving the Item and every placement on other Boards.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_remove_item_from_board","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","boardId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/restore_automation_task":{"post":{"tags":["kvark-v2"],"summary":"Restore one caller-owned archived Kvark task.","description":"Restore one caller-owned archived Kvark task.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_restore_automation_task","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"titled":{"type":"boolean"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"bodyReadable":{"type":"boolean"},"body":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"order":{"type":"number"},"archived":{"type":"boolean"},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"taskId":{"type":"string","minLength":1,"maxLength":128}},"required":["taskId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/restore_nukleon":{"post":{"tags":["kvark-v2"],"summary":"Restore one caller-owned Kvark Nukleon from Trash before its retention deadline.","description":"Restore one caller-owned Kvark Nukleon from Trash before its retention deadline.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_restore_nukleon","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["note","task","drawing"]},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"everServerReadable":{"type":"boolean"},"vaultId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"boostedUntil":{"type":"number"},"combinePending":{"type":"object","properties":{"sourceIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"startedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sourceIds","startedAt","expiresAt"],"additionalProperties":false},"boardId":{"type":"string","minLength":1,"maxLength":128},"trashedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"purgeAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","tags","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128}},"required":["nukleonId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/update_action":{"post":{"tags":["kvark-v2"],"summary":"Create or update one Item’s due date and reminder through the Action facet.","description":"Create or update one Item’s due date and reminder through the Action facet.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_update_action","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"number"},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"number"},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"completedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":128},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"number"},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"channel":{"type":"string","const":"notification"}},"required":["remindAt"],"additionalProperties":false},"clearDueAt":{"type":"boolean"},"clearReminder":{"type":"boolean"},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["itemId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/update_automation_task":{"post":{"tags":["kvark-v2"],"summary":"Patch task metadata and Action fields. Body writes are accepted only for explicitly server-readable tasks.","description":"Patch task metadata and Action fields. Body writes are accepted only for explicitly server-readable tasks.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_update_automation_task","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"titled":{"type":"boolean"},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"bodyReadable":{"type":"boolean"},"body":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"boardId":{"type":"string","minLength":1,"maxLength":128},"columnId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["todo","in_progress","done"]},"order":{"type":"number"},"archived":{"type":"boolean"},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"firedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"channel":{"type":"string","enum":["notification","email","both"]}},"required":["remindAt"],"additionalProperties":false},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","title","titled","visibility","bodyReadable","tags","boardId","columnId","status","order","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"taskId":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","minLength":1,"maxLength":500},"body":{"type":"string","maxLength":750000},"description":{"type":"string","maxLength":750000},"tags":{"maxItems":64,"type":"array","items":{"type":"string","maxLength":120}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"dueAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"reminder":{"type":"object","properties":{"remindAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"recurrence":{"type":"string","enum":["daily","weekdays","weekly","monthly"]},"channel":{"type":"string","const":"notification"}},"required":["remindAt"],"additionalProperties":false},"clearDueAt":{"type":"boolean"},"clearReminder":{"type":"boolean"}},"required":["taskId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/update_block":{"post":{"tags":["kvark-v2"],"summary":"Switch one caller-owned List block between its checklist and board render styles.","description":"Switch one caller-owned List block between its checklist and board render styles.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_update_block","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"journal"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"canvas"},"placement":{"type":"string","const":"inline"}},"required":["id","nukleonId","order","createdAt","updatedAt","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"nukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"list"},"childNukleonId":{"type":"string","minLength":1,"maxLength":128},"boardId":{"type":"string","minLength":1,"maxLength":128},"renderStyle":{"default":"checklist","type":"string","enum":["checklist","board"]}},"required":["id","nukleonId","order","createdAt","updatedAt","kind","childNukleonId","renderStyle"],"additionalProperties":false}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"blockId":{"type":"string","minLength":1,"maxLength":128},"renderStyle":{"type":"string","enum":["checklist","board"]},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["nukleonId","blockId","renderStyle"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/update_board":{"post":{"tags":["kvark-v2"],"summary":"Update caller-owned Kvark Board metadata without changing stable column identities.","description":"Update caller-owned Kvark Board metadata without changing stable column identities.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_update_board","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"entryColumnId":{"type":"string","minLength":1,"maxLength":128},"terminalColumnId":{"type":"string","minLength":1,"maxLength":128},"defaultVisibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"ownerNukleonId":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"number"},"archived":{"type":"boolean"},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","name","entryColumnId","order","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"boardId":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"defaultVisibility":{"anyOf":[{"type":"string","enum":["zero-knowledge","server-readable"]},{"type":"null"}]},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["boardId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/kvark/write/update_nukleon":{"post":{"tags":["kvark-v2"],"summary":"Patch caller-owned plaintext Nukleon identity metadata without reading or rewriting encrypted content quarks.","description":"Patch caller-owned plaintext Nukleon identity metadata without reading or rewriting encrypted content quarks.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_kvark_write_update_nukleon","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["note","task","drawing"]},"visibility":{"type":"string","enum":["zero-knowledge","server-readable"]},"dekEnvelope":{"type":"object","properties":{"version":{"type":"number","const":1},"wrappedDek":{"type":"string","minLength":1,"maxLength":4096},"wrapIv":{"type":"string","minLength":1,"maxLength":256}},"required":["version","wrappedDek","wrapIv"],"additionalProperties":false},"title":{"type":"string","maxLength":500},"sealed":{"type":"boolean","const":true},"everServerReadable":{"type":"boolean"},"vaultId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"boostedUntil":{"type":"number"},"combinePending":{"type":"object","properties":{"sourceIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"startedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sourceIds","startedAt","expiresAt"],"additionalProperties":false},"boardId":{"type":"string","minLength":1,"maxLength":128},"trashedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"purgeAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","tags","archived","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"nukleonId":{"type":"string","minLength":1,"maxLength":128},"title":{"type":"string","maxLength":500},"tags":{"maxItems":64,"type":"array","items":{"type":"string","maxLength":120}},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":4096}},"archived":{"type":"boolean"},"boostedUntil":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["nukleonId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/archive_customer":{"post":{"tags":["ledger-v2"],"summary":"Flip a customer archived flag.","description":"Flip a customer archived flag.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_archive_customer","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","archived"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/archive_work_type":{"post":{"tags":["ledger-v2"],"summary":"Flip a work-type archived flag.","description":"Flip a work-type archived flag.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_archive_work_type","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","archived"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/attach_scans_to_entry":{"post":{"tags":["ledger-v2"],"summary":"Move scans' attachments onto a journal entry, deleting the scan records.","description":"Move scans' attachments onto a journal entry, deleting the scan records.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_attach_scans_to_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"attached":{"type":"number"}},"required":["attached"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"transactionKey":{"type":"string"},"scanIds":{"type":"array","items":{"type":"string"}}},"required":["transactionKey","scanIds"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/clearing_count":{"post":{"tags":["ledger-v2"],"summary":"Count of journal entries touching the clearing account (2999) across the last 24 months.","description":"Count of journal entries touching the clearing account (2999) across the last 24 months.","operationId":"post_api_v2_ledger_read_clearing_count","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"number"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/compute_oss_report":{"post":{"tags":["ledger-v2"],"summary":"Compute the quarterly EU OSS report (per-country B2C digital service VAT).","description":"Compute the quarterly EU OSS report (per-country B2C digital service VAT).","operationId":"post_api_v2_ledger_read_compute_oss_report","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"period":{"type":"object","properties":{"year":{"type":"number"},"quarter":{"type":"number"},"startDate":{"type":"string"},"endDate":{"type":"string"}},"required":["year","quarter","startDate","endDate"],"additionalProperties":false},"countries":{"type":"array","items":{"type":"object","properties":{"countryCode":{"type":"string"},"countryName":{"type":"string"},"vatRate":{"type":"number"},"transactions":{"type":"array","items":{"type":"object","properties":{"jeKey":{"type":"string"},"seq":{"type":"number"},"date":{"type":"string"},"description":{"type":"string"},"counterparty":{"type":"string"},"netAmount":{"type":"number"},"vatAmount":{"type":"number"}},"required":["jeKey","seq","date","description","netAmount","vatAmount"],"additionalProperties":false}},"totalNet":{"type":"number"},"totalVat":{"type":"number"},"collectedVat":{"type":"number"},"vatDelta":{"type":"number"},"filable":{"type":"boolean"}},"required":["countryCode","countryName","vatRate","transactions","totalNet","totalVat","collectedVat","vatDelta","filable"],"additionalProperties":false}},"grandTotalNet":{"type":"number"},"grandTotalVat":{"type":"number"}},"required":["period","countries","grandTotalNet","grandTotalVat"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100},"quarter":{"type":"integer","minimum":1,"maximum":4}},"required":["year","quarter"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/compute_tilinpaatos":{"post":{"tags":["ledger-v2"],"summary":"Compute the annual PMA mikroyritys financial statement (tase + tuloslaskelma).","description":"Compute the annual PMA mikroyritys financial statement (tase + tuloslaskelma).","operationId":"post_api_v2_ledger_read_compute_tilinpaatos","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"year":{"type":"number"},"priorYear":{"type":"number"},"tase":{"type":"object","properties":{"vastaavaa":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"groups":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"accounts":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"balance":{"type":"number"},"priorBalance":{"type":"number"}},"required":["code","name","balance","priorBalance"],"additionalProperties":false}},"total":{"type":"number"},"priorTotal":{"type":"number"}},"required":["label","accounts","total","priorTotal"],"additionalProperties":false}},"total":{"type":"number"},"priorTotal":{"type":"number"}},"required":["label","groups","total","priorTotal"],"additionalProperties":false}},"vastaavaaYhteensa":{"type":"number"},"vastaavaaPrior":{"type":"number"},"vastattavaa":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"groups":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"accounts":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"balance":{"type":"number"},"priorBalance":{"type":"number"}},"required":["code","name","balance","priorBalance"],"additionalProperties":false}},"total":{"type":"number"},"priorTotal":{"type":"number"}},"required":["label","accounts","total","priorTotal"],"additionalProperties":false}},"total":{"type":"number"},"priorTotal":{"type":"number"}},"required":["label","groups","total","priorTotal"],"additionalProperties":false}},"vastattavaaYhteensa":{"type":"number"},"vastattavaaPrior":{"type":"number"}},"required":["vastaavaa","vastaavaaYhteensa","vastaavaaPrior","vastattavaa","vastattavaaYhteensa","vastattavaaPrior"],"additionalProperties":false},"tuloslaskelma":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"priorAmount":{"type":"number"},"isSubtotal":{"type":"boolean"}},"required":["label","amount","priorAmount"],"additionalProperties":false}},"tilikausiVoitto":{"type":"number"},"tilikausiVoittoPrior":{"type":"number"}},"required":["lines","tilikausiVoitto","tilikausiVoittoPrior"],"additionalProperties":false}},"required":["year","priorYear","tase","tuloslaskelma"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100}},"required":["year"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/compute_vat_report":{"post":{"tags":["ledger-v2"],"summary":"Compute the quarterly OmaVero domestic VAT (ALV-ilmoitus) report.","description":"Compute the quarterly OmaVero domestic VAT (ALV-ilmoitus) report.","operationId":"post_api_v2_ledger_read_compute_vat_report","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"period":{"type":"object","properties":{"year":{"type":"number"},"quarter":{"type":"number"},"startDate":{"type":"string"},"endDate":{"type":"string"}},"required":["year","quarter","startDate","endDate"],"additionalProperties":false},"rows":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":"string"},"amount":{"type":"number"}},"required":["code","description","amount"],"additionalProperties":false}}},"required":["period","rows"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100},"quarter":{"type":"integer","minimum":1,"maximum":4}},"required":["year","quarter"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/create_customer":{"post":{"tags":["ledger-v2"],"summary":"Create a customer (validates name, Y-tunnus, payment terms, country, currency).","description":"Create a customer (validates name, Y-tunnus, payment terms, country, currency).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_create_customer","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"email":{"type":"string"},"contactName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"iban":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"notes":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","seq","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{"type":"object","properties":{"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"email":{"type":"string"},"contactName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"iban":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"notes":{"type":"string"},"archived":{"type":"boolean"}},"required":["name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false}},"required":["input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/create_invoice_draft":{"post":{"tags":["ledger-v2"],"summary":"Create a draft invoice for a customer, snapshotting billing data and computing totals.","description":"Create a draft invoice for a customer, snapshotting billing data and computing totals.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_create_invoice_draft","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"number":{"type":"string"},"fiscalYear":{"type":"number"},"yearSeq":{"type":"number"},"customerId":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"contactName":{"type":"string"},"email":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultCurrency":{"type":"string"}},"required":["id","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false},"issueDate":{"type":"string"},"dueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string","enum":["minutes","piece","hour"]},"unitPriceCents":{"type":"number"},"netCents":{"type":"number"},"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"vatCents":{"type":"number"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","netCents","vatCodeId","vatRate","vatCents"],"additionalProperties":false}},"netCents":{"type":"number"},"vatCents":{"type":"number"},"totalCents":{"type":"number"},"currency":{"type":"string"},"vatBreakdown":{"type":"array","items":{"type":"object","properties":{"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"netCents":{"type":"number"},"vatCents":{"type":"number"}},"required":["vatCodeId","vatRate","netCents","vatCents"],"additionalProperties":false}},"referenceNumber":{"type":"string"},"status":{"type":"string","enum":["draft","issued","paid","credited"]},"paidAt":{"type":"number"},"paymentJournalEntryKey":{"type":"string"},"receivableJournalEntryKey":{"type":"string"},"creditNoteOf":{"type":"string"},"creditedBy":{"type":"string"},"notes":{"type":"string"}},"required":["id","seq","customerId","customer","issueDate","dueDate","lines","netCents","vatCents","totalCents","currency","vatBreakdown","status"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{"type":"object","properties":{"customerId":{"type":"string"},"issueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"anyOf":[{"type":"string","const":"minutes"},{"type":"string","const":"piece"},{"type":"string","const":"hour"}]},"unitPriceCents":{"type":"number"},"vatCodeId":{"type":"string"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","vatCodeId"],"additionalProperties":false}},"notes":{"type":"string"},"currency":{"type":"string"}},"required":["customerId","issueDate","lines","currency"],"additionalProperties":false}},"required":["input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/create_journal_entry":{"post":{"tags":["ledger-v2"],"summary":"Create a balanced journal entry, allocating the next sequence.","description":"Create a balanced journal entry, allocating the next sequence.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_create_journal_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"date":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"},"vatAmount":{"type":"number"},"description":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"vatInclusive":{"type":"boolean"},"bankAccountId":{"type":"string"},"counterparty":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"transactionType":{"type":"string"},"transactionRef":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false}},"source":{"anyOf":[{"type":"string","const":"manual"},{"type":"string","const":"revolut"},{"type":"string","const":"stripe"},{"type":"string","const":"merit"}]},"externalId":{"type":"string"}},"required":["date","description","legs","amount","currency"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/create_time_entry":{"post":{"tags":["ledger-v2"],"summary":"Create a draft time entry (validates customer + work type exist).","description":"Create a draft time entry (validates customer + work type exist).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_create_time_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"date":{"type":"string"},"customerId":{"type":"string"},"workTypeId":{"type":"string"},"minutes":{"type":"number"},"note":{"type":"string"},"status":{"type":"string","enum":["draft","invoiced"]},"invoiceId":{"type":"string"}},"required":["id","seq","date","customerId","workTypeId","minutes","status"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{"type":"object","properties":{"date":{"type":"string"},"customerId":{"type":"string"},"workTypeId":{"type":"string"},"minutes":{"type":"number"},"note":{"type":"string"}},"required":["date","customerId","workTypeId","minutes"],"additionalProperties":false}},"required":["input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/create_work_type":{"post":{"tags":["ledger-v2"],"summary":"Create a work type (validates name, hourly rate ≥ 0, currency, vat code).","description":"Create a work type (validates name, hourly rate ≥ 0, currency, vat code).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_create_work_type","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"name":{"type":"string"},"defaultHourlyRate":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","seq","name","defaultHourlyRate","defaultVatCodeId","defaultCurrency"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{"type":"object","properties":{"name":{"type":"string"},"defaultHourlyRate":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"archived":{"type":"boolean"}},"required":["name","defaultHourlyRate","defaultVatCodeId","defaultCurrency"],"additionalProperties":false}},"required":["input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/credit_invoice":{"post":{"tags":["ledger-v2"],"summary":"Create a credit note (hyvityslasku) reversing an issued/paid invoice, then flip the original credited.","description":"Create a credit note (hyvityslasku) reversing an issued/paid invoice, then flip the original credited.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_credit_invoice","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"number":{"type":"string"},"fiscalYear":{"type":"number"},"yearSeq":{"type":"number"},"customerId":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"contactName":{"type":"string"},"email":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultCurrency":{"type":"string"}},"required":["id","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false},"issueDate":{"type":"string"},"dueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string","enum":["minutes","piece","hour"]},"unitPriceCents":{"type":"number"},"netCents":{"type":"number"},"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"vatCents":{"type":"number"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","netCents","vatCodeId","vatRate","vatCents"],"additionalProperties":false}},"netCents":{"type":"number"},"vatCents":{"type":"number"},"totalCents":{"type":"number"},"currency":{"type":"string"},"vatBreakdown":{"type":"array","items":{"type":"object","properties":{"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"netCents":{"type":"number"},"vatCents":{"type":"number"}},"required":["vatCodeId","vatRate","netCents","vatCents"],"additionalProperties":false}},"referenceNumber":{"type":"string"},"status":{"type":"string","enum":["draft","issued","paid","credited"]},"paidAt":{"type":"number"},"paymentJournalEntryKey":{"type":"string"},"receivableJournalEntryKey":{"type":"string"},"creditNoteOf":{"type":"string"},"creditedBy":{"type":"string"},"notes":{"type":"string"}},"required":["id","seq","customerId","customer","issueDate","dueDate","lines","netCents","vatCents","totalCents","currency","vatBreakdown","status"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"issueDate":{"type":"string"},"notes":{"type":"string"}},"required":["id","issueDate"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/dashboard_summary":{"post":{"tags":["ledger-v2"],"summary":"Compute the dashboard balance, performance series, and prior-period comparison totals.","description":"Compute the dashboard balance, performance series, and prior-period comparison totals.","operationId":"post_api_v2_ledger_read_dashboard_summary","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"current":{"type":"object","properties":{"asOfDate":{"type":["string","null"]},"accountBalances":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"balance":{"type":"number"}},"required":["code","name","type","balance"],"additionalProperties":false}}},"required":["asOfDate","accountBalances"],"additionalProperties":false},"performance":{"type":"object","properties":{"granularity":{"type":"string","enum":["day","month"]},"startDate":{"type":"string"},"endDate":{"type":"string"},"buckets":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"revenue":{"type":"number"},"expenses":{"type":"number"},"transactionCount":{"type":"number"}},"required":["date","revenue","expenses","transactionCount"],"additionalProperties":false}},"totals":{"type":"object","properties":{"revenue":{"type":"number"},"expenses":{"type":"number"},"netResult":{"type":"number"},"transactionCount":{"type":"number"}},"required":["revenue","expenses","netResult","transactionCount"],"additionalProperties":false},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"totals":{"type":"object","properties":{"revenue":{"type":"number"},"expenses":{"type":"number"},"netResult":{"type":"number"},"transactionCount":{"type":"number"}},"required":["revenue","expenses","netResult","transactionCount"],"additionalProperties":false}},"required":["startDate","endDate","totals"],"additionalProperties":false},"topRevenueAccounts":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"total":{"type":"number"}},"required":["code","name","total"],"additionalProperties":false}},"topExpenseAccounts":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"total":{"type":"number"}},"required":["code","name","total"],"additionalProperties":false}}},"required":["granularity","startDate","endDate","buckets","totals","comparison","topRevenueAccounts","topExpenseAccounts"],"additionalProperties":false}},"required":["current","performance"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"period":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"preset"},"preset":{"type":"string","enum":["7d","30d","90d","365d","ytd"]}},"required":["kind","preset"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"year"},"year":{"type":"integer","minimum":2000,"maximum":2100}},"required":["kind","year"],"additionalProperties":false}]}},"required":["period"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_attachment":{"post":{"tags":["ledger-v2"],"summary":"Delete a stored attachment and detach it from its journal entry.","description":"Delete a stored attachment and detach it from its journal entry.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_attachment","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"transactionKey":{"type":"string"},"storageKey":{"type":"string"}},"required":["transactionKey","storageKey"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_customer":{"post":{"tags":["ledger-v2"],"summary":"Delete a customer and cascade its per-customer rate overrides (idempotent).","description":"Delete a customer and cascade its per-customer rate overrides (idempotent).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_customer","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_customer_rate":{"post":{"tags":["ledger-v2"],"summary":"Delete a per-customer rate override by composite key (idempotent).","description":"Delete a per-customer rate override by composite key (idempotent).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_customer_rate","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string"},"workTypeId":{"type":"string"}},"required":["customerId","workTypeId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_invoice_draft":{"post":{"tags":["ledger-v2"],"summary":"Delete a draft invoice (idempotent; only drafts can be deleted). KV-only — no blob cleanup.","description":"Delete a draft invoice (idempotent; only drafts can be deleted). KV-only — no blob cleanup.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_invoice_draft","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_journal_entry":{"post":{"tags":["ledger-v2"],"summary":"Delete a journal entry: remove its attachment blobs from protected storage, then its record.","description":"Delete a journal entry: remove its attachment blobs from protected storage, then its record.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_journal_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"boolean"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"key":{"type":"string"}},"required":["key"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_report":{"post":{"tags":["ledger-v2"],"summary":"Delete a saved report: remove its stored PDF blob and both KV records.","description":"Delete a saved report: remove its stored PDF blob and both KV records.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_report","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"boolean"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reportType":{"type":"string","enum":["vat","oss","annual"]},"period":{"type":"string"}},"required":["reportType","period"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_scan":{"post":{"tags":["ledger-v2"],"summary":"Delete a scan: remove its stored blob and the scan record. Idempotent (false if absent).","description":"Delete a scan: remove its stored blob and the scan record. Idempotent (false if absent).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_scan","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"boolean"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_time_entry":{"post":{"tags":["ledger-v2"],"summary":"Delete a draft time entry (invoiced entries cannot be deleted).","description":"Delete a draft time entry (invoiced entries cannot be deleted).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_time_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/delete_work_type":{"post":{"tags":["ledger-v2"],"summary":"Delete a work type and any rate overrides referencing it (idempotent).","description":"Delete a work type and any rate overrides referencing it (idempotent).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_delete_work_type","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/export_oss_csv":{"post":{"tags":["ledger-v2"],"summary":"Build the Union-scheme OSS CSV upload (vero.fi) for the quarter.","description":"Build the Union-scheme OSS CSV upload (vero.fi) for the quarter.","operationId":"post_api_v2_ledger_read_export_oss_csv","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true},"csv":{"type":"string"}},"required":["ok","csv"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","const":false},"errors":{"type":"array","items":{"type":"string"}}},"required":["ok","errors"],"additionalProperties":false}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100},"quarter":{"type":"integer","minimum":1,"maximum":4}},"required":["year","quarter"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/extract_from_attachments":{"post":{"tags":["ledger-v2"],"summary":"Extract journal-entry data from receipt/invoice attachments with the platform text model.","description":"Extract journal-entry data from receipt/invoice attachments with the platform text model.","operationId":"post_api_v2_ledger_read_extract_from_attachments","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"date":{"type":"string"},"counterparty":{"type":"string"},"reference":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"data":{"type":"string"},"mimeType":{"type":"string"},"filename":{"type":"string"}},"required":["data","mimeType","filename"],"additionalProperties":false}},"scanIds":{"type":"array","items":{"type":"string"}},"direction":{"type":"string","enum":["expense","income"]}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/find_dangling_attachments":{"post":{"tags":["ledger-v2"],"summary":"Check Ledger attachment references and return any whose stored blobs are missing.","description":"Check Ledger attachment references and return any whose stored blobs are missing.","operationId":"post_api_v2_ledger_read_find_dangling_attachments","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"checked":{"type":"number"},"missing":{"type":"number"},"dangling":{"type":"array","items":{"type":"object","properties":{"storageKey":{"type":"string"},"recordKey":{"type":"string"},"recordType":{"type":"string","enum":["journal-entry","scan","report"]},"filename":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","recordKey","recordType","filename","size","uploadedAt"],"additionalProperties":false}}},"required":["checked","missing","dangling"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/generate_invoice_pdf":{"post":{"tags":["ledger-v2"],"summary":"Generate a Finnish-format invoice PDF, upload it to protected storage, and return a signed URL.","description":"Generate a Finnish-format invoice PDF, upload it to protected storage, and return a signed URL.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_generate_invoice_pdf","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"size":{"type":"number"}},"required":["url","filename","size"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/generate_report_pdf":{"post":{"tags":["ledger-v2"],"summary":"Render a saved VAT/OSS/annual report to PDF, upload it to protected storage (replacing the previous PDF), and return a signed URL.","description":"Render a saved VAT/OSS/annual report to PDF, upload it to protected storage (replacing the previous PDF), and return a signed URL.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_generate_report_pdf","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"size":{"type":"number"}},"required":["url","filename","size"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reportType":{"type":"string","enum":["vat","oss","annual"]},"period":{"type":"string"}},"required":["reportType","period"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_attachment_url":{"post":{"tags":["ledger-v2"],"summary":"Mint a fresh signed download URL for a ledger attachment.","description":"Mint a fresh signed download URL for a ledger attachment.","operationId":"post_api_v2_ledger_read_get_attachment_url","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string"},"expiresAt":{"type":"number"}},"required":["url"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storageKey":{"type":"string"}},"required":["storageKey"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_config":{"post":{"tags":["ledger-v2"],"summary":"Ledger config: the constant Finnish VAT codes + EU rates and opening balances.","description":"Ledger config: the constant Finnish VAT codes + EU rates and opening balances.","operationId":"post_api_v2_ledger_read_get_config","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"vatCodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rate":{"type":"number"},"name":{"type":"string"},"reverseCharge":{"type":"boolean"}},"required":["id","rate","name"],"additionalProperties":false}},"euVatRates":{"type":"object","properties":{"version":{"type":"number"},"fetchedAt":{"type":"number"},"items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"effective_from":{"type":"string"},"rates":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}}},"required":["effective_from","rates"],"additionalProperties":false}}}},"required":["version","fetchedAt","items"],"additionalProperties":false},"openingBalances":{"anyOf":[{"type":"object","properties":{"date":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"},"vatAmount":{"type":"number"},"description":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}}},"required":["date","legs"],"additionalProperties":false},{"type":"null"}]}},"required":["vatCodes","euVatRates","openingBalances"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_counterparties":{"post":{"tags":["ledger-v2"],"summary":"Distinct, locale-sorted counterparties across the last 24 months of journal entries.","description":"Distinct, locale-sorted counterparties across the last 24 months of journal entries.","operationId":"post_api_v2_ledger_read_get_counterparties","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"string"}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_customer":{"post":{"tags":["ledger-v2"],"summary":"Fetch one customer by id.","description":"Fetch one customer by id.","operationId":"post_api_v2_ledger_read_get_customer","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"email":{"type":"string"},"contactName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"iban":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"notes":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","seq","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_invoice":{"post":{"tags":["ledger-v2"],"summary":"Fetch a single invoice by id.","description":"Fetch a single invoice by id.","operationId":"post_api_v2_ledger_read_get_invoice","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"number":{"type":"string"},"fiscalYear":{"type":"number"},"yearSeq":{"type":"number"},"customerId":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"contactName":{"type":"string"},"email":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultCurrency":{"type":"string"}},"required":["id","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false},"issueDate":{"type":"string"},"dueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string","enum":["minutes","piece","hour"]},"unitPriceCents":{"type":"number"},"netCents":{"type":"number"},"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"vatCents":{"type":"number"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","netCents","vatCodeId","vatRate","vatCents"],"additionalProperties":false}},"netCents":{"type":"number"},"vatCents":{"type":"number"},"totalCents":{"type":"number"},"currency":{"type":"string"},"vatBreakdown":{"type":"array","items":{"type":"object","properties":{"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"netCents":{"type":"number"},"vatCents":{"type":"number"}},"required":["vatCodeId","vatRate","netCents","vatCents"],"additionalProperties":false}},"referenceNumber":{"type":"string"},"status":{"type":"string","enum":["draft","issued","paid","credited"]},"paidAt":{"type":"number"},"paymentJournalEntryKey":{"type":"string"},"receivableJournalEntryKey":{"type":"string"},"creditNoteOf":{"type":"string"},"creditedBy":{"type":"string"},"notes":{"type":"string"}},"required":["id","seq","customerId","customer","issueDate","dueDate","lines","netCents","vatCents","totalCents","currency","vatBreakdown","status"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_journal_entry":{"post":{"tags":["ledger-v2"],"summary":"A single journal entry by KV key.","description":"A single journal entry by KV key.","operationId":"post_api_v2_ledger_read_get_journal_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"seq":{"type":"number"},"date":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"},"vatAmount":{"type":"number"},"description":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"vatInclusive":{"type":"boolean"},"bankAccountId":{"type":"string"},"counterparty":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"transactionType":{"type":"string"},"transactionRef":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false}},"source":{"type":"string","enum":["manual","revolut","stripe","merit"]},"externalId":{"type":"string"}},"required":["seq","date","description","legs","amount","currency","attachments","source"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"key":{"type":"string"}},"required":["key"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_saved_report":{"post":{"tags":["ledger-v2"],"summary":"Read a saved report payload and metadata, including validation details for malformed legacy data.","description":"Read a saved report payload and metadata, including validation details for malformed legacy data.","operationId":"post_api_v2_ledger_read_get_saved_report","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reportType":{"type":"string","enum":["vat","oss","annual"]},"period":{"type":"string"},"data":{},"meta":{"anyOf":[{"type":"object","properties":{"reportType":{"type":"string","enum":["vat","oss","annual"]},"period":{"type":"string"},"generatedAt":{"type":"number"},"generatedBy":{"type":"string"},"attachment":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"}},"required":["storageKey","filename","mimeType","size"],"additionalProperties":false}},"required":["reportType","period","generatedAt","generatedBy"],"additionalProperties":false},{"type":"null"}]},"validation":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","const":false},"problem":{"type":"string"}},"required":["ok","problem"],"additionalProperties":false}]}},"required":["reportType","period","data","meta","validation"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reportType":{"type":"string","enum":["vat","oss","annual"]},"period":{"type":"string"}},"required":["reportType","period"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_saved_report_pdf_url":{"post":{"tags":["ledger-v2"],"summary":"Return a fresh signed URL for the stored PDF of a saved report.","description":"Return a fresh signed URL for the stored PDF of a saved report.","operationId":"post_api_v2_ledger_read_get_saved_report_pdf_url","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"expiresAt":{"type":"number"}},"required":["url","filename"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reportType":{"type":"string","enum":["vat","oss","annual"]},"period":{"type":"string"}},"required":["reportType","period"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_scan":{"post":{"tags":["ledger-v2"],"summary":"Fetch a single scan record by id.","description":"Fetch a single scan record by id.","operationId":"post_api_v2_ledger_read_get_scan","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"attachment":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false},"source":{"type":"string","enum":["camera","upload"]},"extraction":{"type":"object","properties":{"date":{"type":"string"},"counterparty":{"type":"string"},"reference":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"required":["id","attachment","source"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_tilinpaatos_config":{"post":{"tags":["ledger-v2"],"summary":"Read the assembled tilinpäätös config (company + per-year notes/approval/records/signatures).","description":"Read the assembled tilinpäätös config (company + per-year notes/approval/records/signatures).","operationId":"post_api_v2_ledger_read_get_tilinpaatos_config","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"company":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"ytunnus":{"type":"string"},"address":{"type":"string"},"domicile":{"type":"string"},"iban":{"type":"string"},"bic":{"type":"string"},"email":{"type":"string"},"website":{"type":"string"}},"required":["name","ytunnus","address","domicile"],"additionalProperties":false},{"type":"null"}]},"notes":{"anyOf":[{"type":"object","properties":{"pmaStatement":{"type":"string"},"averageHeadcount":{"type":"number"},"equityProposal":{"type":"string"},"customNotes":{"type":"array","items":{"type":"string"}}},"required":["pmaStatement","averageHeadcount","equityProposal","customNotes"],"additionalProperties":false},{"type":"null"}]},"approval":{"anyOf":[{"type":"object","properties":{"approvalDate":{"type":"string"},"approvalPlace":{"type":"string"},"signerName":{"type":"string"},"signerRole":{"type":"string"}},"required":["approvalDate"],"additionalProperties":false},{"type":"null"}]},"records":{"type":["string","null"]},"signatures":{"anyOf":[{"type":"object","properties":{"location":{"type":"string"},"signers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"}},"required":["name","title"],"additionalProperties":false}}},"required":["location","signers"],"additionalProperties":false},{"type":"null"}]}},"required":["company","notes","approval","records","signatures"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100}},"required":["year"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/get_time_entry":{"post":{"tags":["ledger-v2"],"summary":"Fetch one time entry by id.","description":"Fetch one time entry by id.","operationId":"post_api_v2_ledger_read_get_time_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"date":{"type":"string"},"customerId":{"type":"string"},"workTypeId":{"type":"string"},"minutes":{"type":"number"},"note":{"type":"string"},"status":{"type":"string","enum":["draft","invoiced"]},"invoiceId":{"type":"string"}},"required":["id","seq","date","customerId","workTypeId","minutes","status"],"additionalProperties":false},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/issue_invoice":{"post":{"tags":["ledger-v2"],"summary":"Issue a draft: assign number + reference, book the receivable JE, flip linked time entries to invoiced.","description":"Issue a draft: assign number + reference, book the receivable JE, flip linked time entries to invoiced.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_issue_invoice","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"number":{"type":"string"},"fiscalYear":{"type":"number"},"yearSeq":{"type":"number"},"customerId":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"contactName":{"type":"string"},"email":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultCurrency":{"type":"string"}},"required":["id","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false},"issueDate":{"type":"string"},"dueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string","enum":["minutes","piece","hour"]},"unitPriceCents":{"type":"number"},"netCents":{"type":"number"},"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"vatCents":{"type":"number"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","netCents","vatCodeId","vatRate","vatCents"],"additionalProperties":false}},"netCents":{"type":"number"},"vatCents":{"type":"number"},"totalCents":{"type":"number"},"currency":{"type":"string"},"vatBreakdown":{"type":"array","items":{"type":"object","properties":{"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"netCents":{"type":"number"},"vatCents":{"type":"number"}},"required":["vatCodeId","vatRate","netCents","vatCents"],"additionalProperties":false}},"referenceNumber":{"type":"string"},"status":{"type":"string","enum":["draft","issued","paid","credited"]},"paidAt":{"type":"number"},"paymentJournalEntryKey":{"type":"string"},"receivableJournalEntryKey":{"type":"string"},"creditNoteOf":{"type":"string"},"creditedBy":{"type":"string"},"notes":{"type":"string"}},"required":["id","seq","customerId","customer","issueDate","dueDate","lines","netCents","vatCents","totalCents","currency","vatBreakdown","status"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_all_customer_rates":{"post":{"tags":["ledger-v2"],"summary":"Every rate override across all customers. Used by views that render rates per row.","description":"Every rate override across all customers. Used by views that render rates per row.","operationId":"post_api_v2_ledger_read_list_all_customer_rates","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"customerId":{"type":"string"},"workTypeId":{"type":"string"},"hourlyRate":{"type":"number"},"vatCodeId":{"type":"string"},"currency":{"type":"string"}},"required":["customerId","workTypeId","hourlyRate"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_clearing_entries":{"post":{"tags":["ledger-v2"],"summary":"Journal entries touching the clearing account (2999) across the last 24 months.","description":"Journal entries touching the clearing account (2999) across the last 24 months.","operationId":"post_api_v2_ledger_read_list_clearing_entries","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"object","properties":{"seq":{"type":"number"},"date":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"},"vatAmount":{"type":"number"},"description":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"vatInclusive":{"type":"boolean"},"bankAccountId":{"type":"string"},"counterparty":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"transactionType":{"type":"string"},"transactionRef":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false}},"source":{"type":"string","enum":["manual","revolut","stripe","merit"]},"externalId":{"type":"string"}},"required":["seq","date","description","legs","amount","currency","attachments","source"],"additionalProperties":false}},"required":["key","value"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_customer_rates":{"post":{"tags":["ledger-v2"],"summary":"All rate overrides for one customer.","description":"All rate overrides for one customer.","operationId":"post_api_v2_ledger_read_list_customer_rates","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"customerId":{"type":"string"},"workTypeId":{"type":"string"},"hourlyRate":{"type":"number"},"vatCodeId":{"type":"string"},"currency":{"type":"string"}},"required":["customerId","workTypeId","hourlyRate"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string"}},"required":["customerId"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_customers":{"post":{"tags":["ledger-v2"],"summary":"All customers (archived dropped unless includeArchived), sorted by name with Finnish collation.","description":"All customers (archived dropped unless includeArchived), sorted by name with Finnish collation.","operationId":"post_api_v2_ledger_read_list_customers","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"email":{"type":"string"},"contactName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"iban":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"notes":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","seq","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"includeArchived":{"type":"boolean"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_invoices":{"post":{"tags":["ledger-v2"],"summary":"List invoices filtered by fiscal year / customer / status; drafts first, then newest issued.","description":"List invoices filtered by fiscal year / customer / status; drafts first, then newest issued.","operationId":"post_api_v2_ledger_read_list_invoices","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"number":{"type":"string"},"fiscalYear":{"type":"number"},"yearSeq":{"type":"number"},"customerId":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"contactName":{"type":"string"},"email":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultCurrency":{"type":"string"}},"required":["id","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false},"issueDate":{"type":"string"},"dueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string","enum":["minutes","piece","hour"]},"unitPriceCents":{"type":"number"},"netCents":{"type":"number"},"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"vatCents":{"type":"number"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","netCents","vatCodeId","vatRate","vatCents"],"additionalProperties":false}},"netCents":{"type":"number"},"vatCents":{"type":"number"},"totalCents":{"type":"number"},"currency":{"type":"string"},"vatBreakdown":{"type":"array","items":{"type":"object","properties":{"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"netCents":{"type":"number"},"vatCents":{"type":"number"}},"required":["vatCodeId","vatRate","netCents","vatCents"],"additionalProperties":false}},"referenceNumber":{"type":"string"},"status":{"type":"string","enum":["draft","issued","paid","credited"]},"paidAt":{"type":"number"},"paymentJournalEntryKey":{"type":"string"},"receivableJournalEntryKey":{"type":"string"},"creditNoteOf":{"type":"string"},"creditedBy":{"type":"string"},"notes":{"type":"string"}},"required":["id","seq","customerId","customer","issueDate","dueDate","lines","netCents","vatCents","totalCents","currency","vatBreakdown","status"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"fiscalYear":{"type":"number"},"customerId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"draft"},{"type":"string","const":"issued"},{"type":"string","const":"paid"},{"type":"string","const":"credited"}]}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_journal_entries":{"post":{"tags":["ledger-v2"],"summary":"Journal entries for a month, optionally filtered by bank account and/or attachment presence.","description":"Journal entries for a month, optionally filtered by bank account and/or attachment presence.","operationId":"post_api_v2_ledger_read_list_journal_entries","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"object","properties":{"seq":{"type":"number"},"date":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"},"vatAmount":{"type":"number"},"description":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"vatInclusive":{"type":"boolean"},"bankAccountId":{"type":"string"},"counterparty":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"transactionType":{"type":"string"},"transactionRef":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false}},"source":{"type":"string","enum":["manual","revolut","stripe","merit"]},"externalId":{"type":"string"}},"required":["seq","date","description","legs","amount","currency","attachments","source"],"additionalProperties":false}},"required":["key","value"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"month":{"type":"string"},"bankAccountId":{"type":"string"},"hasAttachment":{"type":"boolean"}},"required":["month"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_revolut_activity":{"post":{"tags":["ledger-v2"],"summary":"List recent Revolut transactions with their ledger import status.","description":"List recent Revolut transactions with their ledger import status.","operationId":"post_api_v2_ledger_read_list_revolut_activity","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"state":{"type":"string"},"date":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"description":{"type":"string"},"imported":{"type":"boolean"},"skippable":{"type":"boolean"},"skipReason":{"type":["string","null"]},"matchedStripe":{"type":"boolean"}},"required":["id","type","state","date","amount","currency","description","imported","skippable","skipReason","matchedStripe"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limit":{"type":"number"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_saved_reports":{"post":{"tags":["ledger-v2"],"summary":"List saved report metadata, newest first (generatedAt desc).","description":"List saved report metadata, newest first (generatedAt desc).","operationId":"post_api_v2_ledger_read_list_saved_reports","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reportType":{"type":"string","enum":["vat","oss","annual"]},"period":{"type":"string"},"generatedAt":{"type":"number"},"generatedBy":{"type":"string"},"attachment":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"}},"required":["storageKey","filename","mimeType","size"],"additionalProperties":false}},"required":["key","reportType","period","generatedAt","generatedBy"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_scans":{"post":{"tags":["ledger-v2"],"summary":"List unattached scan records, newest first (by upload time, tiebroken by id).","description":"List unattached scan records, newest first (by upload time, tiebroken by id).","operationId":"post_api_v2_ledger_read_list_scans","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"attachment":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false},"source":{"type":"string","enum":["camera","upload"]},"extraction":{"type":"object","properties":{"date":{"type":"string"},"counterparty":{"type":"string"},"reference":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"required":["id","attachment","source"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limit":{"type":"number"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_stripe_activity":{"post":{"tags":["ledger-v2"],"summary":"List recent Stripe balance transactions with their ledger import status.","description":"List recent Stripe balance transactions with their ledger import status.","operationId":"post_api_v2_ledger_read_list_stripe_activity","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"net":{"type":"number"},"created":{"type":"number"},"description":{"type":["string","null"]},"customerName":{"type":["string","null"]},"imported":{"type":"boolean"}},"required":["id","type","amount","fee","net","created","description","customerName","imported"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limit":{"type":"number"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_time_entries":{"post":{"tags":["ledger-v2"],"summary":"Time entries for a month, optionally filtered by customer/status, ordered by date then sequence.","description":"Time entries for a month, optionally filtered by customer/status, ordered by date then sequence.","operationId":"post_api_v2_ledger_read_list_time_entries","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"date":{"type":"string"},"customerId":{"type":"string"},"workTypeId":{"type":"string"},"minutes":{"type":"number"},"note":{"type":"string"},"status":{"type":"string","enum":["draft","invoiced"]},"invoiceId":{"type":"string"}},"required":["id","seq","date","customerId","workTypeId","minutes","status"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"month":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string","enum":["draft","invoiced"]}},"required":["month"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_unbilled_for_customer":{"post":{"tags":["ledger-v2"],"summary":"Flat list of draft (uninvoiced) time entries for one customer across the given months.","description":"Flat list of draft (uninvoiced) time entries for one customer across the given months.","operationId":"post_api_v2_ledger_read_list_unbilled_for_customer","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"date":{"type":"string"},"customerId":{"type":"string"},"workTypeId":{"type":"string"},"minutes":{"type":"number"},"note":{"type":"string"},"status":{"type":"string","enum":["draft","invoiced"]},"invoiceId":{"type":"string"}},"required":["id","seq","date","customerId","workTypeId","minutes","status"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string"},"months":{"type":"array","items":{"type":"string"}}},"required":["customerId","months"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/list_work_types":{"post":{"tags":["ledger-v2"],"summary":"All work types (archived dropped unless includeArchived), sorted by name with Finnish collation.","description":"All work types (archived dropped unless includeArchived), sorted by name with Finnish collation.","operationId":"post_api_v2_ledger_read_list_work_types","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"name":{"type":"string"},"defaultHourlyRate":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","seq","name","defaultHourlyRate","defaultVatCodeId","defaultCurrency"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"includeArchived":{"type":"boolean"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/mark_invoice_paid":{"post":{"tags":["ledger-v2"],"summary":"Mark an issued invoice paid: book the payment JE (DR bank, CR receivable) and record paidAt.","description":"Mark an issued invoice paid: book the payment JE (DR bank, CR receivable) and record paidAt.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_mark_invoice_paid","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"number":{"type":"string"},"fiscalYear":{"type":"number"},"yearSeq":{"type":"number"},"customerId":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"contactName":{"type":"string"},"email":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultCurrency":{"type":"string"}},"required":["id","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false},"issueDate":{"type":"string"},"dueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string","enum":["minutes","piece","hour"]},"unitPriceCents":{"type":"number"},"netCents":{"type":"number"},"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"vatCents":{"type":"number"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","netCents","vatCodeId","vatRate","vatCents"],"additionalProperties":false}},"netCents":{"type":"number"},"vatCents":{"type":"number"},"totalCents":{"type":"number"},"currency":{"type":"string"},"vatBreakdown":{"type":"array","items":{"type":"object","properties":{"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"netCents":{"type":"number"},"vatCents":{"type":"number"}},"required":["vatCodeId","vatRate","netCents","vatCents"],"additionalProperties":false}},"referenceNumber":{"type":"string"},"status":{"type":"string","enum":["draft","issued","paid","credited"]},"paidAt":{"type":"number"},"paymentJournalEntryKey":{"type":"string"},"receivableJournalEntryKey":{"type":"string"},"creditNoteOf":{"type":"string"},"creditedBy":{"type":"string"},"notes":{"type":"string"}},"required":["id","seq","customerId","customer","issueDate","dueDate","lines","netCents","vatCents","totalCents","currency","vatBreakdown","status"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"paymentDate":{"type":"string"},"bankAccountCode":{"type":"string"}},"required":["id","paymentDate","bankAccountCode"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/prepare_revolut_connect":{"post":{"tags":["ledger-v2"],"summary":"Mint a Revolut OAuth consent URL for reconnecting the bank integration.","description":"Mint a Revolut OAuth consent URL for reconnecting the bank integration.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_prepare_revolut_connect","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/save_opening_balances":{"post":{"tags":["ledger-v2"],"summary":"Create or relocate the single opening-balances journal entry from per-account balances.","description":"Create or relocate the single opening-balances journal entry from per-account balances.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_save_opening_balances","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"date":{"type":"string"},"balances":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"amount":{"type":"number"}},"required":["accountCode","amount"],"additionalProperties":false}}},"required":["date","balances"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/save_report":{"post":{"tags":["ledger-v2"],"summary":"Persist a computed report + its metadata, preserving any existing PDF attachment.","description":"Persist a computed report + its metadata, preserving any existing PDF attachment.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_save_report","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"dataKey":{"type":"string"},"metaKey":{"type":"string"}},"required":["dataKey","metaKey"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reportType":{"type":"string","enum":["vat","oss","annual"]},"period":{"type":"string"},"data":{}},"required":["reportType","period","data"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/save_tilinpaatos_config":{"post":{"tags":["ledger-v2"],"summary":"Persist the tilinpäätös config — company globally, the rest under per-year keys.","description":"Persist the tilinpäätös config — company globally, the rest under per-year keys.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_save_tilinpaatos_config","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100},"company":{"type":"object","properties":{"name":{"type":"string"},"ytunnus":{"type":"string"},"address":{"type":"string"},"domicile":{"type":"string"}},"required":["name","ytunnus","address","domicile"],"additionalProperties":false},"notes":{"type":"object","properties":{"pmaStatement":{"type":"string"},"averageHeadcount":{"type":"number"},"equityProposal":{"type":"string"},"customNotes":{"type":"array","items":{"type":"string"}}},"required":["pmaStatement","averageHeadcount","equityProposal","customNotes"],"additionalProperties":false},"approval":{"type":"object","properties":{"approvalDate":{"type":"string"},"approvalPlace":{"type":"string"},"signerName":{"type":"string"},"signerRole":{"type":"string"}},"required":["approvalDate"],"additionalProperties":false},"records":{"type":"string"},"signatures":{"type":"object","properties":{"location":{"type":"string"},"signers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"}},"required":["name","title"],"additionalProperties":false}}},"required":["location","signers"],"additionalProperties":false}},"required":["year"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/search_journal_entries":{"post":{"tags":["ledger-v2"],"summary":"Substring search over the last 12 months of journal entries (≤10 hits; empty for q shorter than 2).","description":"Substring search over the last 12 months of journal entries (≤10 hits; empty for q shorter than 2).","operationId":"post_api_v2_ledger_read_search_journal_entries","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"seq":{"type":"number"},"date":{"type":"string"},"counterparty":{"type":"string"},"description":{"type":"string"},"amount":{"type":"number"}},"required":["key","seq","date","counterparty","description","amount"],"additionalProperties":false}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"q":{"type":"string"}},"required":["q"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/set_customer_rate":{"post":{"tags":["ledger-v2"],"summary":"Set a per-customer rate override (validates customer + work type exist, rate ≥ 0).","description":"Set a per-customer rate override (validates customer + work type exist, rate ≥ 0).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_set_customer_rate","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string"},"workTypeId":{"type":"string"},"hourlyRate":{"type":"number"},"vatCodeId":{"type":"string"},"currency":{"type":"string"}},"required":["customerId","workTypeId","hourlyRate"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string"},"workTypeId":{"type":"string"},"input":{"type":"object","properties":{"hourlyRate":{"type":"number"},"vatCodeId":{"type":"string"},"currency":{"type":"string"}},"required":["hourlyRate"],"additionalProperties":false}},"required":["customerId","workTypeId","input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/set_scan_extraction":{"post":{"tags":["ledger-v2"],"summary":"Attach AI-extracted draft journal data to a scan record.","description":"Attach AI-extracted draft journal data to a scan record.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_set_scan_extraction","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"null"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"extraction":{"type":"object","properties":{"date":{"type":"string"},"counterparty":{"type":"string"},"reference":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"required":["id","extraction"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/read/summarize_uninvoiced":{"post":{"tags":["ledger-v2"],"summary":"Aggregate uninvoiced minutes and per-customer totals across a month range.","description":"Aggregate uninvoiced minutes and per-customer totals across a month range.","operationId":"post_api_v2_ledger_read_summarize_uninvoiced","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"totalMinutes":{"type":"number"},"totalEntries":{"type":"number"},"byCustomer":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string"},"minutes":{"type":"number"},"entries":{"type":"number"}},"required":["customerId","minutes","entries"],"additionalProperties":false}}},"required":["totalMinutes","totalEntries","byCustomer"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"months":{"type":"array","items":{"type":"string"}}},"required":["months"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/sync_balance_transactions":{"post":{"tags":["ledger-v2"],"summary":"Import Stripe balance transactions as journal entries (payments, fees, adjustments, refunds, payouts).","description":"Import Stripe balance transactions as journal entries (payments, fees, adjustments, refunds, payouts).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_sync_balance_transactions","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"imported":{"type":"number"},"skipped":{"type":"number"},"total":{"type":"number"},"unhandled":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"effectiveStartDate":{"type":"string"},"stripeBalance":{"type":"number"},"reconciliationResidual":{"type":"number"}},"required":["imported","skipped","total"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/sync_revolut_transactions":{"post":{"tags":["ledger-v2"],"summary":"Import Revolut bank transactions as journal entries (card payments, transfers, fees, topups).","description":"Import Revolut bank transactions as journal entries (card payments, transfers, fees, topups).\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_sync_revolut_transactions","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"imported":{"type":"number"},"skipped":{"type":"number"},"total":{"type":"number"},"deferred":{"type":"number"},"importDrift":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"amount"},"key":{"type":"string"},"externalId":{"type":"string"},"booked":{"type":"number"},"provider":{"type":"number"}},"required":["kind","key","externalId","booked","provider"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"missing"},"key":{"type":"string"},"externalId":{"type":"string"},"booked":{"type":"number"}},"required":["kind","key","externalId","booked"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"state"},"key":{"type":"string"},"externalId":{"type":"string"},"booked":{"type":"number"},"state":{"type":"string"}},"required":["kind","key","externalId","booked","state"],"additionalProperties":false}]}},"reconciliationResiduals":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}}},"required":["imported","skipped","total","deferred"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}},"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/update_customer":{"post":{"tags":["ledger-v2"],"summary":"Update a customer in place, preserving its sequence.","description":"Update a customer in place, preserving its sequence.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_update_customer","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"email":{"type":"string"},"contactName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"iban":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"notes":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","seq","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"input":{"type":"object","properties":{"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"email":{"type":"string"},"contactName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"iban":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"notes":{"type":"string"},"archived":{"type":"boolean"}},"required":["name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false}},"required":["id","input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/update_invoice_draft":{"post":{"tags":["ledger-v2"],"summary":"Replace a draft invoice in place, preserving its id/seq and rebuilding lines/totals/snapshot.","description":"Replace a draft invoice in place, preserving its id/seq and rebuilding lines/totals/snapshot.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_update_invoice_draft","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"number":{"type":"string"},"fiscalYear":{"type":"number"},"yearSeq":{"type":"number"},"customerId":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ytunnus":{"type":"string"},"vatId":{"type":"string"},"countryCode":{"type":"string"},"contactName":{"type":"string"},"email":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"paymentTermsDays":{"type":"number"},"defaultCurrency":{"type":"string"}},"required":["id","name","countryCode","paymentTermsDays","defaultCurrency"],"additionalProperties":false},"issueDate":{"type":"string"},"dueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string","enum":["minutes","piece","hour"]},"unitPriceCents":{"type":"number"},"netCents":{"type":"number"},"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"vatCents":{"type":"number"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","netCents","vatCodeId","vatRate","vatCents"],"additionalProperties":false}},"netCents":{"type":"number"},"vatCents":{"type":"number"},"totalCents":{"type":"number"},"currency":{"type":"string"},"vatBreakdown":{"type":"array","items":{"type":"object","properties":{"vatCodeId":{"type":"string"},"vatRate":{"type":"number"},"netCents":{"type":"number"},"vatCents":{"type":"number"}},"required":["vatCodeId","vatRate","netCents","vatCents"],"additionalProperties":false}},"referenceNumber":{"type":"string"},"status":{"type":"string","enum":["draft","issued","paid","credited"]},"paidAt":{"type":"number"},"paymentJournalEntryKey":{"type":"string"},"receivableJournalEntryKey":{"type":"string"},"creditNoteOf":{"type":"string"},"creditedBy":{"type":"string"},"notes":{"type":"string"}},"required":["id","seq","customerId","customer","issueDate","dueDate","lines","netCents","vatCents","totalCents","currency","vatBreakdown","status"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"input":{"type":"object","properties":{"customerId":{"type":"string"},"issueDate":{"type":"string"},"serviceStartDate":{"type":"string"},"serviceEndDate":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"anyOf":[{"type":"string","const":"minutes"},{"type":"string","const":"piece"},{"type":"string","const":"hour"}]},"unitPriceCents":{"type":"number"},"vatCodeId":{"type":"string"},"timeEntryIds":{"type":"array","items":{"type":"string"}}},"required":["description","quantity","unit","unitPriceCents","vatCodeId"],"additionalProperties":false}},"notes":{"type":"string"},"currency":{"type":"string"}},"required":["customerId","issueDate","lines","currency"],"additionalProperties":false}},"required":["id","input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/update_journal_entry":{"post":{"tags":["ledger-v2"],"summary":"Replace a journal entry by key; relocates the KV key when the date crosses a month boundary.","description":"Replace a journal entry by key; relocates the KV key when the date crosses a month boundary.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_update_journal_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string"}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"key":{"type":"string"},"date":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"},"vatAmount":{"type":"number"},"description":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"vatInclusive":{"type":["boolean","null"]},"bankAccountId":{"type":["string","null"]},"counterparty":{"type":["string","null"]},"amount":{"type":"number"},"currency":{"type":"string"},"transactionType":{"type":["string","null"]},"transactionRef":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false}},"source":{"anyOf":[{"type":"string","const":"manual"},{"type":"string","const":"revolut"},{"type":"string","const":"stripe"},{"type":"string","const":"merit"}]},"externalId":{"type":"string"}},"required":["key","date","description","legs","amount","currency"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/update_time_entry":{"post":{"tags":["ledger-v2"],"summary":"Update a draft time entry; relocates the KV key when the date moves to a new month.","description":"Update a draft time entry; relocates the KV key when the date moves to a new month.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_update_time_entry","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"date":{"type":"string"},"customerId":{"type":"string"},"workTypeId":{"type":"string"},"minutes":{"type":"number"},"note":{"type":"string"},"status":{"type":"string","enum":["draft","invoiced"]},"invoiceId":{"type":"string"}},"required":["id","seq","date","customerId","workTypeId","minutes","status"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"input":{"type":"object","properties":{"date":{"type":"string"},"customerId":{"type":"string"},"workTypeId":{"type":"string"},"minutes":{"type":"number"},"note":{"type":"string"}},"required":["date","customerId","workTypeId","minutes"],"additionalProperties":false}},"required":["id","input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/update_work_type":{"post":{"tags":["ledger-v2"],"summary":"Update a work type in place, preserving its sequence.","description":"Update a work type in place, preserving its sequence.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_update_work_type","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"name":{"type":"string"},"defaultHourlyRate":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","seq","name","defaultHourlyRate","defaultVatCodeId","defaultCurrency"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"input":{"type":"object","properties":{"name":{"type":"string"},"defaultHourlyRate":{"type":"number"},"defaultVatCodeId":{"type":"string"},"defaultCurrency":{"type":"string"},"archived":{"type":"boolean"}},"required":["name","defaultHourlyRate","defaultVatCodeId","defaultCurrency"],"additionalProperties":false}},"required":["id","input"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/upload_attachment":{"post":{"tags":["ledger-v2"],"summary":"Upload a receipt/invoice to protected storage and attach it to a journal entry.","description":"Upload a receipt/invoice to protected storage and attach it to a journal entry.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_upload_attachment","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"transactionKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"data":{"type":"string"}},"required":["transactionKey","filename","mimeType","data"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/ledger/write/upload_scan":{"post":{"tags":["ledger-v2"],"summary":"Upload a receipt scan to protected storage as an unattached scan record.","description":"Upload a receipt scan to protected storage as an unattached scan record.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_ledger_write_upload_scan","responses":{"200":{"description":"Operation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"attachment":{"type":"object","properties":{"storageKey":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["storageKey","filename","mimeType","size","uploadedAt"],"additionalProperties":false},"source":{"type":"string","enum":["camera","upload"]},"extraction":{"type":"object","properties":{"date":{"type":"string"},"counterparty":{"type":"string"},"reference":{"type":"string"},"description":{"type":"string"},"legs":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"vatCodeId":{"type":"string"}},"required":["accountCode","debit","credit"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"required":["id","attachment","source"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"filename":{"type":"string"},"mimeType":{"type":"string"},"data":{"type":"string"},"source":{"type":"string","enum":["camera","upload"]}},"required":["filename","mimeType","data","source"],"additionalProperties":false}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/ledger.audit":{"post":{"tags":["platform-v2"],"summary":"ledger.audit","description":"List changes to Ledger bookkeeping records, newest first: who changed which record and each field before and after. Filter by an exact record key (`targetId`) or a key prefix (`targetPrefix`), not both, by audited key `family`, and from `fromTimestamp` (epoch ms). `limit` defaults to 100 and is clamped to 1 through 200. A null filter counts as omitted. Prefix and family filters scan at most 5,000 recent rows. Requires ledger:admin in ledger.","operationId":"post_api_v2_platform_read_ledger.audit","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"targetId":{"type":"string"},"targetPrefix":{"type":"string"},"family":{"type":"string"},"fromTimestamp":{"type":"number"},"limit":{"description":"Rows to return: 100 when omitted; below 1 or above 200 is clamped.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/htmlApp.current":{"post":{"tags":["platform-v2"],"summary":"htmlApp.current","description":"Return the current version of an HTML app: its hash, size, author, time, note and declared capabilities, or null when no version is selected. Requires access:app on the app.","operationId":"post_api_v2_platform_read_htmlApp.current","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string"}},"required":["appSlug"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/htmlApp.listVersions":{"post":{"tags":["platform-v2"],"summary":"htmlApp.listVersions","description":"List the versions of an HTML app newest first, a page at a time: `page`, `isDone` and `continueCursor`. Requires access:app on the app.","operationId":"post_api_v2_platform_read_htmlApp.listVersions","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string"},"cursor":{"description":"continueCursor from the previous page; omit to start the list.","type":"string","pattern":"^__html:log:\\d{13}:[a-f0-9]{64}$"},"limit":{"description":"Versions per page; 25 when omitted.","type":"integer","minimum":1,"maximum":100}},"required":["appSlug"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/htmlApp.listMine":{"post":{"tags":["platform-v2"],"summary":"htmlApp.listMine","description":"List your HTML apps: `mine` holds the apps you administer (you can share and remove them), `shared` the apps others shared with you. Each carries `canManage`, whether you may change its versions. Needs only a signed-in Furnace ID.","operationId":"post_api_v2_platform_read_htmlApp.listMine","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/htmlApp.removalSummary":{"post":{"tags":["platform-v2"],"summary":"htmlApp.removalSummary","description":"Count what html_app_remove would delete: saved data rows, versions, and people with access, and whether the app is shared with anyone else. Requires manage:roles on the app. Show this to the person before asking them to confirm a removal.","operationId":"post_api_v2_platform_read_htmlApp.removalSummary","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string"}},"required":["appSlug"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/htmlApp.members":{"post":{"tags":["platform-v2"],"summary":"htmlApp.members","description":"List who can open the app: admins, editors, viewers, and anyone with access granted another way, with a `memberId` for html_app_unshare. Requires manage:roles and assign:roles on the app. At most 200 people, admins first; `truncated` says more exist.","operationId":"post_api_v2_platform_read_htmlApp.members","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string"}},"required":["appSlug"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/heroPromo.list":{"post":{"tags":["platform-v2"],"summary":"heroPromo.list","description":"List every hero promo in a namespace in display order, scheduled and disabled ones included; `activeOnly` limits it to the ones visible now. Requires manage:hero_promos on the namespace.","operationId":"post_api_v2_platform_read_heroPromo.list","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string"},"activeOnly":{"type":"boolean"}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/contentLayout.list":{"post":{"tags":["platform-v2"],"summary":"contentLayout.list","description":"List every named content layout in a namespace, ordered by slug, with its SDL document. Requires manage:content_layouts or update:content on the namespace.","operationId":"post_api_v2_platform_read_contentLayout.list","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string"}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/contentLayout.usage":{"post":{"tags":["platform-v2"],"summary":"contentLayout.usage","description":"Count the pages in a namespace that use a named layout as their template. The scan stops at 1,000 pages: 1001 means more than that and the exact count is unknown. Requires manage:content_layouts or update:content on the namespace.","operationId":"post_api_v2_platform_read_contentLayout.usage","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string"},"slug":{"type":"string"}},"required":["namespace","slug"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/durableJob.listDefinitions":{"post":{"tags":["platform-v2"],"summary":"durableJob.listDefinitions","description":"List every registered background job type with its summary, how it runs (`action` or `workflow`), and whether the recovery sweeper may re-dispatch it and a cron schedule may name it. Requires `*:*` in `system`.","operationId":"post_api_v2_platform_read_durableJob.listDefinitions","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/durableJob.listSchedules":{"post":{"tags":["platform-v2"],"summary":"durableJob.listSchedules","description":"List runtime-managed UTC cron schedules that materialize durable tasks, including next/last run linkage. Requires `*:*` in `system`.","operationId":"post_api_v2_platform_read_durableJob.listSchedules","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/deployment.listDomains":{"post":{"tags":["platform-v2"],"summary":"deployment.listDomains","description":"Map each deployed app namespace to its public domain, from the published deployment topology; empty when none is published. Needs only a signed-in Furnace ID.","operationId":"post_api_v2_platform_read_deployment.listDomains","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/media.uniqueTags":{"post":{"tags":["platform-v2"],"summary":"media.uniqueTags","description":"List every tag in use across image, file and audio assets, sorted alphabetically (from at most 10,000 assets). Requires media:admin in media-library.","operationId":"post_api_v2_platform_read_media.uniqueTags","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/media.stats":{"post":{"tags":["platform-v2"],"summary":"media.stats","description":"Media library totals for image, file and audio assets: count and bytes, counts by type, visibility and processing status, and cumulative daily trends (from at most 10,000 assets). Requires media:admin in media-library.","operationId":"post_api_v2_platform_read_media.stats","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/media.cdnConfig":{"post":{"tags":["platform-v2"],"summary":"media.cdnConfig","description":"The public CDN base URL for media. A media administrator (media:admin in media-library) also gets the protected CDN base URL; everyone else gets null for it. Needs only a signed-in Furnace ID.","operationId":"post_api_v2_platform_read_media.cdnConfig","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/media.uniqueVideoTags":{"post":{"tags":["platform-v2"],"summary":"media.uniqueVideoTags","description":"List every tag in use across videos, sorted alphabetically (from at most 10,000 videos). Requires media:admin in media-library.","operationId":"post_api_v2_platform_read_media.uniqueVideoTags","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.subscriberCounts":{"post":{"tags":["platform-v2"],"summary":"comms.subscriberCounts","description":"Count an app’s email subscribers by status (subscribed, unsubscribed, bounced, complained) with a total; each status counts at most 10,000. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.subscriberCounts","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.subscriberTags":{"post":{"tags":["platform-v2"],"summary":"comms.subscriberTags","description":"List every tag on an app’s email subscribers, sorted (from at most 10,000 subscribers). Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.subscriberTags","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.campaign":{"post":{"tags":["platform-v2"],"summary":"comms.campaign","description":"Read one email campaign by id, or null when there is none. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.campaign","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"campaignId":{"type":"string","minLength":1}},"required":["campaignId"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.campaignStats":{"post":{"tags":["platform-v2"],"summary":"comms.campaignStats","description":"Delivery stats for a sent campaign: recipient total and unique recipients delivered, clicked, bounced and complained. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.campaignStats","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"campaignId":{"type":"string","minLength":1}},"required":["campaignId"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.templates":{"post":{"tags":["platform-v2"],"summary":"comms.templates","description":"List an app’s email campaign templates. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.templates","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.audienceSize":{"post":{"tags":["platform-v2"],"summary":"comms.audienceSize","description":"Count an app’s subscribed recipients, or only those with at least one of `audienceTags` (from at most 10,000 subscribers). Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.audienceSize","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"audienceTags":{"type":"array","items":{"type":"string"}}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.legalConfig":{"post":{"tags":["platform-v2"],"summary":"comms.legalConfig","description":"Read an app’s email legal footer (company name, postal address, unsubscribe note), or null when unset. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.legalConfig","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.emailConfig":{"post":{"tags":["platform-v2"],"summary":"comms.emailConfig","description":"Read an app’s email sending configuration (from address and name), or null when unset. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.emailConfig","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/comms.enabledNamespaces":{"post":{"tags":["platform-v2"],"summary":"comms.enabledNamespaces","description":"List the app namespaces the communication center is enabled for. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_comms.enabledNamespaces","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/alert.adminList":{"post":{"tags":["platform-v2"],"summary":"alert.adminList","description":"List site-banner alerts newest first, at most 1,000, active or not. Omit `namespace` for every alert; with it, the platform-wide alerts and those aimed at that app. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_alert.adminList","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string"}}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/alert.adminGet":{"post":{"tags":["platform-v2"],"summary":"alert.adminGet","description":"Read one site-banner alert by id, or null when there is none. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_alert.adminGet","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/broadcast.list":{"post":{"tags":["platform-v2"],"summary":"broadcast.list","description":"List every notification broadcast, newest first, drafts and sent. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_broadcast.list","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/broadcast.get":{"post":{"tags":["platform-v2"],"summary":"broadcast.get","description":"Read one notification broadcast by id, or null when there is none. Requires read:communications in communication-center.","operationId":"post_api_v2_platform_read_broadcast.get","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"broadcastId":{"type":"string","minLength":1}},"required":["broadcastId"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/broadcast.searchUsers":{"post":{"tags":["platform-v2"],"summary":"broadcast.searchUsers","description":"Search people by email or name for broadcast recipients, at most 10; use the returned `subject` values as recipients. Reads the user directory, so it requires write:communications in communication-center.","operationId":"post_api_v2_platform_read_broadcast.searchUsers","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":1}},"required":["query"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/broadcast.usersBySubjects":{"post":{"tags":["platform-v2"],"summary":"broadcast.usersBySubjects","description":"Resolve user ids (subjects) to their subject, email and name; an id that names no user is skipped, and a string that is not a user id is refused. Reads the user directory, so it requires write:communications in communication-center.","operationId":"post_api_v2_platform_read_broadcast.usersBySubjects","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subjects":{"type":"array","items":{"type":"string"}}},"required":["subjects"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/florio.browseByLetter":{"post":{"tags":["platform-v2"],"summary":"florio.browseByLetter","description":"Browse the Florio Italian-English dictionary under one letter, a page at a time: pass `cursor: null` to start, then the `continueCursor` of the previous page until `isDone`. `limit` defaults to 50 entries. Public reference content; any signed-in Furnace ID may read it.","operationId":"post_api_v2_platform_read_florio.browseByLetter","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"letter":{"type":"string"},"cursor":{"type":["string","null"]},"limit":{"type":"number"}},"required":["letter","cursor"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/florio.availableLetters":{"post":{"tags":["platform-v2"],"summary":"florio.availableLetters","description":"List the letters that have at least one entry in the Florio Italian-English dictionary. Public reference content; any signed-in Furnace ID may read it.","operationId":"post_api_v2_platform_read_florio.availableLetters","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/florio.searchHeadword":{"post":{"tags":["platform-v2"],"summary":"florio.searchHeadword","description":"Search the headwords of the Florio Italian-English dictionary, ignoring accents. Answers at most `limit` entries (default 20), and none for an empty query. Public reference content; any signed-in Furnace ID may read it.","operationId":"post_api_v2_platform_read_florio.searchHeadword","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string"},"limit":{"type":"number"}},"required":["query"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/aiChat.moderationEvents":{"post":{"tags":["platform-v2"],"summary":"aiChat.moderationEvents","description":"List the AI chat moderation checks recorded for one app, newest first: who wrote the message, whether it passed, the reason and a short preview. `onlyFlagged` keeps the ones that did not pass; `limit` defaults to 50 and is capped at 200. Needs `moderate:comments` in that app.","operationId":"post_api_v2_platform_read_aiChat.moderationEvents","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string"},"limit":{"type":"number"},"onlyFlagged":{"type":"boolean"}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/read/aiChat.moderationStats":{"post":{"tags":["platform-v2"],"summary":"aiChat.moderationStats","description":"Count the last 24 hours of AI chat moderation checks for one app: total, passed, flagged, and flagged by stage (input or output). `truncated` means the counts are lower bounds. Needs `moderate:comments` in that app.","operationId":"post_api_v2_platform_read_aiChat.moderationStats","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string"}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/page/comms.listSubscribers":{"post":{"tags":["platform-v2"],"summary":"comms.listSubscribers","description":"List the email subscribers of one app (`namespace`, its slug), newest first, one page at a time; `status` keeps one delivery status. Follow `continueCursor` until `isDone`. Needs `read:communications` in `communication-center`.","operationId":"post_api_v2_platform_page_comms.listSubscribers","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string","description":"Send as `cursor` to read the next page."},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"status":{"anyOf":[{"type":"string","const":"subscribed"},{"type":"string","const":"unsubscribed"},{"type":"string","const":"bounced"},{"type":"string","const":"complained"}]},"cursor":{"type":["string","null"],"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."},"limit":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/page/comms.listCampaigns":{"post":{"tags":["platform-v2"],"summary":"comms.listCampaigns","description":"List the email campaigns of one app (`namespace`, its slug), newest first, one page at a time; `status` keeps one campaign status. Follow `continueCursor` until `isDone`. Needs `read:communications` in `communication-center`.","operationId":"post_api_v2_platform_page_comms.listCampaigns","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string","description":"Send as `cursor` to read the next page."},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"status":{"anyOf":[{"type":"string","const":"draft"},{"type":"string","const":"sending"},{"type":"string","const":"sent"},{"type":"string","const":"failed"},{"type":"string","const":"partially_sent"}]},"cursor":{"type":["string","null"],"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."},"limit":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/page/workflow.listDefinitions":{"post":{"tags":["platform-v2"],"summary":"workflow.listDefinitions","description":"List the workflow definition summaries in one namespace, most recently updated first, one page at a time. Follow `continueCursor` until `isDone`. Needs `read:workflow_definitions` in that namespace.","operationId":"post_api_v2_platform_page_workflow.listDefinitions","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string","description":"Send as `cursor` to read the next page."},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"cursor":{"type":["string","null"],"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."},"limit":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/page/workflow.listRuns":{"post":{"tags":["platform-v2"],"summary":"workflow.listRuns","description":"List the workflow runs in one namespace, newest first, one page at a time; `workflowKey` and `status` narrow the list. Follow `continueCursor` until `isDone`. Needs `read:workflow_runs` in that namespace.","operationId":"post_api_v2_platform_page_workflow.listRuns","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string","description":"Send as `cursor` to read the next page."},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"workflowKey":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"queued"},{"type":"string","const":"running"},{"type":"string","const":"waiting"},{"type":"string","const":"completed"},{"type":"string","const":"failed"},{"type":"string","const":"canceled"}]},"cursor":{"type":["string","null"],"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."},"limit":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/page/workflow.listRunEvents":{"post":{"tags":["platform-v2"],"summary":"workflow.listRunEvents","description":"List one workflow run's durable event timeline in sequence order, one page at a time. Follow `continueCursor` until `isDone`. Needs `read:workflow_runs` in the run's namespace; a run that does not exist or that you cannot read is not found.","operationId":"post_api_v2_platform_page_workflow.listRunEvents","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["page","isDone","continueCursor"],"properties":{"page":{"type":"array","items":{}},"isDone":{"type":"boolean"},"continueCursor":{"type":"string","description":"Send as `cursor` to read the next page."},"splitCursor":{"type":["string","null"]},"pageStatus":{"type":["string","null"],"enum":["SplitRecommended","SplitRequired",null]}}}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"runId":{"type":"string","minLength":1},"cursor":{"type":["string","null"],"description":"Opaque cursor: the `continueCursor` of the previous page. Omit or send null for the first page."},"limit":{"type":"integer","minimum":1,"default":50,"description":"Page size, a whole number of at least 1; omitted or null means 50. A larger value than 200 is served as 200."}},"required":["runId"]}}}},"security":[{"bearerAuth":["api:read"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/contentLayout.update":{"post":{"tags":["platform-v2"],"summary":"contentLayout.update","description":"Patch a named content layout in place. Omitted fields keep their stored value; `description: null` clears it; `document` is the SDL layout document as JSON text and is validated before it is stored. The slug cannot change. Requires manage:content_layouts on the namespace.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_contentLayout.update","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":["string","null"]},"document":{"description":"The SDL layout document as JSON text; omit to keep the stored one.","type":"string"}},"required":["namespace","slug"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/contentLayout.delete":{"post":{"tags":["platform-v2"],"summary":"contentLayout.delete","description":"Delete a named content layout. Pages that name it fall back to their default layout; this cannot be undone. Requires manage:content_layouts on the namespace.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_contentLayout.delete","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string"},"slug":{"type":"string"}},"required":["namespace","slug"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/htmlApp.setCurrent":{"post":{"tags":["platform-v2"],"summary":"htmlApp.setCurrent","description":"Make an uploaded version of an HTML app current. Requires manage:app on the app. With `expectedCurrent`, the pointer moves only if that hash is still current, so a change made meanwhile in App Host is not replaced.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_htmlApp.setCurrent","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string"},"hash":{"type":"string","description":"The version to make current."},"expectedCurrent":{"description":"Move the pointer only if this hash is still current.","type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["appSlug","hash"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/htmlApp.dismissRun":{"post":{"tags":["platform-v2"],"summary":"htmlApp.dismissRun","description":"Hide one of your finished App Host Generate or Refine runs from your run list. Refuses a run that is still running or that isn't yours. Needs only a signed-in Furnace ID.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_htmlApp.dismissRun","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"runId":{"type":"string"}},"required":["runId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/htmlApp.shareByEmail":{"post":{"tags":["platform-v2"],"summary":"htmlApp.shareByEmail","description":"Give the person with this email the viewer or editor role on the app; sharing again changes the role. Requires manage:roles and assign:roles on the app. The answer is the same whether or not the address has a Furnace account, so it reveals nothing about who signs in. At most a few attempts an hour per caller.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_htmlApp.shareByEmail","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string"},"email":{"type":"string","description":"The email address of the person to share with."},"role":{"type":"string","enum":["viewer","editor"],"description":"viewer opens the app; editor may also change it."}},"required":["appSlug","email","role"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/htmlApp.unshare":{"post":{"tags":["platform-v2"],"summary":"htmlApp.unshare","description":"Remove the viewer and editor roles from the member, using a `memberId` from html_app_members. Requires manage:roles and assign:roles on the app. Refuses you and any admin. `stillHasAccess` reports access the person keeps another way.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_htmlApp.unshare","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string"},"memberId":{"type":"string"}},"required":["appSlug","memberId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/durableJob.retrigger":{"post":{"tags":["platform-v2"],"summary":"durableJob.retrigger","description":"Re-dispatch one recoverable durable job by id: reset its recovery budget and, for a failed job, set it running again so its orchestrator resumes from the last checkpoint. Refuses job types with no orchestrator and completed jobs. A server-side app function job also loses the access token it was given. It can re-run a user deletion or a data export, so read the job with ops_tasks_recent first. Requires *:* in system.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_durableJob.retrigger","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"taskId":{"type":"string"}},"required":["taskId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.update":{"post":{"tags":["platform-v2"],"summary":"media.update","description":"Change an image, file or audio asset’s displayName, description, tags (replaced, not merged) or visibility. Only the fields you send change; null counts as omitted. Answers the asset id. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.update","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"visibility":{"anyOf":[{"type":"string","const":"public"},{"type":"string","const":"protected"}]}},"required":["id"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.setAllowedNamespaces":{"post":{"tags":["platform-v2"],"summary":"media.setAllowedNamespaces","description":"Legacy form of media_set_usage_policy: a list of app namespaces restricts where the asset may be embedded; null or an empty list makes it library-only. Refused while published content in a namespace being dropped still uses the asset. Answers the asset id. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.setAllowedNamespaces","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"allowedNamespaces":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["id","allowedNamespaces"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.setUsagePolicy":{"post":{"tags":["platform-v2"],"summary":"media.setUsagePolicy","description":"Set where an image, file or audio asset may be embedded, independently of its visibility: `library-only`, `all` apps, or `restricted` to listed app namespaces. Refused while published content or a published gallery the new policy excludes still uses the asset. Answers the asset id. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.setUsagePolicy","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"usagePolicy":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"library-only"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"all"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"restricted"},"namespaces":{"type":"array","items":{"type":"string"}}},"required":["mode","namespaces"]}]}},"required":["id","usagePolicy"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.remove":{"post":{"tags":["platform-v2"],"summary":"media.remove","description":"Delete an image, file or audio asset and schedule its stored bytes for removal; this cannot be undone. Refused while a gallery still shows the asset. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.remove","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.batchRemove":{"post":{"tags":["platform-v2"],"summary":"media.batchRemove","description":"Delete every listed image, file or audio asset and schedule their stored bytes for removal; this cannot be undone. Ids that name no asset are skipped. Answers how many ids were sent. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.batchRemove","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.batchAddTags":{"post":{"tags":["platform-v2"],"summary":"media.batchAddTags","description":"Add tags to every listed image, file or audio asset, keeping the tags each already has. Ids that name no asset are skipped. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.batchAddTags","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["ids","tags"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.batchRemoveTags":{"post":{"tags":["platform-v2"],"summary":"media.batchRemoveTags","description":"Remove the listed tags from every listed image, file or audio asset; other tags stay. Ids that name no asset are skipped. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.batchRemoveTags","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["ids","tags"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.applyAiSuggestion":{"post":{"tags":["platform-v2"],"summary":"media.applyAiSuggestion","description":"Copy an image’s AI-suggested display name, description or tags onto the asset; choose which with the apply flags. Answers the asset id. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.applyAiSuggestion","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"applyDisplayName":{"type":"boolean"},"applyDescription":{"type":"boolean"},"applyTags":{"type":"boolean"}},"required":["id"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.updateVideo":{"post":{"tags":["platform-v2"],"summary":"media.updateVideo","description":"Change a video’s title, description, visibility, duration, thumbnailUrl or tags (replaced, not merged). Only the fields you send change; null counts as omitted. Answers the video id. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.updateVideo","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"visibility":{"anyOf":[{"type":"string","const":"public"},{"type":"string","const":"protected"}]},"duration":{"type":"number"},"thumbnailUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.setVideoAllowedNamespaces":{"post":{"tags":["platform-v2"],"summary":"media.setVideoAllowedNamespaces","description":"Legacy form of video_set_usage_policy: a list of app namespaces restricts where the video may be embedded; null or an empty list makes it library-only. Answers the video id. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.setVideoAllowedNamespaces","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"allowedNamespaces":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["id","allowedNamespaces"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.setVideoUsagePolicy":{"post":{"tags":["platform-v2"],"summary":"media.setVideoUsagePolicy","description":"Set where a video may be embedded, independently of its visibility: `library-only`, `all` apps, or `restricted` to listed app namespaces. Refused while published content the new policy excludes still uses the video. Answers the video id. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.setVideoUsagePolicy","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"usagePolicy":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"library-only"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"all"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"restricted"},"namespaces":{"type":"array","items":{"type":"string"}}},"required":["mode","namespaces"]}]}},"required":["id","usagePolicy"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.removeVideo":{"post":{"tags":["platform-v2"],"summary":"media.removeVideo","description":"Delete a video and its stream on the video host; this cannot be undone. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.removeVideo","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.batchRemoveVideos":{"post":{"tags":["platform-v2"],"summary":"media.batchRemoveVideos","description":"Delete every listed video and its stream on the video host; this cannot be undone. Ids that name no video are skipped. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.batchRemoveVideos","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.batchAddVideoTags":{"post":{"tags":["platform-v2"],"summary":"media.batchAddVideoTags","description":"Add tags to every listed video, keeping the tags each already has. Ids that name no video are skipped. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.batchAddVideoTags","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["ids","tags"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/media.batchRemoveVideoTags":{"post":{"tags":["platform-v2"],"summary":"media.batchRemoveVideoTags","description":"Remove the listed tags from every listed video; other tags stay. Ids that name no video are skipped. Requires media:admin in media-library.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_media.batchRemoveVideoTags","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["ids","tags"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.addSubscriber":{"post":{"tags":["platform-v2"],"summary":"comms.addSubscriber","description":"Subscribe an email address to an app’s list, or re-subscribe it; answers the subscriber id, the existing one when already subscribed. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.addSubscriber","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"email":{"type":"string","minLength":1},"source":{"anyOf":[{"type":"string","const":"manual"},{"type":"string","const":"signup"},{"type":"string","const":"migration"}]}},"required":["namespace","email","source"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.removeSubscriber":{"post":{"tags":["platform-v2"],"summary":"comms.removeSubscriber","description":"Unsubscribe an email address from an app’s list; answers its subscriber id, or null when it was not subscribed. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.removeSubscriber","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"email":{"type":"string","minLength":1}},"required":["namespace","email"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.updateSubscriberTags":{"post":{"tags":["platform-v2"],"summary":"comms.updateSubscriberTags","description":"Replace a subscriber’s tags; an unknown subscriber id changes nothing. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.updateSubscriberTags","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriberId":{"type":"string","minLength":1},"tags":{"type":"array","items":{"type":"string"}}},"required":["subscriberId","tags"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.createCampaign":{"post":{"tags":["platform-v2"],"summary":"comms.createCampaign","description":"Create a draft email campaign in an app; answers the campaign id. Nothing is sent until communications_campaigns_send. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.createCampaign","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"subject":{"type":"string","minLength":1},"previewText":{"type":"string"},"mdBody":{"type":"string"},"audienceTags":{"type":"array","items":{"type":"string"}}},"required":["namespace","subject"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.updateCampaign":{"post":{"tags":["platform-v2"],"summary":"comms.updateCampaign","description":"Change a draft campaign’s subject, preview text, Markdown body or audience tags; only the fields you send change, and null counts as omitted. Refused unless the campaign is a draft. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.updateCampaign","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"campaignId":{"type":"string","minLength":1},"subject":{"type":"string"},"previewText":{"type":"string"},"mdBody":{"type":"string"},"audienceTags":{"type":"array","items":{"type":"string"}}},"required":["campaignId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.deleteCampaign":{"post":{"tags":["platform-v2"],"summary":"comms.deleteCampaign","description":"Delete a draft campaign; this cannot be undone. Refused unless the campaign is a draft. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.deleteCampaign","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"campaignId":{"type":"string","minLength":1}},"required":["campaignId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.resetCampaignToDraft":{"post":{"tags":["platform-v2"],"summary":"comms.resetCampaignToDraft","description":"Return a failed campaign to draft so it can be edited and sent again. Refused unless the campaign failed. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.resetCampaignToDraft","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"campaignId":{"type":"string","minLength":1}},"required":["campaignId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.duplicateCampaign":{"post":{"tags":["platform-v2"],"summary":"comms.duplicateCampaign","description":"Copy a campaign into a new draft titled \"Copy of …\"; answers the new campaign id. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.duplicateCampaign","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"campaignId":{"type":"string","minLength":1}},"required":["campaignId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.createTemplate":{"post":{"tags":["platform-v2"],"summary":"comms.createTemplate","description":"Save a reusable campaign template (name, Markdown body, audience tags) for an app; answers the template id. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.createTemplate","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"mdBody":{"type":"string"},"audienceTags":{"type":"array","items":{"type":"string"}}},"required":["namespace","name","mdBody"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.deleteTemplate":{"post":{"tags":["platform-v2"],"summary":"comms.deleteTemplate","description":"Delete a campaign template; this cannot be undone. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.deleteTemplate","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"templateId":{"type":"string","minLength":1}},"required":["templateId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.setLegalConfig":{"post":{"tags":["platform-v2"],"summary":"comms.setLegalConfig","description":"Replace an app’s email legal footer: fields you omit are cleared, and null counts as omitted. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.setLegalConfig","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","minLength":1},"companyName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateRegion":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"unsubscribeNote":{"type":"string"}},"required":["namespace"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/comms.setEnabledNamespaces":{"post":{"tags":["platform-v2"],"summary":"comms.setEnabledNamespaces","description":"Replace the list of app namespaces the communication center is enabled for. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_comms.setEnabledNamespaces","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespaces":{"type":"array","items":{"type":"string"}}},"required":["namespaces"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/alert.adminCreate":{"post":{"tags":["platform-v2"],"summary":"alert.adminCreate","description":"Create a site-banner alert and answer its id. It is stored inactive: activate it with ops_alerts_activate, or give a future `activeFrom` (epoch ms) and it activates itself then. Omit `namespace` for a banner on every app. `isDismissible` defaults to true. A null optional field counts as omitted. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_alert.adminCreate","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string"},"message":{"type":"string"},"variant":{"anyOf":[{"type":"string","const":"info"},{"type":"string","const":"warning"},{"type":"string","const":"error"},{"type":"string","const":"success"}]},"namespace":{"type":"string"},"isDismissible":{"default":true,"type":"boolean"},"linkLabel":{"type":"string"},"linkUrl":{"type":"string"},"activeFrom":{"type":"number"},"expiresAt":{"type":"number"}},"required":["title","variant"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/alert.adminUpdate":{"post":{"tags":["platform-v2"],"summary":"alert.adminUpdate","description":"Replace a site-banner alert: send every field to keep. An omitted or null `message`, `linkLabel`, `linkUrl`, `activeFrom` or `expiresAt` is cleared. An alert without `namespace`, or with `isPlatformWide: true`, shows on every app. `isDismissible` defaults to true and `isPlatformWide` to false. A future `activeFrom` hides it until then. Changing its text, variant or link shows it again to people who dismissed it. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_alert.adminUpdate","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"message":{"type":"string"},"variant":{"anyOf":[{"type":"string","const":"info"},{"type":"string","const":"warning"},{"type":"string","const":"error"},{"type":"string","const":"success"}]},"isPlatformWide":{"default":false,"type":"boolean"},"namespace":{"type":"string"},"isDismissible":{"default":true,"type":"boolean"},"linkLabel":{"type":"string"},"linkUrl":{"type":"string"},"activeFrom":{"type":"number"},"expiresAt":{"type":"number"}},"required":["id","title","variant"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/alert.adminActivate":{"post":{"tags":["platform-v2"],"summary":"alert.adminActivate","description":"Show a site-banner alert now and cancel any scheduled activation. If it was hidden, people who dismissed it before see it again. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_alert.adminActivate","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/alert.adminDeactivate":{"post":{"tags":["platform-v2"],"summary":"alert.adminDeactivate","description":"Hide a site-banner alert now and cancel any scheduled activation. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_alert.adminDeactivate","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/alert.adminDelete":{"post":{"tags":["platform-v2"],"summary":"alert.adminDelete","description":"Delete a site-banner alert and cancel any scheduled activation. This cannot be undone. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_alert.adminDelete","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/broadcast.create":{"post":{"tags":["platform-v2"],"summary":"broadcast.create","description":"Create an empty draft notification broadcast and answer its id; fill it with notifications_update before notifications_send. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_broadcast.create","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/broadcast.update":{"post":{"tags":["platform-v2"],"summary":"broadcast.update","description":"Change a draft broadcast: title, plain-text body, optional SDL `content` (which needs a body as fallback), recipients (user subjects) or actions; only the fields you send change. Refused unless the broadcast is a draft. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_broadcast.update","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"broadcastId":{"type":"string","minLength":1},"title":{"type":"string"},"body":{"type":"string"},"content":{"description":"Optional static, display-only SDL detail. Keep body as the plain-text fallback.","type":"object","properties":{"kind":{"type":"string","const":"sdl"},"document":{}},"required":["kind","document"]},"recipientSubjects":{"type":"array","items":{"type":"string"}},"actions":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"path":{"type":"string"},"url":{"type":"string"}},"required":["label"]}}},"required":["broadcastId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/broadcast.delete":{"post":{"tags":["platform-v2"],"summary":"broadcast.delete","description":"Delete a draft broadcast; this cannot be undone, and a sent broadcast cannot be deleted. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_broadcast.delete","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"broadcastId":{"type":"string","minLength":1}},"required":["broadcastId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/write/broadcast.send":{"post":{"tags":["platform-v2"],"summary":"broadcast.send","description":"Send a draft broadcast: notify every recipient and mark it sent, which cannot be undone. Answers `recipientCount`. Refused unless the broadcast is a draft. Requires write:communications in communication-center.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_write_broadcast.send","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"broadcastId":{"type":"string","minLength":1}},"required":["broadcastId"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/action/htmlApp.create":{"post":{"tags":["platform-v2"],"summary":"htmlApp.create","description":"Create an HTML app, with sharing roles and a documents entity, and return its slug and current version hash. Requires create:apps in dev-launcher. The starter page becomes its first version unless `starter` is false; then `hash` is null until you upload a version.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_action_htmlApp.create","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string","description":"The app address: lowercase letters, digits and hyphens, 2 to 31 characters."},"displayName":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":500},"icon":{"type":"string"},"starter":{"description":"Store and select the starter page as the first version. Default true.","type":"boolean"}},"required":["appSlug","displayName"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}},"/api/v2/platform/action/htmlApp.putVersion":{"post":{"tags":["platform-v2"],"summary":"htmlApp.putVersion","description":"Store a new immutable version of an HTML app and return its SHA-256 `hash`, and whether it is now `current`. Requires manage:app on the app. HTML is limited to 3,000,000 UTF-8 bytes. Read the grounding (html_app_grounding) before writing one.\n\nSend `Idempotency-Key` to make a write retryable. The key is bound to the HTTP method, concrete path and query, and raw request body. Reusing it for a different request returns 400 with `code: idempotency_key_reuse`. A matching request that is still running returns 409 with `code: idempotency_in_progress` and `Retry-After: 5`; retry after that delay. Successful 2xx responses are replayable for 24 hours and include `Idempotency-Replayed: true` on replay. If the original response exceeds 256 KiB, later retries return 409 with `code: idempotency_replay_unavailable` instead of running the write again. Non-2xx responses are not retained.","operationId":"post_api_v2_platform_action_htmlApp.putVersion","responses":{"200":{"description":"Capability result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Bad request — invalid arguments or path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Authenticated but lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency state conflict. Use the response `code` to distinguish `idempotency_in_progress` from `idempotency_replay_unavailable`; `Retry-After` is present only while the original request is running.","headers":{"Retry-After":{"description":"Seconds to wait before retrying an in-progress request","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until the request may be retried","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional key for safely retrying this write. Keys are scoped to the platform service caller or to the PAT user (all PATs for one user share a scope).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appSlug":{"type":"string"},"html":{"type":"string","minLength":1,"description":"The HTML file, at most 3,000,000 UTF-8 bytes."},"note":{"type":"string","maxLength":1000},"makeCurrent":{"description":"Make the new version current. Default true; false only stores it.","type":"boolean"},"retention":{"description":"Keep this version for `ttlMs` milliseconds only, from 60,000 to 30 days; omit to keep it.","type":"object","properties":{"ttlMs":{"type":"integer","minimum":60000,"maximum":2592000000}},"required":["ttlMs"]}},"required":["appSlug","html"]}}}},"security":[{"bearerAuth":["api:write"]},{"oauth2":["full"]}]}}},"tags":[{"name":"system","description":"Cross-cutting auth and identity endpoints."},{"name":"me","description":""},{"name":"kvark","description":"Deprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved."},{"name":"content","description":"Content pages and nav trees: create, publish, version, reorder, access gates."},{"name":"content_layouts","description":""},{"name":"communications","description":""},{"name":"ledger","description":"Ledger bookkeeping: journal entries, customers, time, invoices, reports, attachments, and integrations. Deprecated: superseded by the generated v2 surface — POST /api/v2/<app>/<read|write>/<operation> with the input as the JSON body, and <app>_<operation> MCP tools. This v1 module is removed one release after clients moved."},{"name":"analytics","description":"Per-namespace analytics reads — overview, time series, top paths/referrers."},{"name":"studio","description":""},{"name":"marozzo","description":"Marozzo assistant — non-streaming chat turns and thread history."},{"name":"dictionaries","description":"Dual-lane search across Florio (1611) and Crusca (1612) historical Italian dictionaries."},{"name":"hero_promos","description":""},{"name":"media","description":""},{"name":"platform","description":""},{"name":"html-apps","description":""},{"name":"access","description":""},{"name":"feature_flags","description":""},{"name":"ops","description":""},{"name":"notifications","description":""},{"name":"embeddings","description":""},{"name":"web","description":""},{"name":"workflows","description":"Immutable workflow definitions and durable run control: publish, start, inspect, cancel, restart, events, and artifacts."},{"name":"kvark-v2","description":"Kvark operations on the generated v2 surface: POST /api/v2/kvark/<read|write>/<operation>, input as the JSON body."},{"name":"ledger-v2","description":"Ledger operations on the generated v2 surface: POST /api/v2/ledger/<read|write>/<operation>, input as the JSON body; actions are served at the mode they declare."},{"name":"platform-v2","description":""}]}