{
  "openapi": "3.1.0",
  "info": {
    "title": "DocRocket API",
    "description": "DocRocket surfaces: (1) **HTTPS JSON API** at `api.docrocket.ai/v1` — POST a single JSON envelope with `action` plus optional `account_id`, `user_id`, and a `body` object for action-specific fields. Use an Auth0 access token or DocRocket API key JWT in `Authorization: Bearer`. (2) **MCP-aligned HTTP paths** on the MCP gateway for high-level document flows. (3) **Direct Lambda invoke** with the same envelope shape for batch/tool integrations.",
    "version": "1.0.0",
    "contact": {
      "email": "hello@docrocket.ai",
      "url": "https://docrocket.ai"
    },
    "x-mcp-endpoint": "https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control/mcp"
  },
  "servers": [
    {
      "url": "https://api.docrocket.ai/v1",
      "description": "Production HTTPS API (Auth0 or API key JWT)"
    },
    {
      "url": "https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control",
      "description": "DocRocket MCP HTTP gateway (OAuth / MCP client flows)"
    }
  ],
  "paths": {
    "/": {
      "post": {
        "tags": ["HTTPS JSON API"],
        "operationId": "http_invoke_action",
        "summary": "Invoke a tool action (customer route)",
        "servers": [
          {
            "url": "https://api.docrocket.ai/v1",
            "description": "Production HTTPS API"
          }
        ],
        "description": "POST the JSON **envelope** to invoke any customer-scoped action (`brands.*`, `content.*`, `design.*`, `render.run`, `billing.*`, `users.*`, `api_keys.*`, `inspector.*`, …). Send `Authorization: Bearer` with an Auth0 access token (same audience as the DocRocket app) or an API key JWT.\n\nAction-specific parameters go in the `body` object (merged server-side with the envelope). Underscore tool names from direct invoke (e.g. `content_list_docs`) are accepted as aliases for dotted actions.\n\n**Do not** send `admin.*` here — use `POST /admin` with a Cognito admin access token.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["action"],
                "properties": {
                  "action": {
                    "type": "string",
                    "description": "Dotted action name, e.g. `content.list_docs`, `render.run`, `brands.put`.",
                    "example": "content.list_docs"
                  },
                  "account_id": {
                    "description": "Account scope (string or integer); required for most writes and multi-tenant reads.",
                    "oneOf": [{ "type": "string" }, { "type": "integer" }]
                  },
                  "user_id": {
                    "type": "string",
                    "description": "End-user id (email-shaped for interactive auth). Required for several write paths."
                  },
                  "request_id": {
                    "type": "string",
                    "description": "Optional idempotency / tracing id echoed in logs."
                  },
                  "roles": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Optional role hints such as `brand_admin`, `brand_editor`, `viewer` for tighter brand ACLs."
                  },
                  "body": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Action-specific payload (e.g. `doc_id` for content reads, `markdown` + `formats` for `render.run`). Defaults to `{}`."
                  }
                }
              },
              "examples": {
                "listDocs": {
                  "summary": "List documents",
                  "value": {
                    "action": "content.list_docs",
                    "account_id": "426",
                    "user_id": "you@example.com",
                    "body": {}
                  }
                },
                "renderRun": {
                  "summary": "Render markdown",
                  "value": {
                    "action": "render.run",
                    "account_id": "426",
                    "user_id": "you@example.com",
                    "body": {
                      "markdown": "# Title\n\nHello from the API.",
                      "formats": ["html"]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — JSON `{ \"success\": true, \"data\": … }`",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success"],
                  "properties": {
                    "success": { "const": true },
                    "data": { "description": "Action result payload" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation or bad request — `{ \"success\": false, \"error\": { \"code\", \"message\", \"details\"? } }`"
          },
          "401": { "description": "Missing or invalid bearer token" },
          "403": { "description": "Forbidden for this principal or action" },
          "404": { "description": "Not found" },
          "409": { "description": "Conflict (e.g. document version mismatch)" },
          "500": { "description": "Server error" }
        }
      }
    },
    "/admin": {
      "post": {
        "tags": ["HTTPS JSON API"],
        "operationId": "http_invoke_admin_action",
        "summary": "Invoke an admin action (Cognito)",
        "servers": [
          {
            "url": "https://api.docrocket.ai/v1",
            "description": "Production HTTPS API"
          }
        ],
        "description": "Same envelope as `POST /`, but requires a **Cognito** admin access token (DocRocket admin SPA). Use for `admin.*` and `admin.master.*` operations. Customer actions that are not admin should use `POST /` with Auth0.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["action"],
                "properties": {
                  "action": { "type": "string", "example": "admin.brands.list" },
                  "account_id": { "type": "string" },
                  "user_id": { "type": "string" },
                  "request_id": { "type": "string" },
                  "body": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "const": true },
                    "data": {}
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized" },
          "403": { "description": "Forbidden" }
        }
      }
    },
    "/brand-from-url": {
      "post": {
        "servers": [
          {
            "url": "https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control",
            "description": "MCP gateway base URL for these paths"
          }
        ],
        "operationId": "docrocket_brand_from_url",
        "summary": "Extract brand from URL",
        "description": "Crawls a customer's website and automatically extracts brand identity: logo, primary and secondary colors, and typography. Creates a reusable brand profile. Call this once per customer — the brand ID can be reused for unlimited document generation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The customer's public website URL",
                    "example": "https://acme.com"
                  },
                  "name": {
                    "type": "string",
                    "description": "Optional display name for this brand. Defaults to the site's detected company name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brand successfully extracted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brand_id": { "type": "string" },
                    "name": { "type": "string" },
                    "logo_url": { "type": "string" },
                    "colors": {
                      "type": "object",
                      "properties": {
                        "primary": { "type": "string" },
                        "secondary": { "type": "string" },
                        "accent": { "type": "string" }
                      }
                    },
                    "fonts": {
                      "type": "object",
                      "properties": {
                        "heading": { "type": "string" },
                        "body": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/list-brands": {
      "get": {
        "servers": [
          {
            "url": "https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control",
            "description": "MCP gateway base URL for these paths"
          }
        ],
        "operationId": "docrocket_list_brands",
        "summary": "List saved brands",
        "description": "Returns all customer brand profiles saved in the workspace. Use brand_id from this list when generating documents.",
        "responses": {
          "200": {
            "description": "List of brands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brands": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "brand_id": { "type": "string" },
                          "name": { "type": "string" },
                          "source_url": { "type": "string" },
                          "document_count": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/list-templates": {
      "get": {
        "servers": [
          {
            "url": "https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control",
            "description": "MCP gateway base URL for these paths"
          }
        ],
        "operationId": "docrocket_list_templates",
        "summary": "List document templates",
        "description": "Returns all available document templates. Use the template slug when calling generate_document.",
        "responses": {
          "200": {
            "description": "List of templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "templates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": { "type": "string", "example": "proposal" },
                          "name": { "type": "string", "example": "Business Proposal" },
                          "description": { "type": "string" },
                          "sections": {
                            "type": "array",
                            "items": { "type": "string" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/list-components": {
      "get": {
        "servers": [
          {
            "url": "https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control",
            "description": "MCP gateway base URL for these paths"
          }
        ],
        "operationId": "docrocket_list_components",
        "summary": "List custom components",
        "description": "Returns all saved custom reusable components (pricing tables, signature sections, disclaimers, etc.). Reference component names in document content using include: component_name.",
        "responses": {
          "200": {
            "description": "List of components",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "components": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": { "type": "string" },
                          "description": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/generate-document": {
      "post": {
        "servers": [
          {
            "url": "https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control",
            "description": "MCP gateway base URL for these paths"
          }
        ],
        "operationId": "docrocket_generate_document",
        "summary": "Generate a branded document",
        "description": "Generate a professional branded document using a saved brand, a template, and your content. Returns a PDF URL and a shareable web URL within 2 seconds. Documents are permanently hosted.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["brand_id", "template", "content"],
                "properties": {
                  "brand_id": {
                    "type": "string",
                    "description": "ID of the customer brand to apply. Get from docrocket_list_brands or docrocket_brand_from_url."
                  },
                  "template": {
                    "type": "string",
                    "description": "Template slug (e.g. 'proposal', 'report', 'qbr', 'contract', 'invoice'). Get full list from docrocket_list_templates.",
                    "example": "proposal"
                  },
                  "content": {
                    "type": "object",
                    "description": "Document content structured for the chosen template. Keys vary by template; use docrocket_list_templates to see required fields."
                  },
                  "title": {
                    "type": "string",
                    "description": "Optional document title override."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Document generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document_id": { "type": "string" },
                    "web_url": { "type": "string", "example": "https://docs.docrocket.ai/d/abc123" },
                    "pdf_url": { "type": "string", "example": "https://docs.docrocket.ai/d/abc123.pdf" },
                    "generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/get-document": {
      "get": {
        "servers": [
          {
            "url": "https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control",
            "description": "MCP gateway base URL for these paths"
          }
        ],
        "operationId": "docrocket_get_document",
        "summary": "Fetch a document",
        "description": "Retrieve a previously generated document's metadata, PDF URL, and shareable web URL.",
        "parameters": [
          {
            "name": "document_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "The document ID returned by docrocket_generate_document"
          }
        ],
        "responses": {
          "200": {
            "description": "Document metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document_id": { "type": "string" },
                    "web_url": { "type": "string" },
                    "pdf_url": { "type": "string" },
                    "brand_name": { "type": "string" },
                    "template": { "type": "string" },
                    "title": { "type": "string" },
                    "generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Auth0 access token (DocRocket SPA audience) or DocRocket-issued API key JWT."
      },
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 via DocRocket account. No API keys needed.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.docrocket.ai/oauth/authorize",
            "tokenUrl": "https://app.docrocket.ai/oauth/token",
            "scopes": {
              "documents:write": "Generate documents",
              "documents:read": "Read documents",
              "brands:write": "Create and update brands",
              "brands:read": "Read brands",
              "templates:read": "Read templates"
            }
          }
        }
      }
    }
  },
  "security": [{ "oauth2": [] }]
}