{
  "openapi": "3.1.0",
  "info": {
    "title": "Bolta API",
    "version": "2026-08-21",
    "description": "Agent- and developer-ready API for Bolta, the approval-aware AI social media manager. Public discovery endpoints require no credentials. Product operations require a scoped Bearer API key or OAuth 2.0 access token.",
    "contact": {
      "name": "Bolta Support",
      "email": "support@bolta.ai",
      "url": "https://bolta.ai/support"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://bolta.ai/tos"
    }
  },
  "externalDocs": {
    "description": "Bolta developer documentation",
    "url": "https://bolta.ai/docs"
  },
  "servers": [
    {
      "url": "https://platty.boltathread.com",
      "description": "Bolta production REST API"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Unauthenticated endpoints for service discovery and health checks."
    },
    {
      "name": "Workspaces",
      "description": "Read workspace identity, policy, and capabilities."
    },
    {
      "name": "Posts",
      "description": "Create, inspect, list, and schedule social posts."
    },
    {
      "name": "Agents",
      "description": "Inspect and run Bolta Agent Architecture V2 automations."
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "getBoltaApiDiscovery",
        "summary": "Discover the Bolta API",
        "description": "Returns canonical URLs for Bolta's OpenAPI document, developer documentation, public health endpoint, authenticated REST API, and MCP server.",
        "tags": [
          "Discovery"
        ],
        "security": [],
        "servers": [
          {
            "url": "https://bolta.ai",
            "description": "Unauthenticated discovery mirror. These three endpoints are served by bolta.ai as well as the API host, with no credential and no redirect."
          }
        ],
        "responses": {
          "200": {
            "description": "Canonical API discovery links.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiDiscovery"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getBoltaApiHealth",
        "summary": "Check public API health",
        "description": "Returns a small unauthenticated health response suitable for agents, uptime checks, and integration diagnostics.",
        "tags": [
          "Discovery"
        ],
        "security": [],
        "servers": [
          {
            "url": "https://bolta.ai",
            "description": "Unauthenticated discovery mirror. These three endpoints are served by bolta.ai as well as the API host, with no credential and no redirect."
          }
        ],
        "responses": {
          "200": {
            "description": "The public discovery API is reachable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        }
      }
    },
    "/api/v1/capabilities": {
      "get": {
        "operationId": "getBoltaCapabilities",
        "summary": "Describe Bolta integration capabilities",
        "description": "Returns machine-readable discovery links, authentication requirements, public endpoints, and MCP connection details without exposing customer data.",
        "tags": [
          "Discovery"
        ],
        "security": [],
        "servers": [
          {
            "url": "https://bolta.ai",
            "description": "Unauthenticated discovery mirror. These three endpoints are served by bolta.ai as well as the API host, with no credential and no redirect."
          }
        ],
        "responses": {
          "200": {
            "description": "Bolta public and authenticated integration capabilities.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        }
      }
    },
    "/api/v1/workspaces/": {
      "get": {
        "operationId": "listWorkspaces",
        "summary": "List accessible workspaces",
        "description": "Lists workspaces accessible to the Bearer credential. Agents should call this first to resolve the workspace_id required by most operations.",
        "tags": [
          "Workspaces"
        ],
        "responses": {
          "200": {
            "description": "Accessible workspaces.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Workspace"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "mcp"
            ]
          }
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}/": {
      "get": {
        "operationId": "getWorkspace",
        "summary": "Get a workspace",
        "description": "Returns workspace identity and governance settings. Call this before mutating content so the agent can honor Safe Mode and autonomy rules.",
        "tags": [
          "Workspaces"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "mcp"
            ]
          }
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}/posts/": {
      "get": {
        "operationId": "listWorkspacePosts",
        "summary": "List workspace posts",
        "description": "Lists posts in a workspace with optional status, platform, date, sorting, and pagination filters.",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by the exact PascalCase post status.",
            "schema": {
              "$ref": "#/components/schemas/PostStatus"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Filter by a connected social platform.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "description": "Return posts on or after this ISO 8601 date-time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "description": "Return posts on or before this ISO 8601 date-time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Results per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "One-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated post collection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "mcp"
            ]
          }
        ],
        "x-requiredScopes": [
          "posts:read"
        ]
      }
    },
    "/api/v1/posts/": {
      "post": {
        "operationId": "createPost",
        "summary": "Create a social post",
        "description": "Creates a draft or scheduled post for one or more connected accounts. Workspace autonomy and Safe Mode can route a requested Scheduled status to Draft or Pending Approval; inspect the returned status and routing fields.",
        "tags": [
          "Posts"
        ],
        "requestBody": {
          "required": true,
          "description": "The post, target accounts, content blocks, and optional schedule.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePostRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Post created. The effective status may differ from the requested status because of workspace governance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Post"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "mcp"
            ]
          }
        ],
        "x-requiredScopes": [
          "posts:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      }
    },
    "/api/v1/posts/{post_id}/": {
      "get": {
        "operationId": "getPost",
        "summary": "Get a social post",
        "description": "Returns the current content, status, schedule, target accounts, and timestamps for one post.",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PostId"
          }
        ],
        "responses": {
          "200": {
            "description": "Post details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Post"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "mcp"
            ]
          }
        ],
        "x-requiredScopes": [
          "posts:read"
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}/posts/{post_id}/schedule/": {
      "post": {
        "operationId": "schedulePost",
        "summary": "Schedule a post",
        "description": "Schedules a schedulable post for a future time. Safe Mode may route a Draft to Pending Approval instead of scheduling it directly.",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/PostId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Future publication time.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "time"
                ],
                "properties": {
                  "time": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Future ISO 8601 publication time."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post scheduled or routed into approval according to workspace policy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Post"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "mcp"
            ]
          }
        ],
        "x-requiredScopes": [
          "posts:write"
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}/agents-v2/": {
      "get": {
        "operationId": "listAgentsV2",
        "summary": "List workspace agents",
        "description": "Lists Agent Architecture V2 agents, including their type, role, status, Safe Mode setting, and configuration.",
        "tags": [
          "Agents"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace agents.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Agent"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "mcp"
            ]
          }
        ],
        "x-requiredScopes": [
          "workspace:read"
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}/runs/": {
      "post": {
        "operationId": "runAgentJobNowV2",
        "summary": "Run an agent job now",
        "description": "Starts an immediate run of an existing Agent V2 job. The calling credential needs agents:manage plus every scope required by the job's actions.",
        "tags": [
          "Agents"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/AgentId"
          },
          {
            "$ref": "#/components/parameters/JobId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "Agent job run accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRun"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "default": {
            "$ref": "#/components/responses/DefaultError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "mcp"
            ]
          }
        ],
        "x-requiredScopes": [
          "workspace:read",
          "agents:manage"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Bolta API key or OAuth 2.0 access token",
        "description": "Create a scoped API key in Bolta Settings → API Keys, or use an OAuth 2.0 access token. Every key carries an explicit permission scope set (see x-apiKeyScopes); the scopes each operation requires are listed in its x-requiredScopes. Grant the narrowest set that covers your calls. Never expose the credential in query parameters."
      },
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 authorization code flow with PKCE (S256) and dynamic client registration (RFC 7591). Consent is per workspace: the `mcp` grant mints a workspace-scoped API key whose permission scopes follow the consenting member's role, so an agent never receives more than that member can do.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://platty.boltathread.com/users/oauth/authorize/",
            "tokenUrl": "https://platty.boltathread.com/users/oauth/token/",
            "refreshUrl": "https://platty.boltathread.com/users/oauth/token/",
            "scopes": {
              "mcp": "Operate a single consented workspace through the Bolta API and MCP server.",
              "profile": "Read the authenticated user's basic profile.",
              "email": "Read the authenticated user's email address."
            }
          }
        }
      }
    },
    "parameters": {
      "WorkspaceId": {
        "name": "workspace_id",
        "in": "path",
        "required": true,
        "description": "Bolta workspace UUID.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "PostId": {
        "name": "post_id",
        "in": "path",
        "required": true,
        "description": "Bolta post UUID.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "AgentId": {
        "name": "agent_id",
        "in": "path",
        "required": true,
        "description": "Bolta Agent V2 UUID.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "JobId": {
        "name": "job_id",
        "in": "path",
        "required": true,
        "description": "Bolta Agent V2 job UUID.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Client-generated key that makes a retried write safe. A repeat of the same key within 24 hours replays the original response instead of creating a second record. Use a fresh UUID per logical operation, and reuse it verbatim on every retry of that operation.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "example": "6f1b0a4e-6a1e-4f2f-9a2a-2f3a1b4c5d6e"
        }
      }
    },
    "headers": {
      "RateLimit": {
        "description": "Current quota budget for this request under RFC 9651.",
        "schema": {
          "type": "string",
          "example": "\"default\";r=95;t=60"
        }
      },
      "RateLimit-Policy": {
        "description": "Applicable quota policy under RFC 9651.",
        "schema": {
          "type": "string",
          "example": "\"default\";q=100;w=60"
        }
      },
      "RateLimit-Limit": {
        "description": "Quota limit in the active window (transitional field).",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "RateLimit-Remaining": {
        "description": "Requests remaining in the active window (transitional field).",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the active window resets (transitional field).",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is invalid or conflicts with workspace policy.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The Bearer credential is missing, expired, or invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The credential is valid but lacks the required workspace role or permission scope.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested workspace resource does not exist or is not visible to the credential.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The API key's rate limit was exceeded. Respect Retry-After before retrying.",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the caller should retry.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Conflict": {
        "description": "The request conflicts with the resource's current state, for example a second, different decision on a review that was already resolved.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServerError": {
        "description": "Bolta failed to process an otherwise valid request. Retry with backoff.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "DefaultError": {
        "description": "Unexpected error. Every non-2xx Bolta response uses the same typed error envelope, so a client can branch on error.code without inspecting prose.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ApiDiscovery": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "product",
          "openapi",
          "documentation",
          "authenticatedApiBase",
          "mcp"
        ],
        "properties": {
          "product": {
            "type": "string",
            "const": "Bolta"
          },
          "description": {
            "type": "string"
          },
          "health": {
            "type": "string",
            "format": "uri"
          },
          "capabilities": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "authenticatedApiBase": {
            "type": "string",
            "format": "uri"
          },
          "mcp": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Health": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "service",
          "documentation"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "ok"
          },
          "service": {
            "type": "string",
            "const": "bolta-public-api"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Capabilities": {
        "type": "object",
        "required": [
          "product",
          "description",
          "discovery",
          "access",
          "mcp"
        ],
        "properties": {
          "product": {
            "type": "string",
            "const": "Bolta"
          },
          "description": {
            "type": "string"
          },
          "discovery": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          },
          "access": {
            "type": "object",
            "description": "Public endpoints and authenticated REST API access details."
          },
          "mcp": {
            "type": "object",
            "description": "Streamable HTTP MCP endpoint and authentication details."
          }
        }
      },
      "Workspace": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "safe_mode": {
            "type": "boolean",
            "description": "When true, risky agent-created actions require human review."
          },
          "autonomy_mode": {
            "type": "string",
            "description": "Workspace automation mode controlling effective post routing."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PostStatus": {
        "type": "string",
        "enum": [
          "Draft",
          "Scheduled",
          "Published",
          "Failed",
          "Pending Approval",
          "Needs Revision",
          "Approved",
          "Rejected",
          "Queued",
          "Processing",
          "Ready for Scheduling"
        ]
      },
      "PostContent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "content",
          "index"
        ],
        "properties": {
          "content": {
            "type": "string",
            "minLength": 1
          },
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "media": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "media_url"
              ],
              "properties": {
                "media_url": {
                  "type": "string",
                  "format": "uri"
                },
                "order": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "default": []
          }
        }
      },
      "CreatePostRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "workspace_id",
          "status",
          "accounts",
          "contents"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "$ref": "#/components/schemas/PostStatus"
          },
          "scheduled_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Required when status is Scheduled."
          },
          "accounts": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "description": "Account UUID or a supported organization/page identifier."
            }
          },
          "contents": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/PostContent"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "platform_specific": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/PostContent"
            }
          }
        }
      },
      "Post": {
        "type": "object",
        "required": [
          "id",
          "status",
          "contents",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "$ref": "#/components/schemas/PostStatus"
          },
          "scheduled_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "contents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PostContent"
            }
          },
          "accounts": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "original_requested_status": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PostStatus"
              },
              {
                "type": "null"
              }
            ]
          },
          "routing": {
            "type": "object",
            "description": "Present when governance changes the requested status; explains the effective status and how to change policy."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PostList": {
        "type": "object",
        "required": [
          "posts",
          "count"
        ],
        "properties": {
          "posts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "has_more": {
            "type": "boolean"
          },
          "pagination": {
            "type": "object",
            "properties": {
              "page": {
                "type": "integer",
                "minimum": 1
              },
              "limit": {
                "type": "integer",
                "minimum": 1
              },
              "total": {
                "type": "integer",
                "minimum": 0
              },
              "has_next": {
                "type": "boolean"
              },
              "has_previous": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "Agent": {
        "type": "object",
        "required": [
          "id",
          "name",
          "type",
          "role",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "content_creator",
              "engagement",
              "acquisition",
              "reviewer",
              "analytics",
              "moderator",
              "custom"
            ]
          },
          "role": {
            "type": "string",
            "enum": [
              "viewer",
              "creator",
              "editor",
              "admin"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "error"
            ]
          },
          "safe_mode": {
            "type": "boolean"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "config": {
            "type": "object"
          }
        }
      },
      "AgentRun": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation."
              },
              "resolution": {
                "type": "string",
                "description": "Concrete recovery hint for an agent or developer."
              },
              "documentation": {
                "type": "string",
                "format": "uri"
              },
              "details": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "x-apiKeyScopes": {
      "posts:read": "Read posts, drafts, and their scheduling state.",
      "posts:write": "Create, edit, schedule, approve, and publish posts.",
      "posts:delete": "Delete posts.",
      "accounts:read": "Read connected social accounts and their health.",
      "accounts:write": "Manage social buckets and account settings.",
      "accounts:connect": "Start a connect flow for a new social account.",
      "recurring:manage": "Manage recurring content schedules.",
      "voice:read": "Read brand voice profiles.",
      "voice:write": "Create and update brand voice profiles.",
      "crm:read": "Read CRM contacts and conversations.",
      "crm:write": "Create and update CRM contacts and conversations.",
      "ai:generate": "Run AI generation (text, images, voice-aware drafting).",
      "content:bulk": "Run bulk content operations.",
      "workspace:read": "Read workspace identity, policy, agents, and jobs.",
      "workspace:admin": "Change workspace settings, including autonomy and safe mode.",
      "review:submit": "Submit content for human review.",
      "review:approve": "Approve or reject content in review.",
      "audit:export": "Export the workspace audit log.",
      "team:manage": "Manage workspace members and roles.",
      "team:manage_keys": "Create and revoke API keys.",
      "agents:manage": "Create, update, delete, pause, and run agents and agent jobs."
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}