{
  "openapi": "3.1.0",
  "info": {
    "title": "CreativeClaw MCP API",
    "version": "0.3.0",
    "summary": "Remote Model Context Protocol server for AI image, video, speech, and brand workflows.",
    "description": "CreativeClaw is a remote MCP server, not a resource-oriented REST API.\n\nAgents authenticate with OAuth 2.1 (authorization code + PKCE S256), then speak JSON-RPC 2.0 over Streamable HTTP at POST /mcp.\n\nAfter `initialize`, call `tools/list` for live schemas and `tools/call` to invoke a tool.\n\nAsync tools (`generate_video`, `render_html_video`, `generate_3d_model`, `transcribe`, `isolate_audio`, `merge_media`) return a `job_id`; poll `check_job` until `status` is `completed` or `failed`.\n\nHuman docs: https://creativeclaw.co/developers/  ·  Tool catalog: https://creativeclaw.co/methods/  ·  Pricing: https://creativeclaw.co/pricing.md",
    "termsOfService": "https://creativeclaw.co/terms/",
    "contact": {
      "name": "CreativeClaw",
      "email": "hello@creativeclaw.co",
      "url": "https://creativeclaw.co"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://creativeclaw.co/terms/"
    }
  },
  "externalDocs": {
    "description": "Developer and agent documentation",
    "url": "https://creativeclaw.co/developers/"
  },
  "servers": [
    {
      "url": "https://app.creativeclaw.co",
      "description": "Production MCP host"
    }
  ],
  "tags": [
    {
      "name": "MCP",
      "description": "Streamable HTTP JSON-RPC transport"
    },
    {
      "name": "Health",
      "description": "Unauthenticated liveness"
    },
    {
      "name": "OAuth",
      "description": "RFC 8414 / RFC 9728 discovery. Used by MCP clients before the first authenticated call."
    },
    {
      "name": "Tools",
      "description": "MCP tools invoked via tools/call. Schemas are authoritative from tools/list at runtime."
    }
  ],
  "security": [
    {
      "oauth2": [
        "profile",
        "email"
      ]
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "tags": [
          "MCP"
        ],
        "operationId": "mcpJsonRpc",
        "summary": "MCP Streamable HTTP endpoint",
        "description": "JSON-RPC 2.0 over Streamable HTTP (MCP protocol 2025-03-26 and later). Requires a Bearer access token from the Clerk OAuth flow. Clients must send `Accept: application/json, text/event-stream`.",
        "security": [
          {
            "oauth2": [
              "profile",
              "email"
            ]
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "MCP-Protocol-Version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "example": "2025-03-26"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "initialize": {
                  "summary": "initialize",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2025-03-26",
                      "capabilities": {},
                      "clientInfo": {
                        "name": "example-agent",
                        "version": "1.0.0"
                      }
                    }
                  }
                },
                "toolsList": {
                  "summary": "tools/list",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/list",
                    "params": {}
                  }
                },
                "toolsCall": {
                  "summary": "tools/call generate_image",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tools/call",
                    "params": {
                      "name": "generate_image",
                      "arguments": {
                        "prompt": "A matte black espresso machine on a warm kitchen counter"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC success or error envelope, or a text/event-stream for streamed results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token. Follow WWW-Authenticate to the protected-resource metadata.",
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "Bearer challenge pointing at https://app.creativeclaw.co/.well-known/oauth-protected-resource/mcp"
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "getHealth",
        "summary": "MCP host health",
        "description": "Unauthenticated liveness probe. Live URL: https://app.creativeclaw.co/health",
        "security": [],
        "responses": {
          "200": {
            "description": "Process and database are up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "503": {
            "description": "Database unreachable. Process is up but degraded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-protected-resource/mcp": {
      "get": {
        "tags": [
          "OAuth"
        ],
        "operationId": "getProtectedResourceMetadata",
        "summary": "OAuth protected resource metadata (RFC 9728)",
        "security": [],
        "responses": {
          "200": {
            "description": "Resource identifier, authorization servers, and supported scopes (`profile`, `email`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "tags": [
          "OAuth"
        ],
        "operationId": "getAuthorizationServerMetadata",
        "summary": "OAuth authorization server metadata (RFC 8414)",
        "description": "Proxied from Clerk with `scopes_supported` pinned to `profile` and `email`. Dynamic clients must not request `openid`.",
        "security": [],
        "responses": {
          "200": {
            "description": "Authorization, token, registration, and JWKS URLs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/openid-configuration": {
      "get": {
        "tags": [
          "OAuth"
        ],
        "operationId": "getOpenIdConfiguration",
        "summary": "OpenID Provider configuration",
        "security": [],
        "responses": {
          "200": {
            "description": "Same Clerk issuer metadata with MCP-safe scopes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorization code with PKCE S256. Dynamic client registration is supported. Request only `profile` and `email`.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://clerk.creativeclaw.co/oauth/authorize",
            "tokenUrl": "https://clerk.creativeclaw.co/oauth/token",
            "refreshUrl": "https://clerk.creativeclaw.co/oauth/token",
            "scopes": {
              "profile": "Read the authenticated user profile",
              "email": "Read the authenticated user email"
            }
          }
        }
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Access token from the Clerk token endpoint, sent as `Authorization: Bearer <token>`."
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "method": {
            "type": "string",
            "enum": [
              "initialize",
              "tools/list",
              "tools/call",
              "ping",
              "notifications/initialized"
            ]
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "$ref": "#/components/schemas/JsonRpcError"
          }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "JSON-RPC error code (e.g. -32600 invalid request, -32602 invalid params)."
          },
          "message": {
            "type": "string"
          },
          "data": {
            "description": "Optional protocol or tool error payload."
          }
        }
      },
      "ToolCallParams": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "generate_image",
              "generate_video",
              "generate_speech",
              "generate_3d_model",
              "compare_models",
              "list_models",
              "get_model_params",
              "render_html_image",
              "render_html_video",
              "create_template",
              "render_template",
              "update_template",
              "list_templates",
              "transcribe",
              "isolate_audio",
              "upscale_media",
              "trim_video",
              "scale_video",
              "add_subtitles",
              "remove_background",
              "extract_frames",
              "merge_media",
              "manage_character",
              "clone_voice",
              "list_characters",
              "delete_character",
              "create_film_project",
              "update_film_project",
              "get_film_project",
              "list_film_projects",
              "assemble_film",
              "list_themes",
              "get_theme",
              "update_theme",
              "delete_theme",
              "search_assets",
              "update_asset",
              "delete_asset",
              "load_image",
              "import_media",
              "import_chatgpt_media",
              "get_upload_url",
              "confirm_upload",
              "upload_asset",
              "check_job",
              "get_credits_balance",
              "get_credits_link",
              "purchase_credits",
              "submit_feedback"
            ]
          },
          "arguments": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ToolResult": {
        "type": "object",
        "properties": {
          "content": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "example": "text"
                },
                "text": {
                  "type": "string"
                }
              }
            }
          },
          "isError": {
            "type": "boolean",
            "description": "True when the tool ran but the operation failed (credits, validation, provider)."
          },
          "structuredContent": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Job": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Permanent CDN URL when status is completed."
          },
          "error": {
            "type": "string"
          }
        }
      },
      "Health": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded"
            ]
          },
          "db": {
            "type": "string",
            "enum": [
              "connected",
              "error"
            ]
          },
          "version": {
            "type": "string"
          },
          "commit": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        }
      },
      "McpTool": {
        "type": "object",
        "required": [
          "name",
          "summary"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "async": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "x-mcp-endpoint": "https://app.creativeclaw.co/mcp",
  "x-mcp-transport": "streamable-http",
  "x-pkce": "S256",
  "x-mcp-tools": [
    {
      "name": "generate_image",
      "summary": "Generate or edit an image. Default model: Nano Banana 2.",
      "category": "generate"
    },
    {
      "name": "generate_video",
      "summary": "Generate, animate, extend, or edit video. Default model: Gemini Omni Flash.",
      "category": "generate",
      "async": true
    },
    {
      "name": "generate_speech",
      "summary": "Generate speech or dialogue. Default model: ElevenLabs v3.",
      "category": "generate"
    },
    {
      "name": "generate_3d_model",
      "summary": "Queue a 3D model generation job (GLB).",
      "category": "generate",
      "async": true
    },
    {
      "name": "compare_models",
      "summary": "Run one image prompt through 2–4 image models side by side.",
      "category": "generate"
    },
    {
      "name": "list_models",
      "summary": "List current image, video, and speech models. Filter by category.",
      "category": "discover"
    },
    {
      "name": "get_model_params",
      "summary": "Read a model’s live schema, defaults, enums, and extras.",
      "category": "discover"
    },
    {
      "name": "render_html_image",
      "summary": "Render HTML/CSS to a PNG via the branded layout engine.",
      "category": "layout"
    },
    {
      "name": "render_html_video",
      "summary": "Render code-driven HTML motion to MP4. Returns a job ID.",
      "category": "layout",
      "async": true
    },
    {
      "name": "create_template",
      "summary": "Create a reusable HTML or generative template.",
      "category": "layout"
    },
    {
      "name": "render_template",
      "summary": "Render a saved template with parameter values.",
      "category": "layout"
    },
    {
      "name": "update_template",
      "summary": "Patch an existing template’s fields.",
      "category": "layout"
    },
    {
      "name": "list_templates",
      "summary": "List saved templates for the account.",
      "category": "layout"
    },
    {
      "name": "transcribe",
      "summary": "Transcribe audio or video with word-level timestamps.",
      "category": "edit",
      "async": true
    },
    {
      "name": "isolate_audio",
      "summary": "Remove noise, music, and reverb from a voice recording.",
      "category": "edit",
      "async": true
    },
    {
      "name": "upscale_media",
      "summary": "Upscale an image or video.",
      "category": "edit"
    },
    {
      "name": "trim_video",
      "summary": "Cut a time range from a video.",
      "category": "edit"
    },
    {
      "name": "scale_video",
      "summary": "Resize, crop, or pad a video.",
      "category": "edit"
    },
    {
      "name": "add_subtitles",
      "summary": "Burn captions onto a video.",
      "category": "edit"
    },
    {
      "name": "remove_background",
      "summary": "Remove the background from an image or video.",
      "category": "edit"
    },
    {
      "name": "extract_frames",
      "summary": "Extract still frames from a video.",
      "category": "edit"
    },
    {
      "name": "merge_media",
      "summary": "Concatenate videos or audio, or mix an audio track onto video.",
      "category": "edit",
      "async": true
    },
    {
      "name": "manage_character",
      "summary": "Create or update a Character (reference image + optional cloned voice).",
      "category": "characters"
    },
    {
      "name": "clone_voice",
      "summary": "Attach a consented voice clone to an existing Character.",
      "category": "characters"
    },
    {
      "name": "list_characters",
      "summary": "List reusable Characters and IDs.",
      "category": "characters"
    },
    {
      "name": "delete_character",
      "summary": "Soft-delete a Character.",
      "category": "characters"
    },
    {
      "name": "create_film_project",
      "summary": "Create a multi-shot Film project.",
      "category": "film"
    },
    {
      "name": "update_film_project",
      "summary": "Save script, shots, storyboards, clips, and approval state.",
      "category": "film"
    },
    {
      "name": "get_film_project",
      "summary": "Inspect one Film project.",
      "category": "film"
    },
    {
      "name": "list_film_projects",
      "summary": "List Film projects for the account.",
      "category": "film"
    },
    {
      "name": "assemble_film",
      "summary": "Merge approved clips and audio into the final Film.",
      "category": "film"
    },
    {
      "name": "list_themes",
      "summary": "List brand themes and the default theme.",
      "category": "brand"
    },
    {
      "name": "get_theme",
      "summary": "Fetch the default or named brand theme.",
      "category": "brand"
    },
    {
      "name": "update_theme",
      "summary": "Create or update a brand theme, or open the visual editor.",
      "category": "brand"
    },
    {
      "name": "delete_theme",
      "summary": "Soft-delete a brand theme.",
      "category": "brand"
    },
    {
      "name": "search_assets",
      "summary": "Search the permanent asset library by type, query, tags, or name.",
      "category": "assets"
    },
    {
      "name": "update_asset",
      "summary": "Set a unique name, replace tags, or update a description.",
      "category": "assets"
    },
    {
      "name": "delete_asset",
      "summary": "Soft-delete an asset.",
      "category": "assets"
    },
    {
      "name": "load_image",
      "summary": "Load an image URL inline for visual review.",
      "category": "assets"
    },
    {
      "name": "import_media",
      "summary": "Open the media picker when the user still needs to choose a file.",
      "category": "assets"
    },
    {
      "name": "import_chatgpt_media",
      "summary": "Convert a ChatGPT attachment into a durable CreativeClaw asset (ChatGPT only).",
      "category": "assets"
    },
    {
      "name": "get_upload_url",
      "summary": "Mint a signed upload URL for clients that can HTTP PUT bytes.",
      "category": "assets"
    },
    {
      "name": "confirm_upload",
      "summary": "Finalize a signed upload into the asset library.",
      "category": "assets"
    },
    {
      "name": "upload_asset",
      "summary": "Copy a public, directly downloadable URL into the library.",
      "category": "assets"
    },
    {
      "name": "check_job",
      "summary": "Poll an async job by job_id until it completes or fails.",
      "category": "billing"
    },
    {
      "name": "get_credits_balance",
      "summary": "Read remaining credits and optionally estimate a generation cost.",
      "category": "billing"
    },
    {
      "name": "get_credits_link",
      "summary": "Return a user-operated Polar checkout link for credit top-up.",
      "category": "billing"
    },
    {
      "name": "purchase_credits",
      "summary": "Start a credit purchase. Packs: 1000/$10, 5000/$50, 11000/$100, 27500/$250.",
      "category": "billing"
    },
    {
      "name": "submit_feedback",
      "summary": "Send product feedback (bug, missing feature, praise) to the team.",
      "category": "billing"
    }
  ]
}