{ "openapi": "3.1.0", "info": { "title": "ReBrandOS Agent API", "version": "1.0.0", "description": "Key-authenticated REST API for agents and scripts. Send `Authorization: Bearer rbos_live_...`. Every request is limited to the key’s scopes and brands and to the live access of the person who created it, is rate limited, and is audited. Each key may make 300 requests a minute and schedule 10 posts a day by default. Errors are application/problem+json (RFC 9457)." }, "externalDocs": { "description": "Agent API guide", "url": "https://www.rebrandos.com/docs/api" }, "servers": [ { "url": "https://ops.rebrandos.com/api/agent/v1" } ], "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "rbos_live_ / rbos_test_", "description": "A ReBrandOS agent access key from Settings → Agent access keys." } }, "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. `code` is the stable machine-readable identifier; extra members depend on the code.", "required": [ "type", "title", "status", "code", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "https://www.rebrandos.com/docs/api#error-" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "examples": [ "brand_required", "draft_required", "channel_required", "invalid_scheduled_at", "scheduled_at_in_past", "draft_update_failed", "unsafe_url", "webhook_invalid", "at_least_one_scope_required", "scope_exceeds_parent", "brand_exceeds_parent", "ip_allowlist_exceeds_parent", "cannot_derive_from_subtoken", "expires_at_must_be_future", "expires_at_invalid", "agent_key_scope_invalid", "parent_expired", "parent_rotated", "keys_killed", "missing_key", "invalid_key", "not_found", "revoked", "expired", "rotated", "restriction_invalid", "parent_revoked", "entitlement_blocked", "killed", "ip_not_allowed", "workspace_deletion_pending", "insufficient_scope", "brand_not_permitted", "issuer_no_access", "issuer_cannot_write", "module_inactive", "parent_not_active", "draft_not_found", "webhook_not_found", "publish_job_not_found", "publish_job_not_cancellable", "idempotency_conflict", "idempotency_in_progress", "brandos_generation_retired", "payload_too_large", "provider_capacity_not_ready", "publish_not_ready", "rate_limited", "publish_cap_reached", "internal_error", "entitlement_unavailable" ], "description": "Stable machine-readable code. The documented codes are listed at https://www.rebrandos.com/docs/api#errors." }, "detail": { "type": "string" }, "hint": { "type": "string" }, "requiredScope": { "type": "string" }, "brandId": { "type": "string" }, "reason": { "type": "string" }, "limit": { "type": [ "integer", "null" ] }, "used": { "type": "integer" }, "resetAt": { "type": "string", "format": "date-time" }, "retryAfter": { "type": "integer", "description": "Unix time (seconds) when the rate-limit window resets." } }, "additionalProperties": true }, "WhoAmI": { "type": "object", "properties": { "ok": { "type": "boolean" }, "keyId": { "type": "string" }, "label": { "type": "string" }, "organizationId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "brands": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "null means every brand in the workspace." }, "expiresAt": { "type": "string", "format": "date-time" }, "env": { "type": "string", "enum": [ "live", "test" ] } } }, "Brand": { "type": "object", "properties": { "id": { "type": "string", "description": "Brand slug; use it as `brand` / `brandId`." }, "name": { "type": "string" }, "status": { "type": "string" } } }, "Account": { "type": "object", "properties": { "brandId": { "type": "string" }, "platform": { "type": "string", "description": "Use as the draft `channel`, for example linkedin." }, "account": { "type": "string" } } }, "Draft": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "brand": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "DraftSummary": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" } } }, "DraftCreate": { "type": "object", "required": [ "brand" ], "properties": { "brand": { "type": "string", "description": "Brand slug (`brandId` is accepted as an alias)." }, "title": { "type": "string", "description": "Internal title, never published." }, "content": { "type": "string", "description": "The post text." }, "channel": { "type": "string", "description": "Network to publish to, for example linkedin. Can also be given at publish time." }, "postType": { "type": "string", "default": "text" } } }, "DraftUpdate": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "channel": { "type": "string" }, "postType": { "type": "string" } } }, "PublishRequest": { "type": "object", "required": [ "draftId" ], "properties": { "draftId": { "type": "string" }, "channel": { "type": "string", "description": "Overrides the draft channel." }, "scheduledAt": { "type": "string", "format": "date-time", "description": "ISO 8601 with a time zone, in the future. Omit to schedule five minutes from now." }, "dryRun": { "type": "boolean", "description": "Return the plan without scheduling or counting against the daily cap." } } }, "DailyCap": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resetAt": { "type": "string", "format": "date-time" } } }, "PublishScheduled": { "type": "object", "properties": { "ok": { "type": "boolean" }, "scheduled": { "type": "object", "properties": { "scheduleId": { "type": "string" }, "draftId": { "type": "string" }, "brand": { "type": "string" }, "channel": { "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time" } } }, "dailyCap": { "$ref": "#/components/schemas/DailyCap" } } }, "PublishPending": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "const": "pending_approval" }, "pendingId": { "type": "string" }, "brand": { "type": "string" }, "channel": { "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time" }, "message": { "type": "string" } } }, "PublishDryRun": { "type": "object", "properties": { "ok": { "type": "boolean" }, "dryRun": { "type": "boolean", "const": true }, "plan": { "type": "object", "properties": { "draftId": { "type": "string" }, "brand": { "type": "string" }, "channel": { "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "providerCapacity": { "type": "object", "properties": { "enforced": { "type": "boolean" }, "ready": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object" } } } }, "dailyCap": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" } } } } } } }, "SubtokenRequest": { "type": "object", "properties": { "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Subset of the calling key’s scopes. Omit to inherit." }, "brandIds": { "type": "array", "items": { "type": "string" }, "description": "Subset of the calling key’s brands. Omit to inherit." }, "caps": { "type": "object", "additionalProperties": false, "properties": { "rateLimitPerMin": { "type": "integer" }, "publishesPerDay": { "type": "integer" }, "ipAllowlist": { "type": "array", "items": { "type": "string" } } }, "description": "Each cap is the lower of this value and the parent’s." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Clamped to the parent’s expiry." } } }, "Subtoken": { "type": "object", "properties": { "ok": { "type": "boolean" }, "token": { "type": "string", "description": "Shown once." }, "apiKey": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "brandIds": { "type": [ "array", "null" ], "items": { "type": "string" } }, "caps": { "type": "object" }, "expiresAt": { "type": "string", "format": "date-time" }, "env": { "type": "string" }, "parentKeyId": { "type": "string" } } } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "failureCount": { "type": "integer" }, "lastStatus": { "type": "string" }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string" }, "event_type": { "type": "string" }, "status_code": { "type": "integer" }, "ok": { "type": "integer", "enum": [ 0, 1 ] }, "attempts": { "type": "integer" }, "error": { "type": "string" }, "at": { "type": "string", "format": "date-time" } } }, "PublishJob": { "type": "object", "properties": { "id": { "type": "string" }, "brandId": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "scheduledAt": { "type": "string" }, "providerPostId": { "type": "string" } } }, "PublishReceipt": { "type": "object", "properties": { "id": { "type": "string" }, "brandId": { "type": "string" }, "provider": { "type": "string" }, "providerPostId": { "type": "string" }, "status": { "type": "string" }, "publishedAt": { "type": "string" } } }, "MediaAsset": { "type": "object", "properties": { "id": { "type": "string" }, "brandId": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "publicUrl": { "type": "string" } } } } }, "security": [ { "ApiKeyBearer": [] } ], "x-scopes": [ "profile:read", "brands:read", "brands:write", "accounts:read", "accounts:manage", "personas:read", "personas:write", "drafts:read", "drafts:write", "pillars:read", "pillars:write", "calendar:read", "schedule:read", "schedule:write", "analytics:read", "media:read", "media:write", "automations:read", "automations:write", "automations:execute", "publish:execute", "webhooks:manage" ], "paths": { "/whoami": { "get": { "summary": "Identity, scopes, brands and expiry of the calling key", "responses": { "200": { "description": "The calling key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmI" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/brands": { "get": { "summary": "Brands this key can reach", "x-required-scope": "brands:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "A page of brands.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor", "total" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/accounts": { "get": { "summary": "Connected accounts bound to brands this key can reach", "x-required-scope": "accounts:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "A page of accounts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor", "total" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drafts": { "get": { "summary": "List drafts", "x-required-scope": "drafts:read", "parameters": [ { "name": "brandId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "A page of drafts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor", "total" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Draft" } }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "summary": "Create a text draft", "x-required-scope": "drafts:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Optional. Replaying the same key with the same body returns the first response; a different body returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftCreate" } } } }, "responses": { "200": { "description": "Idempotent replay of an earlier create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "draft": { "$ref": "#/components/schemas/DraftSummary" } } } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "draft": { "$ref": "#/components/schemas/DraftSummary" } } } } } }, "400": { "description": "brand_required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "entitlement_blocked: the plan does not allow writes right now.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict or idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "entitlement_unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drafts/{id}": { "patch": { "summary": "Update a draft", "x-required-scope": "drafts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftUpdate" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "draft": { "$ref": "#/components/schemas/DraftSummary" } } } } } }, "400": { "description": "draft_update_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "entitlement_blocked: the plan does not allow writes right now.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "draft_not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "summary": "Update a draft (same as PATCH)", "x-required-scope": "drafts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftUpdate" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "draft": { "$ref": "#/components/schemas/DraftSummary" } } } } } }, "400": { "description": "draft_update_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "entitlement_blocked: the plan does not allow writes right now.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "draft_not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "summary": "Delete a draft", "x-required-scope": "drafts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deleted": { "type": "string" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "draft_not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/publish": { "post": { "summary": "Schedule a draft to publish", "description": "Schedules through the same pipeline as the dashboard. Each key may schedule 10 posts per UTC day. If the workspace requires approval for agent publishing, the request is parked for a person to approve and returns 202.", "x-required-scope": "publish:execute", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Optional. Replaying the same key with the same body returns the first response; a different body returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRequest" } } } }, "responses": { "200": { "description": "Dry-run plan, or an idempotent replay of an earlier response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PublishDryRun" }, { "$ref": "#/components/schemas/PublishScheduled" } ] } } } }, "201": { "description": "Scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishScheduled" } } } }, "202": { "description": "Waiting for a person to approve it in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishPending" } } } }, "400": { "description": "draft_required, channel_required, invalid_scheduled_at or scheduled_at_in_past", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "entitlement_blocked: the plan does not allow publishing right now.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "draft_not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict or idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "provider_capacity_not_ready or publish_not_ready. Nothing was scheduled.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited, or publish_cap_reached (resets 00:00 UTC).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "entitlement_unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subtokens": { "post": { "summary": "Mint a narrower sub-token for a sub-agent", "description": "No scope required. The child can only narrow the parent: scopes, brands, caps and expiry never exceed it, and revoking or rotating the parent disables the child. Sub-tokens cannot mint sub-tokens.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubtokenRequest" } } } }, "responses": { "201": { "description": "Created. The token is shown once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subtoken" } } } }, "400": { "description": "The request widens the parent or is invalid; see the error codes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks": { "get": { "summary": "List webhook subscriptions", "x-required-scope": "webhooks:manage", "responses": { "200": { "description": "Subscriptions and the events you can subscribe to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "availableEvents": { "type": "array", "items": { "type": "string", "enum": [ "draft.created", "draft.updated", "post.scheduled", "post.published", "post.needs_action", "post.failed", "key.revoked" ] } } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "summary": "Subscribe an https endpoint to lifecycle events", "x-required-scope": "webhooks:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "https on a public host." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "draft.created", "draft.updated", "post.scheduled", "post.published", "post.needs_action", "post.failed", "key.revoked" ] }, "description": "Omit or send [] for every event." } } } } } }, "responses": { "201": { "description": "Created. The signing secret is shown once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "webhook": { "$ref": "#/components/schemas/Webhook" }, "secret": { "type": "string" }, "signatureScheme": { "type": "string" } } } } } }, "400": { "description": "unsafe_url or webhook_invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}": { "delete": { "summary": "Delete a webhook subscription", "x-required-scope": "webhooks:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deleted": { "type": "string" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "webhook_not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "summary": "The 50 most recent delivery attempts for a subscription", "x-required-scope": "webhooks:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery log, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "webhook_not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/pillars": { "get": { "summary": "Content pillars of a brand", "x-required-scope": "pillars:read", "parameters": [ { "name": "brandId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." } ], "responses": { "200": { "description": "Pillars.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "brandId": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "brand_required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/brand-profile": { "get": { "summary": "A brand’s strategy profile (positioning, audience, voice, pillars)", "x-required-scope": "brands:read", "parameters": [ { "name": "brandId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." } ], "responses": { "200": { "description": "Profile, or null if the brand has none yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "brandId": { "type": "string" }, "profile": { "type": [ "object", "null" ] } } } } } }, "400": { "description": "brand_required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/content-outcomes": { "get": { "summary": "A brand’s content outcomes and the outcome catalog", "x-required-scope": "brands:read", "parameters": [ { "name": "brandId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." } ], "responses": { "200": { "description": "Outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "outcomes": { "type": "array", "items": { "type": "object" } }, "catalog": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "brand_required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/hook-devices": { "get": { "summary": "The hook-device catalog", "x-required-scope": "brands:read", "responses": { "200": { "description": "Catalog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "hookDevices": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/viral-formats": { "get": { "summary": "The post-format catalog, with a recommendation from the brand’s own results when brandId is given", "x-required-scope": "pillars:read", "parameters": [ { "name": "brandId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." } ], "responses": { "200": { "description": "Formats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "formats": { "type": "array", "items": { "type": "object" } }, "recommendation": { "type": [ "object", "null" ] } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics": { "get": { "summary": "Per-brand performance snapshots", "x-required-scope": "analytics:read", "parameters": [ { "name": "brandId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "A page of snapshots.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor", "total" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/publish-jobs": { "get": { "summary": "Scheduled and queued publish jobs", "x-required-scope": "schedule:read", "parameters": [ { "name": "brandId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "A page of jobs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor", "total" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublishJob" } }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/publish-jobs/{id}/cancel": { "post": { "summary": "Cancel a queued post before it starts publishing", "description": "Works whatever the subscription state, so a workspace that has become read-only can still stop queued posts.", "x-required-scope": "schedule:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "cancelled": { "type": "object", "properties": { "id": { "type": "string" }, "brandId": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "publish_job_not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "publish_job_not_cancellable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/publish-receipts": { "get": { "summary": "Publish outcomes reported by the networks", "x-required-scope": "analytics:read", "parameters": [ { "name": "brandId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "A page of receipts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor", "total" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublishReceipt" } }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/media": { "get": { "summary": "Media in the brand’s library", "x-required-scope": "media:read", "parameters": [ { "name": "brandId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Brand slug. A brand-restricted key may only name its own brands." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "A page of media.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor", "total" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaAsset" } }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, unknown, revoked, expired or rotated key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Paused workspace, IP outside the allowlist, missing scope, brand not permitted, or the issuing user lost access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } } }