{ "openapi": "3.1.0", "info": { "title": "PostMCP API", "version": "0.1.0", "summary": "Agent-first social publishing API for CLI, MCP, OpenClaw, scripts, and dashboard clients." }, "servers": [ { "url": "https://api.postmcp.dev" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List workspaces owned by a user.", "parameters": [ { "name": "owner_user_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspaces owned by the requested user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacesResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWorkspace", "summary": "Create a workspace billing and isolation unit.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } } }, "responses": { "200": { "description": "Workspace creation dry-run preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceDryRunResponse" } } } }, "201": { "description": "Workspace created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/workspaces/{workspace_id}": { "patch": { "operationId": "updateWorkspace", "summary": "Update workspace usage caps.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" } } } }, "responses": { "200": { "description": "Workspace updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteWorkspace", "summary": "Soft-delete a workspace.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace marked as deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWorkspaceResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/workspaces/{workspace_id}/export": { "get": { "operationId": "exportWorkspace", "summary": "Export workspace metadata for account data access requests.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace export payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceExportResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/users/{user_id}": { "delete": { "operationId": "deleteUserAccount", "summary": "Delete a user account by anonymizing the user and soft-deleting owned workspaces.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User account anonymized and owned workspaces soft-deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteUserAccountResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/users/{user_id}/export": { "get": { "operationId": "exportUserAccount", "summary": "Export user account metadata and owned workspaces for account data access requests.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User account export payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAccountExportResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/agents": { "get": { "operationId": "listAgents", "summary": "List agent identities for a workspace.", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace agent identities.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createAgent", "summary": "Register an agent identity and issue a one-time claim token.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "200": { "description": "Agent creation dry-run preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentDryRunResponse" } } } }, "201": { "description": "Agent registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent_id}": { "get": { "operationId": "getAgent", "summary": "Fetch an agent identity.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateAgent", "summary": "Update agent identity settings.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } } }, "responses": { "200": { "description": "Updated agent identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "revokeAgent", "summary": "Revoke an agent identity.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Revoked agent identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAgentResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent_id}/rotate-key": { "post": { "operationId": "rotateAgentKey", "summary": "Rotate an agent API key with a 24 hour overlap.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "New agent API key and retiring key overlap metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateAgentKeyResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent_id}/logs": { "get": { "operationId": "listAgentLogs", "summary": "List audit logs for one agent identity.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent audit log entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogsResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent_id}/usage": { "get": { "operationId": "getAgentUsage", "summary": "Fetch one agent's usage and spend cap state for a billing period.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "period_start", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Agent usage totals and spend cap state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUsageSummary" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/agents/claim": { "post": { "operationId": "claimAgent", "summary": "Exchange a one-time claim token for a scoped agent API key.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimAgentRequest" } } } }, "responses": { "200": { "description": "Claim token burned and API key issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimAgentResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/auth/api-keys": { "post": { "operationId": "createApiKey", "summary": "Create a scoped workspace API key.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "200": { "description": "API key creation dry-run preview or idempotent replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "201": { "description": "API key created. The token is returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/auth/api-keys/{api_key_id}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke a workspace API key.", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "API key revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeApiKeyResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accounts/connect": { "post": { "operationId": "beginAccountConnection", "summary": "Start an OAuth or credential account connection flow.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginAccountConnectionRequest" } } } }, "responses": { "200": { "description": "OAuth authorization URL, dry-run preview, or connected account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginAccountConnectionResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected accounts for a workspace.", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connected accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountsResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accounts/{account_id}": { "delete": { "operationId": "disconnectAccount", "summary": "Disconnect a connected account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Disconnected account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectAccountResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accounts/{account_id}/status": { "get": { "operationId": "getAccountStatus", "summary": "Fetch connected account status.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connected account status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accounts/{account_id}/capabilities": { "get": { "operationId": "getAccountCapabilities", "summary": "Fetch platform capabilities for a connected account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Platform capabilities for the connected account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformCapabilitiesResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accounts/oauth/callback": { "get": { "operationId": "completeAccountOAuth", "summary": "Complete an OAuth account connection callback.", "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Connected account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/posts/validate": { "post": { "operationId": "validatePost", "summary": "Validate post content against target platform constraints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatePostRequest" } } } }, "responses": { "200": { "description": "Validation result with repair hints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResult" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/posts/batch": { "post": { "operationId": "createPostBatch", "summary": "Create multiple post groups in one request.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostBatchRequest" } } } }, "responses": { "201": { "description": "Batch post groups created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostBatchResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/media": { "get": { "operationId": "listMedia", "summary": "List media assets for a workspace.", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace media assets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAssetsResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "uploadMedia", "summary": "Upload media and receive a stable media id.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadMediaRequest" } } } }, "responses": { "201": { "description": "Media uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadMediaResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/media/{media_id}": { "delete": { "operationId": "deleteMedia", "summary": "Delete a media asset from the workspace library.", "parameters": [ { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Media asset deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMediaResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Fetch workspace usage and spend cap state for a billing period.", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "period_start", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "workspace_monthly_spend_cap_cents", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Usage totals and spend cap state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/billing": { "get": { "operationId": "getBilling", "summary": "Fetch projected bill and spend cap state for a billing period.", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "period_start", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "workspace_monthly_spend_cap_cents", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "free_credit_cents", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 100 } } ], "responses": { "200": { "description": "Billing projection and spend cap state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummary" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/billing/checkout-sessions": { "post": { "operationId": "createBillingCheckoutSession", "summary": "Create a Stripe Checkout session for a workspace.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutSessionRequest" } } } }, "responses": { "200": { "description": "Stripe Checkout session URL for the workspace customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutSessionResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/billing/portal-sessions": { "post": { "operationId": "createBillingPortalSession", "summary": "Create a Stripe billing portal session for a workspace.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeBillingPortalSessionRequest" } } } }, "responses": { "200": { "description": "Stripe billing portal session URL for the workspace customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeBillingPortalSessionResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/billing/webhooks/stripe": { "post": { "operationId": "handleStripeBillingWebhook", "summary": "Accept a Stripe billing webhook after verifying its signature.", "security": [], "parameters": [ { "name": "Stripe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stripe webhook signature header containing timestamp and v1 HMAC signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Stripe billing webhook accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeBillingWebhookResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhooks/deliveries/{delivery_id}/replay": { "post": { "operationId": "replayWebhookDelivery", "summary": "Replay a stored webhook delivery.", "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Replayed webhook delivery status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/logs": { "get": { "operationId": "listLogs", "summary": "List workspace audit logs with optional actor filters.", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "actor_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user", "agent", "api_key", "cli", "mcp", "openclaw", "system" ] } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "retention_tier", "in": "query", "required": false, "schema": { "type": "string", "enum": ["free", "pro", "scale", "enterprise"] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["json", "csv"], "default": "json" } } ], "responses": { "200": { "description": "Workspace audit log entries.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuditLogsResponse" }, { "$ref": "#/components/schemas/AuditLogsCsvExportResponse" } ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/posts": { "get": { "operationId": "listPosts", "summary": "List scheduled posts for a calendar day.", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "timezone", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled posts for the requested local day.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostListResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createPost", "summary": "Create, publish, or schedule a post group.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostRequest" } } } }, "responses": { "201": { "description": "Post group created.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DryRunPostResponse" }, { "$ref": "#/components/schemas/SandboxPostResponse" }, { "$ref": "#/components/schemas/PostStatusResponse" } ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/posts/{post_group_id}": { "get": { "operationId": "getPost", "summary": "Fetch post group status.", "parameters": [ { "name": "post_group_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post group status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatusResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteScheduledPost", "summary": "Cancel a scheduled post group.", "parameters": [ { "name": "post_group_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Cancelled post group status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPostResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/posts/{post_group_id}/retry": { "post": { "operationId": "retryPost", "summary": "Retry a failed post group.", "parameters": [ { "name": "post_group_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retried post group status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryPostResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1 } } }, "responses": { "Error": { "description": "PostMCP error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostMCPError" } } } } }, "schemas": { "AgentScope": { "type": "string", "enum": [ "posts.read", "posts.draft", "posts.schedule", "posts.publish", "media.upload", "accounts.read", "accounts.write", "usage.read", "logs.read", "api_keys.write" ] }, "AgentDefaultMode": { "type": "string", "enum": ["dry_run", "draft", "requires_confirmation", "allow_publish"] }, "Workspace": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug", "owner_user_id", "stripe_customer_id", "default_timezone", "free_monthly_credit_cents", "monthly_spend_cap_cents", "monthly_x_url_post_cap", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^wrk_" }, "name": { "type": "string" }, "slug": { "type": "string" }, "owner_user_id": { "type": "string" }, "stripe_customer_id": { "type": "string" }, "default_timezone": { "type": "string" }, "free_monthly_credit_cents": { "type": "integer", "minimum": 0 }, "monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "monthly_x_url_post_cap": { "type": "integer", "minimum": 0 }, "commit_pack_id": { "type": "string" }, "status": { "type": "string", "enum": ["active", "paused", "deleted"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateWorkspaceRequest": { "type": "object", "additionalProperties": false, "required": ["owner_user_id", "name"], "properties": { "owner_user_id": { "type": "string" }, "name": { "type": "string" }, "default_timezone": { "type": "string", "default": "UTC" }, "free_monthly_credit_cents": { "type": "integer", "minimum": 0, "default": 100 }, "monthly_spend_cap_cents": { "type": "integer", "minimum": 0, "default": 0 }, "monthly_x_url_post_cap": { "type": "integer", "minimum": 0, "default": 0 }, "commit_pack_id": { "type": "string" }, "dry_run": { "type": "boolean" } } }, "UpdateWorkspaceRequest": { "type": "object", "additionalProperties": false, "properties": { "monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "monthly_x_url_post_cap": { "type": "integer", "minimum": 0 }, "dry_run": { "type": "boolean" } } }, "WorkspaceResponse": { "type": "object", "additionalProperties": false, "required": ["workspace"], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } } }, "DeleteWorkspaceResponse": { "$ref": "#/components/schemas/WorkspaceResponse" }, "WorkspaceExportResponse": { "type": "object", "additionalProperties": false, "required": ["exported_at", "workspace"], "properties": { "exported_at": { "type": "string", "format": "date-time" }, "workspace": { "$ref": "#/components/schemas/Workspace" } } }, "WorkspaceUser": { "type": "object", "additionalProperties": false, "required": ["id", "email", "created_at", "updated_at"], "properties": { "id": { "type": "string" }, "clerk_user_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "display_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean" } } }, "UserAccountExportResponse": { "type": "object", "additionalProperties": false, "required": ["exported_at", "user", "owned_workspaces"], "properties": { "exported_at": { "type": "string", "format": "date-time" }, "user": { "$ref": "#/components/schemas/WorkspaceUser" }, "owned_workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } } }, "DeleteUserAccountResponse": { "type": "object", "additionalProperties": false, "required": ["user", "deleted_workspaces"], "properties": { "user": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceUser" }, { "type": "object", "required": ["deleted"], "properties": { "deleted": { "const": true } } } ] }, "deleted_workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } } }, "UpdateWorkspaceResponse": { "oneOf": [ { "$ref": "#/components/schemas/WorkspaceResponse" }, { "$ref": "#/components/schemas/UpdateWorkspaceDryRunResponse" } ] }, "UpdateWorkspaceDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_update"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "workspaces.update_caps" }, "request": { "type": "object", "additionalProperties": false, "required": ["workspace_id"], "properties": { "workspace_id": { "type": "string" }, "monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "monthly_x_url_post_cap": { "type": "integer", "minimum": 0 } } }, "would_update": { "type": "object", "additionalProperties": false, "required": ["workspace"], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } } } } }, "CreateWorkspaceDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_create"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "workspaces.create" }, "request": { "type": "object", "additionalProperties": false, "required": [ "owner_user_id", "name", "default_timezone", "free_monthly_credit_cents", "monthly_spend_cap_cents", "monthly_x_url_post_cap" ], "properties": { "owner_user_id": { "type": "string" }, "name": { "type": "string" }, "default_timezone": { "type": "string" }, "free_monthly_credit_cents": { "type": "integer", "minimum": 0 }, "monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "monthly_x_url_post_cap": { "type": "integer", "minimum": 0 }, "commit_pack_id": { "type": "string" } } }, "would_create": { "type": "object", "additionalProperties": false, "required": ["workspace", "sandbox_accounts"], "properties": { "workspace": { "type": "object", "additionalProperties": false, "required": [ "name", "slug", "owner_user_id", "default_timezone", "free_monthly_credit_cents", "monthly_spend_cap_cents", "monthly_x_url_post_cap", "status" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "owner_user_id": { "type": "string" }, "default_timezone": { "type": "string" }, "free_monthly_credit_cents": { "type": "integer", "minimum": 0 }, "monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "monthly_x_url_post_cap": { "type": "integer", "minimum": 0 }, "commit_pack_id": { "type": "string" }, "status": { "type": "string", "enum": ["active"] } } }, "sandbox_accounts": { "type": "object", "additionalProperties": false, "required": ["count", "platforms"], "properties": { "count": { "type": "integer", "minimum": 0 }, "platforms": { "type": "array", "items": { "type": "string" } } } } } } } }, "WorkspacesResponse": { "type": "object", "additionalProperties": false, "required": ["workspaces"], "properties": { "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } } }, "Agent": { "type": "object", "additionalProperties": false, "required": [ "id", "workspace_id", "name", "scopes", "default_mode", "status" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } }, "default_mode": { "$ref": "#/components/schemas/AgentDefaultMode" }, "status": { "type": "string", "enum": ["active", "revoked"] } } }, "CreateAgentRequest": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "owner_user_id", "name", "scopes", "default_mode" ], "properties": { "workspace_id": { "type": "string" }, "owner_user_id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "scopes": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AgentScope" } }, "default_mode": { "$ref": "#/components/schemas/AgentDefaultMode" }, "account_allowlist": { "type": "array", "items": { "type": "string" } }, "rate_limit_per_minute": { "type": "integer", "minimum": 1 }, "posts_per_day_cap": { "type": "integer", "minimum": 1 }, "monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "monthly_x_url_post_cap": { "type": "integer", "minimum": 0 }, "webhook_url": { "type": "string", "format": "uri" }, "showcase_opt_in": { "type": "boolean" }, "dry_run": { "type": "boolean" } } }, "UpdateAgentRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "scopes": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AgentScope" } }, "default_mode": { "$ref": "#/components/schemas/AgentDefaultMode" }, "account_allowlist": { "type": "array", "items": { "type": "string" } }, "rate_limit_per_minute": { "type": "integer", "minimum": 1 }, "posts_per_day_cap": { "type": "integer", "minimum": 1 }, "monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "monthly_x_url_post_cap": { "type": "integer", "minimum": 0 }, "webhook_url": { "type": "string", "format": "uri" }, "showcase_opt_in": { "type": "boolean" }, "dry_run": { "type": "boolean" } } }, "AgentResponse": { "type": "object", "additionalProperties": false, "required": ["agent"], "properties": { "agent": { "$ref": "#/components/schemas/Agent" } } }, "UpdateAgentResponse": { "oneOf": [ { "$ref": "#/components/schemas/AgentResponse" }, { "$ref": "#/components/schemas/UpdateAgentDryRunResponse" } ] }, "UpdateAgentDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_update"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "agents.update" }, "request": { "type": "object", "additionalProperties": true, "required": ["agent_id"], "properties": { "agent_id": { "type": "string" } } }, "would_update": { "type": "object", "additionalProperties": false, "required": ["agent"], "properties": { "agent": { "$ref": "#/components/schemas/Agent" } } } } }, "RevokeAgentResponse": { "oneOf": [ { "$ref": "#/components/schemas/AgentResponse" }, { "$ref": "#/components/schemas/RevokeAgentDryRunResponse" } ] }, "RevokeAgentDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_revoke"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "agents.revoke" }, "request": { "type": "object", "additionalProperties": false, "required": ["agent_id"], "properties": { "agent_id": { "type": "string" } } }, "would_revoke": { "type": "object", "additionalProperties": false, "required": ["agent"], "properties": { "agent": { "$ref": "#/components/schemas/Agent" } } } } }, "AgentsResponse": { "type": "object", "additionalProperties": false, "required": ["agents"], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } }, "RotateAgentKeyResponse": { "oneOf": [ { "$ref": "#/components/schemas/RotateAgentKeySuccessResponse" }, { "$ref": "#/components/schemas/RotateAgentKeyDryRunResponse" } ] }, "RotateAgentKeySuccessResponse": { "type": "object", "additionalProperties": false, "required": ["agent", "api_key", "retiring_api_keys"], "properties": { "agent": { "$ref": "#/components/schemas/Agent" }, "api_key": { "$ref": "#/components/schemas/IssuedAgentApiKey" }, "retiring_api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/RetiringAgentApiKey" } } } }, "RotateAgentKeyDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_rotate"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "agents.rotate_key" }, "request": { "type": "object", "additionalProperties": false, "required": ["agent_id"], "properties": { "agent_id": { "type": "string" } } }, "would_rotate": { "type": "object", "additionalProperties": false, "required": ["agent", "api_key", "retiring_api_keys"], "properties": { "agent": { "$ref": "#/components/schemas/Agent" }, "api_key": { "type": "object", "additionalProperties": false, "required": ["returned_once", "prefix", "scopes"], "properties": { "returned_once": { "type": "boolean", "const": true }, "prefix": { "type": "string", "const": "pmcp_key_" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } } } }, "retiring_api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/RetiringAgentApiKey" } } } } } }, "IssuedAgentApiKey": { "type": "object", "additionalProperties": false, "required": ["id", "token", "scopes"], "properties": { "id": { "type": "string" }, "token": { "type": "string", "pattern": "^pmcp_key_" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } } } }, "RetiringAgentApiKey": { "type": "object", "additionalProperties": false, "required": ["id", "expires_at"], "properties": { "id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "CreateAgentResponse": { "type": "object", "additionalProperties": false, "required": ["agent", "claim_token"], "properties": { "agent": { "$ref": "#/components/schemas/Agent" }, "claim_token": { "type": "object", "additionalProperties": false, "required": ["token", "expires_at"], "properties": { "token": { "type": "string", "pattern": "^pmcp_claim_" }, "expires_at": { "type": "string", "format": "date-time" } } } } }, "CreateAgentDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_create"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "agents.create" }, "request": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "owner_user_id", "name", "scopes", "default_mode" ], "properties": { "workspace_id": { "type": "string" }, "owner_user_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } }, "default_mode": { "$ref": "#/components/schemas/AgentDefaultMode" } } }, "would_create": { "type": "object", "additionalProperties": false, "required": ["agent", "claim_token"], "properties": { "agent": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "name", "scopes", "default_mode", "status" ], "properties": { "workspace_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } }, "default_mode": { "$ref": "#/components/schemas/AgentDefaultMode" }, "status": { "type": "string", "enum": ["active"] } } }, "claim_token": { "type": "object", "additionalProperties": false, "required": ["returned_once", "expires_in_seconds", "prefix"], "properties": { "returned_once": { "type": "boolean", "const": true }, "expires_in_seconds": { "type": "integer", "minimum": 1 }, "prefix": { "type": "string", "const": "pmcp_claim_" } } } } } } }, "ClaimAgentRequest": { "type": "object", "additionalProperties": false, "required": ["claim_token"], "properties": { "claim_token": { "type": "string", "pattern": "^pmcp_claim_" }, "dry_run": { "type": "boolean" } } }, "ClaimAgentResponse": { "oneOf": [ { "$ref": "#/components/schemas/ClaimAgentSuccessResponse" }, { "$ref": "#/components/schemas/ClaimAgentDryRunResponse" } ] }, "ClaimAgentSuccessResponse": { "type": "object", "additionalProperties": false, "required": ["agent", "api_key"], "properties": { "agent": { "$ref": "#/components/schemas/Agent" }, "api_key": { "type": "object", "additionalProperties": false, "required": ["id", "token", "scopes"], "properties": { "id": { "type": "string" }, "token": { "type": "string", "pattern": "^pmcp_key_" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } } } } } }, "ClaimAgentDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_claim"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "agents.claim" }, "request": { "type": "object", "additionalProperties": false, "required": ["claim_token"], "properties": { "claim_token": { "type": "object", "additionalProperties": false, "required": ["prefix", "redacted"], "properties": { "prefix": { "type": "string", "const": "pmcp_claim_" }, "redacted": { "type": "boolean", "const": true } } } } }, "would_claim": { "type": "object", "additionalProperties": false, "required": ["agent", "api_key", "claim_token"], "properties": { "agent": { "$ref": "#/components/schemas/Agent" }, "api_key": { "type": "object", "additionalProperties": false, "required": ["returned_once", "prefix", "scopes"], "properties": { "returned_once": { "type": "boolean", "const": true }, "prefix": { "type": "string", "const": "pmcp_key_" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } } } }, "claim_token": { "type": "object", "additionalProperties": false, "required": ["would_be_marked_used"], "properties": { "would_be_marked_used": { "type": "boolean", "const": true } } } } } } }, "CreateApiKeyRequest": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "name", "scopes"], "properties": { "workspace_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AgentScope" } }, "dry_run": { "type": "boolean" } } }, "CreateApiKeyResponse": { "oneOf": [ { "$ref": "#/components/schemas/CreateApiKeyCreatedResponse" }, { "$ref": "#/components/schemas/CreateApiKeyDryRunResponse" } ] }, "CreateApiKeyCreatedResponse": { "type": "object", "additionalProperties": false, "required": ["api_key"], "properties": { "api_key": { "$ref": "#/components/schemas/ApiKey" }, "token": { "type": "string", "pattern": "^pmcp_key_" } } }, "CreateApiKeyDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_create"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "api_keys.create" }, "request": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "name", "scopes"], "properties": { "workspace_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AgentScope" } } } }, "would_create": { "type": "object", "additionalProperties": false, "required": ["api_key", "token"], "properties": { "api_key": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "name", "scopes", "status"], "properties": { "workspace_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } }, "status": { "type": "string", "enum": ["active"] } } }, "token": { "type": "object", "additionalProperties": false, "required": ["returned_once", "prefix"], "properties": { "returned_once": { "type": "boolean", "const": true }, "prefix": { "type": "string", "const": "pmcp_key_" } } } } } } }, "RevokeApiKeyResponse": { "oneOf": [ { "$ref": "#/components/schemas/RevokeApiKeyRevokedResponse" }, { "$ref": "#/components/schemas/RevokeApiKeyDryRunResponse" } ] }, "RevokeApiKeyRevokedResponse": { "type": "object", "additionalProperties": false, "required": ["api_key"], "properties": { "api_key": { "$ref": "#/components/schemas/ApiKey" } } }, "RevokeApiKeyDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_revoke"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "api_keys.revoke" }, "request": { "type": "object", "additionalProperties": false, "required": ["api_key_id"], "properties": { "api_key_id": { "type": "string" } } }, "would_revoke": { "type": "object", "additionalProperties": false, "required": ["api_key"], "properties": { "api_key": { "$ref": "#/components/schemas/ApiKey" } } } } }, "ApiKey": { "type": "object", "additionalProperties": false, "required": [ "id", "workspace_id", "name", "scopes", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentScope" } }, "status": { "type": "string", "enum": ["active", "revoked"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time" } } }, "BeginAccountConnectionRequest": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "platform"], "properties": { "workspace_id": { "type": "string" }, "platform": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "credentials": { "type": "object", "additionalProperties": false, "description": "Private-beta direct credential connection. Currently supported for Bluesky app passwords.", "required": ["identifier", "app_password"], "properties": { "identifier": { "type": "string" }, "app_password": { "type": "string", "format": "password" }, "display_name": { "type": "string" } } }, "dry_run": { "type": "boolean" } } }, "BeginAccountConnectionResponse": { "oneOf": [ { "$ref": "#/components/schemas/BeginAccountConnectionStartResponse" }, { "$ref": "#/components/schemas/ConnectedAccountResultResponse" }, { "$ref": "#/components/schemas/BeginAccountConnectionDryRunResponse" } ] }, "BeginAccountConnectionStartResponse": { "type": "object", "additionalProperties": false, "required": ["authorization_url", "state"], "properties": { "authorization_url": { "type": "string", "format": "uri" }, "state": { "type": "string" } } }, "BeginAccountConnectionDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "accounts.connect" }, "request": { "$ref": "#/components/schemas/BeginAccountConnectionRequest" }, "would_start_oauth": { "type": "object", "additionalProperties": false, "required": ["platform", "status"], "properties": { "platform": { "type": "string" }, "status": { "type": "string", "enum": ["pending"] } } }, "would_connect_credentials": { "type": "object", "additionalProperties": false, "required": ["platform", "external_account_id", "status"], "properties": { "platform": { "type": "string", "enum": ["bluesky"] }, "external_account_id": { "type": "string" }, "status": { "type": "string", "enum": ["connected"] } } } } }, "ConnectedAccountResponse": { "oneOf": [ { "$ref": "#/components/schemas/ConnectedAccountResultResponse" }, { "$ref": "#/components/schemas/OAuthCallbackDryRunResponse" } ] }, "ConnectedAccountResultResponse": { "type": "object", "additionalProperties": false, "required": ["account"], "properties": { "account": { "$ref": "#/components/schemas/ConnectedAccount" } } }, "OAuthCallbackDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_complete"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "accounts.oauth_callback" }, "request": { "type": "object", "additionalProperties": false, "required": ["state", "code"], "properties": { "state": { "type": "string" }, "code": { "type": "string" } } }, "would_complete": { "type": "object", "additionalProperties": false, "required": ["account"], "properties": { "account": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "platform", "status"], "properties": { "workspace_id": { "type": "string" }, "platform": { "type": "string" }, "status": { "const": "connected" } } } } } } }, "DisconnectAccountResponse": { "oneOf": [ { "$ref": "#/components/schemas/ConnectedAccountResponse" }, { "$ref": "#/components/schemas/DisconnectAccountDryRunResponse" } ] }, "DisconnectAccountDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_disconnect"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "accounts.disconnect" }, "request": { "type": "object", "additionalProperties": false, "required": ["account_id"], "properties": { "account_id": { "type": "string" } } }, "would_disconnect": { "type": "object", "additionalProperties": false, "required": ["account"], "properties": { "account": { "$ref": "#/components/schemas/ConnectedAccount" } } } } }, "ConnectedAccountsResponse": { "type": "object", "additionalProperties": false, "required": ["accounts"], "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectedAccount" } } } }, "ConnectedAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "workspace_id", "platform", "external_account_id", "display_name", "permissions", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "platform": { "type": "string" }, "external_account_id": { "type": "string" }, "display_name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "connected", "needs_reauth", "rate_limited", "disabled", "error", "pending_review" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PlatformCapabilitiesResponse": { "type": "object", "additionalProperties": false, "required": ["account_id", "platform", "capabilities"], "properties": { "account_id": { "type": "string" }, "platform": { "type": "string" }, "capabilities": { "$ref": "#/components/schemas/PlatformCapabilities" } } }, "PlatformCapabilities": { "type": "object", "additionalProperties": false, "required": [ "supports_text", "supports_images", "supports_video", "supports_threads", "supports_native_scheduling" ], "properties": { "supports_text": { "type": "boolean" }, "supports_images": { "type": "boolean" }, "supports_video": { "type": "boolean" }, "supports_threads": { "type": "boolean" }, "supports_native_scheduling": { "type": "boolean" }, "character_limit": { "type": "integer", "minimum": 1 }, "max_media_items": { "type": "integer", "minimum": 1 }, "max_video_duration_seconds": { "type": "integer", "minimum": 1 } } }, "ValidatePostRequest": { "type": "object", "additionalProperties": false, "required": ["text", "targets"], "properties": { "text": { "type": "string" }, "media_ids": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["platform"], "properties": { "platform": { "type": "string" } } } } } }, "ValidationResult": { "type": "object", "additionalProperties": false, "required": ["ok", "errors", "warnings"], "properties": { "ok": { "type": "boolean" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/PostMCPError" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PostMCPError" } }, "proposed_fixes": { "type": "object", "additionalProperties": false, "required": ["per_platform"], "properties": { "per_platform": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } } } } }, "SandboxAccountBehavior": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": ["mode"], "properties": { "mode": { "const": "always_succeed" } } }, { "type": "object", "additionalProperties": false, "required": ["mode"], "properties": { "mode": { "const": "always_fail" } } }, { "type": "object", "additionalProperties": false, "required": ["mode", "n"], "properties": { "mode": { "const": "fail_after_n" }, "n": { "type": "integer", "minimum": 0 } } }, { "type": "object", "additionalProperties": false, "required": ["mode"], "properties": { "mode": { "const": "needs_reauth" } } }, { "type": "object", "additionalProperties": false, "required": ["mode", "n"], "properties": { "mode": { "const": "rate_limit_after_n" }, "n": { "type": "integer", "minimum": 0 } } }, { "type": "object", "additionalProperties": false, "required": ["mode", "delayMs"], "properties": { "mode": { "const": "slow_response_ms" }, "delayMs": { "type": "integer", "minimum": 0 } } }, { "type": "object", "additionalProperties": false, "required": ["mode"], "properties": { "mode": { "const": "media_too_large" } } }, { "type": "object", "additionalProperties": false, "required": ["mode"], "properties": { "mode": { "const": "text_too_long" } } } ] }, "CreatePostRequest": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "created_by_type", "created_by_id", "text", "targets" ], "properties": { "workspace_id": { "type": "string" }, "created_by_type": { "type": "string", "enum": ["user", "agent", "api_key", "cli", "mcp", "openclaw"] }, "created_by_id": { "type": "string" }, "text": { "type": "string" }, "media_ids": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["platform", "connected_account_id"], "properties": { "platform": { "type": "string" }, "connected_account_id": { "type": "string" }, "sandbox_behavior": { "$ref": "#/components/schemas/SandboxAccountBehavior" } } } }, "scheduled_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean" }, "dry_run": { "type": "boolean" }, "wait": { "type": "boolean", "description": "Wait for synchronous completion when the transport supports it; scheduled posts still return queued status." }, "webhook_url": { "type": "string", "format": "uri", "description": "Per-request callback URL for post lifecycle events." }, "auto_fix": { "oneOf": [ { "type": "boolean", "description": "Apply all proposed fixes when true; fail without applying fixes when false." }, { "type": "array", "description": "Apply only the named proposed fixes.", "items": { "type": "string" } } ] }, "workspace_monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "free_credit_cents": { "type": "integer", "minimum": 0, "description": "Workspace monthly free credit available before paid spend cap enforcement." }, "agent_identity_id": { "type": "string" }, "agent_monthly_spend_cap_cents": { "type": "integer", "minimum": 0 }, "period_start": { "type": "string", "format": "date-time" } } }, "CreatePostBatchRequest": { "type": "object", "additionalProperties": false, "required": ["posts"], "properties": { "posts": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CreatePostRequest" } } } }, "CreatePostBatchResponse": { "type": "object", "additionalProperties": false, "required": ["posts"], "properties": { "posts": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DryRunPostResponse" }, { "$ref": "#/components/schemas/SandboxPostResponse" }, { "$ref": "#/components/schemas/PostStatusResponse" } ] } } } }, "UploadMediaRequest": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "filename", "mime_type", "content_base64"], "properties": { "workspace_id": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "content_base64": { "type": "string", "contentEncoding": "base64" }, "sandbox": { "type": "boolean" }, "dry_run": { "type": "boolean" } } }, "UploadMediaResponse": { "oneOf": [ { "$ref": "#/components/schemas/UploadMediaStoredResponse" }, { "$ref": "#/components/schemas/UploadMediaDryRunResponse" } ] }, "UploadMediaStoredResponse": { "type": "object", "additionalProperties": false, "required": ["media"], "properties": { "media": { "$ref": "#/components/schemas/MediaAsset" } } }, "UploadMediaDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_upload"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "media.upload" }, "request": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "filename", "mime_type", "sandbox", "content_base64_provided" ], "properties": { "workspace_id": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "sandbox": { "type": "boolean" }, "content_base64_provided": { "type": "boolean" } } }, "would_upload": { "type": "object", "additionalProperties": false, "required": ["media"], "properties": { "media": { "type": "object", "additionalProperties": false, "required": [ "filename", "mime_type", "byte_size", "sandbox", "status" ], "properties": { "filename": { "type": "string" }, "mime_type": { "type": "string" }, "byte_size": { "type": "integer" }, "sandbox": { "type": "boolean" }, "status": { "type": "string", "enum": ["ready"] } } } } } } }, "DeleteMediaResponse": { "oneOf": [ { "$ref": "#/components/schemas/UploadMediaStoredResponse" }, { "$ref": "#/components/schemas/DeleteMediaDryRunResponse" } ] }, "DeleteMediaDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_delete"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "media.delete" }, "request": { "type": "object", "additionalProperties": false, "required": ["media_id"], "properties": { "media_id": { "type": "string" } } }, "would_delete": { "type": "object", "additionalProperties": false, "required": ["media"], "properties": { "media": { "type": "object", "additionalProperties": false, "required": [ "id", "workspace_id", "filename", "mime_type", "byte_size", "sandbox", "status" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "byte_size": { "type": "integer" }, "sandbox": { "type": "boolean" }, "status": { "type": "string", "enum": ["deleted"] } } } } } } }, "MediaAssetsResponse": { "type": "object", "additionalProperties": false, "required": ["media"], "properties": { "media": { "type": "array", "items": { "$ref": "#/components/schemas/MediaAsset" } } } }, "MediaAsset": { "type": "object", "additionalProperties": false, "required": [ "id", "workspace_id", "filename", "mime_type", "byte_size", "sandbox", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^med_" }, "workspace_id": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "byte_size": { "type": "integer", "minimum": 0 }, "sandbox": { "type": "boolean" }, "status": { "type": "string", "enum": ["uploaded", "ready", "failed", "deleted"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DryRunPostResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "status", "validation", "preview"], "properties": { "dry_run": { "const": true }, "status": { "const": "validated" }, "validation": { "$ref": "#/components/schemas/ValidationResult" }, "preview": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "text", "media_ids", "targets", "sandbox" ], "properties": { "workspace_id": { "type": "string" }, "text": { "type": "string" }, "media_ids": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["platform", "connected_account_id"], "properties": { "platform": { "type": "string" }, "connected_account_id": { "type": "string" }, "sandbox_behavior": { "$ref": "#/components/schemas/SandboxAccountBehavior" } } } }, "scheduled_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean" } } } } }, "SandboxPostResponse": { "type": "object", "additionalProperties": false, "required": ["sandbox", "post_group_id", "status", "results"], "properties": { "sandbox": { "const": true }, "post_group_id": { "type": "string" }, "status": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["platform", "status", "external_url"], "properties": { "platform": { "type": "string" }, "status": { "type": "string" }, "external_url": { "type": "string", "format": "uri" } } } } } }, "PostStatusResponse": { "type": "object", "additionalProperties": false, "required": [ "post_group_id", "status", "sandbox", "media_ids", "targets" ], "properties": { "post_group_id": { "type": "string" }, "status": { "type": "string" }, "sandbox": { "type": "boolean" }, "media_ids": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "platform", "status"], "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string" }, "sandbox_behavior": { "$ref": "#/components/schemas/SandboxAccountBehavior" }, "external_post_id": { "type": "string" }, "external_url": { "type": "string", "format": "uri" }, "published_at": { "type": "string", "format": "date-time" }, "error_code": { "type": "string" }, "error_message": { "type": "string" } } } }, "billing_warnings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["code", "platform", "cost_cents"], "properties": { "code": { "const": "X_URL_BILLING_WARNING" }, "platform": { "type": "string" }, "cost_cents": { "type": "integer", "minimum": 0 } } } } } }, "CancelPostResponse": { "oneOf": [ { "$ref": "#/components/schemas/PostStatusResponse" }, { "$ref": "#/components/schemas/CancelPostDryRunResponse" } ] }, "CancelPostDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_cancel"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "posts.cancel" }, "request": { "type": "object", "additionalProperties": false, "required": ["post_group_id"], "properties": { "post_group_id": { "type": "string" } } }, "would_cancel": { "type": "object", "additionalProperties": false, "required": ["post"], "properties": { "post": { "$ref": "#/components/schemas/PostStatusResponse" } } } } }, "RetryPostResponse": { "oneOf": [ { "$ref": "#/components/schemas/PostStatusResponse" }, { "$ref": "#/components/schemas/RetryPostDryRunResponse" } ] }, "RetryPostDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_retry"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "posts.retry" }, "request": { "type": "object", "additionalProperties": false, "required": ["post_group_id"], "properties": { "post_group_id": { "type": "string" } } }, "would_retry": { "type": "object", "additionalProperties": false, "required": ["post"], "properties": { "post": { "$ref": "#/components/schemas/PostStatusResponse" } } } } }, "PostListResponse": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "date", "timezone", "posts"], "properties": { "workspace_id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/PostListItem" } } } }, "PostListItem": { "type": "object", "additionalProperties": false, "required": [ "post_group_id", "status", "text", "sandbox", "media_ids", "targets" ], "properties": { "post_group_id": { "type": "string" }, "status": { "type": "string" }, "text": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean" }, "media_ids": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "platform", "status"], "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string" }, "sandbox_behavior": { "$ref": "#/components/schemas/SandboxAccountBehavior" } } } } } }, "UsageSummary": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "period_start", "spend_cap_cents", "billable_cost_cents", "remaining_cents", "connected_account_count", "totals", "sandbox_totals", "records" ], "properties": { "workspace_id": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "spend_cap_cents": { "type": "integer", "minimum": 0 }, "billable_cost_cents": { "type": "integer", "minimum": 0 }, "remaining_cents": { "type": "integer", "minimum": 0 }, "connected_account_count": { "type": "integer", "minimum": 0 }, "totals": { "type": "array", "items": { "$ref": "#/components/schemas/UsageTotal" } }, "sandbox_totals": { "type": "object", "additionalProperties": false, "required": ["quantity", "cost_cents"], "properties": { "quantity": { "type": "integer", "minimum": 0 }, "cost_cents": { "type": "integer", "minimum": 0 } } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRecord" } } } }, "AgentUsageSummary": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "agent_identity_id", "period_start", "spend_cap_cents", "billable_cost_cents", "remaining_cents", "totals", "sandbox_totals", "records" ], "properties": { "workspace_id": { "type": "string" }, "agent_identity_id": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "spend_cap_cents": { "type": "integer", "minimum": 0 }, "billable_cost_cents": { "type": "integer", "minimum": 0 }, "remaining_cents": { "type": "integer", "minimum": 0 }, "totals": { "type": "array", "items": { "$ref": "#/components/schemas/UsageTotal" } }, "sandbox_totals": { "type": "object", "additionalProperties": false, "required": ["quantity", "cost_cents"], "properties": { "quantity": { "type": "integer", "minimum": 0 }, "cost_cents": { "type": "integer", "minimum": 0 } } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRecord" } } } }, "BillingSummary": { "type": "object", "additionalProperties": false, "required": [ "workspace_id", "period_start", "free_credit_cents", "billable_cost_cents", "projected_bill_cents", "spend_cap_cents", "remaining_cents", "status" ], "properties": { "workspace_id": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "free_credit_cents": { "type": "integer", "minimum": 0 }, "billable_cost_cents": { "type": "integer", "minimum": 0 }, "projected_bill_cents": { "type": "integer", "minimum": 0 }, "spend_cap_cents": { "type": "integer", "minimum": 0 }, "remaining_cents": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": ["within_cap", "cap_reached"] } } }, "StripeCheckoutSessionRequest": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "price_id", "success_url", "cancel_url"], "properties": { "workspace_id": { "type": "string" }, "price_id": { "type": "string" }, "success_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" } } }, "StripeCheckoutSessionResponse": { "type": "object", "additionalProperties": false, "required": ["session"], "properties": { "session": { "$ref": "#/components/schemas/StripeBillingSession" } } }, "StripeBillingPortalSessionRequest": { "type": "object", "additionalProperties": false, "required": ["workspace_id", "return_url"], "properties": { "workspace_id": { "type": "string" }, "return_url": { "type": "string", "format": "uri" } } }, "StripeBillingPortalSessionResponse": { "type": "object", "additionalProperties": false, "required": ["session"], "properties": { "session": { "$ref": "#/components/schemas/StripeBillingSession" } } }, "StripeBillingSession": { "type": "object", "additionalProperties": false, "required": ["id", "url"], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "StripeBillingWebhookResponse": { "type": "object", "additionalProperties": false, "required": ["received", "event_id", "event_type"], "properties": { "received": { "const": true }, "event_id": { "type": "string" }, "event_type": { "type": "string" } } }, "WebhookDeliveryResponse": { "oneOf": [ { "$ref": "#/components/schemas/WebhookDeliveryResultResponse" }, { "$ref": "#/components/schemas/WebhookReplayDryRunResponse" } ] }, "WebhookDeliveryResultResponse": { "type": "object", "additionalProperties": false, "required": ["delivery"], "properties": { "delivery": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "WebhookReplayDryRunResponse": { "type": "object", "additionalProperties": false, "required": ["dry_run", "operation", "request", "would_replay"], "properties": { "dry_run": { "type": "boolean", "const": true }, "operation": { "type": "string", "const": "webhooks.deliveries.replay" }, "request": { "type": "object", "additionalProperties": false, "required": ["delivery_id"], "properties": { "delivery_id": { "type": "string" } } }, "would_replay": { "type": "object", "additionalProperties": false, "required": ["delivery"], "properties": { "delivery": { "$ref": "#/components/schemas/WebhookDelivery" } } } } }, "WebhookDelivery": { "type": "object", "additionalProperties": false, "required": [ "id", "workspace_id", "event", "sandbox", "url", "status", "attempt", "created_at" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "event": { "type": "string" }, "entity_id": { "type": "string" }, "sandbox": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": ["delivered", "pending_retry", "failed", "dead_lettered"] }, "attempt": { "type": "integer", "minimum": 1 }, "response_status": { "type": "integer", "minimum": 100, "maximum": 599 }, "error_message": { "type": "string" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "dead_lettered_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "AuditLogsResponse": { "type": "object", "additionalProperties": false, "required": ["logs"], "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } } } }, "AuditLogsCsvExportResponse": { "type": "object", "additionalProperties": false, "required": ["format", "content_type", "filename", "data"], "properties": { "format": { "const": "csv" }, "content_type": { "const": "text/csv" }, "filename": { "type": "string" }, "data": { "type": "string" } } }, "AuditLog": { "type": "object", "additionalProperties": false, "required": [ "id", "workspace_id", "actor_type", "actor_id", "action", "entity_type", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^log_" }, "workspace_id": { "type": "string" }, "actor_type": { "type": "string", "enum": [ "user", "agent", "api_key", "cli", "mcp", "openclaw", "system" ] }, "actor_id": { "type": "string" }, "action": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "UsageTotal": { "type": "object", "additionalProperties": false, "required": ["type", "quantity", "cost_cents"], "properties": { "type": { "type": "string" }, "quantity": { "type": "integer", "minimum": 0 }, "cost_cents": { "type": "integer", "minimum": 0 } } }, "UsageRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "quantity", "cost_cents", "sandbox", "created_at" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "quantity": { "type": "integer", "minimum": 0 }, "cost_cents": { "type": "integer", "minimum": 0 }, "sandbox": { "type": "boolean" }, "source_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "PostMCPError": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "suggested_action", "auto_fixable", "trace_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "retry_after_seconds": { "type": "integer", "minimum": 0 }, "suggested_action": { "type": "string" }, "auto_fixable": { "type": "boolean" }, "fix": { "type": "object", "additionalProperties": true, "required": ["name", "description"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "preview": {} } }, "doc_url": { "type": "string", "format": "uri" }, "trace_id": { "type": "string" } } } } } }