{
  "openapi": "3.1.0",
  "info": {
    "title": "CatCaster Public API",
    "version": "1.0.0",
    "description": "Resource-oriented HTTP API for the CatCaster external ecosystem. All mutations execute through the same agent tool layer as MCP."
  },
  "servers": [{ "url": "https://www.catcaster.com", "description": "Production" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "CatCaster API key (sk_live_...) or OAuth access token from Supabase Auth."
      }
    },
    "headers": {
      "XCatCasterRequestId": {
        "schema": { "type": "string" },
        "description": "Echoed on every response; may be supplied on the request."
      },
      "IdempotencyKey": {
        "schema": { "type": "string" },
        "description": "Recommended for create draft, schedule, publish, and generation mutations."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "requestId"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "requestId": { "type": "string" },
              "confirmationId": { "type": "string" },
              "expiresAt": { "type": "string", "format": "date-time" },
              "preview": {},
              "details": {}
            }
          }
        }
      },
      "DataResponse": {
        "type": "object",
        "properties": {
          "data": {},
          "nextCursor": { "type": "string" },
          "requestId": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/api/v1/projects": {
      "get": {
        "summary": "List projects (workspaces)",
        "operationId": "listProjects",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/api/v1/projects/{projectId}/channels": {
      "get": {
        "summary": "List channels for a project",
        "operationId": "listProjectChannels",
        "parameters": [{ "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/v1/posts": {
      "get": {
        "summary": "List posts",
        "operationId": "listPosts",
        "parameters": [
          { "name": "projectId", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          { "name": "status", "in": "query", "schema": { "type": "string" } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/v1/posts/{postId}": {
      "get": {
        "summary": "Get a post",
        "operationId": "getPost",
        "parameters": [{ "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/v1/posts/generate": {
      "post": {
        "summary": "Generate post variants",
        "operationId": "generatePost",
        "responses": { "200": { "description": "OK" }, "409": { "description": "Confirmation required" } }
      }
    },
    "/api/v1/drafts": {
      "post": {
        "summary": "Create a draft",
        "operationId": "createDraft",
        "responses": { "200": { "description": "OK" }, "409": { "description": "Confirmation required" } }
      }
    },
    "/api/v1/drafts/{draftId}": {
      "patch": {
        "summary": "Update a draft",
        "operationId": "updateDraft",
        "parameters": [{ "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/v1/posts/{postId}/schedule": {
      "post": {
        "summary": "Schedule a post",
        "operationId": "schedulePost",
        "parameters": [{ "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "409": { "description": "Confirmation required — pass confirmationId in body on retry" } }
      }
    },
    "/api/v1/posts/{postId}/publish": {
      "post": {
        "summary": "Publish a post now",
        "operationId": "publishPost",
        "parameters": [{ "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "409": { "description": "Confirmation required" } }
      }
    },
    "/api/v1/jobs/{jobId}": {
      "get": {
        "summary": "Get async job status",
        "operationId": "getJob",
        "parameters": [
          { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "jobType", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/v1/tools/{toolName}/execute": {
      "post": {
        "summary": "Execute a registered agent tool by name",
        "description": "Accepts canonical tool names and frozen catcaster_* ecosystem aliases.",
        "operationId": "executeTool",
        "parameters": [{ "name": "toolName", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK" }, "409": { "description": "Confirmation required" } }
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "summary": "List outbound webhook endpoints for a project",
        "operationId": "listWebhooks",
        "parameters": [
          { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": { "200": { "description": "OK" } }
      },
      "post": {
        "summary": "Register an HTTPS webhook endpoint",
        "operationId": "createWebhook",
        "description": "Returns signingSecret once. Events default to post.published and post.failed.",
        "responses": { "201": { "description": "Created" } }
      }
    },
    "/api/v1/webhooks/{webhookId}": {
      "delete": {
        "summary": "Remove a webhook endpoint",
        "operationId": "deleteWebhook",
        "parameters": [
          { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    }
  }
}