{
  "openapi": "3.1.0",
  "info": {
    "title": "draft1 API",
    "version": "1.0.0",
    "description": "Generate and edit editable draw.io (mxGraph) architecture diagrams from plain English, Terraform, docker-compose, or SQL schemas. Designed for agents: every dashboard capability that matters is available here.",
    "contact": { "url": "https://www.draft1.ai" },
    "x-agent-friendly": true
  },
  "servers": [{ "url": "https://api.app.draft1.ai/api/v1" }],
  "security": [{ "ApiKeyAuth": [] }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Create a key at https://app.draft1.ai/settings/api"
      }
    },
    "schemas": {
      "Diagram": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Diagram id; pass to PATCH or GET" },
          "projectId": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" },
          "answer": { "type": "string", "nullable": true, "description": "Model's prose reply" },
          "xml": { "type": "string", "nullable": true, "description": "draw.io editor URL for the mxGraph document" },
          "pngUrl": { "type": "string", "nullable": true, "description": "Rendered preview URL" },
          "shareUrl": { "type": "string", "nullable": true, "description": "Public share page" },
          "success": { "type": "boolean" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      }
    }
  },
  "paths": {
    "/me": {
      "get": {
        "operationId": "getAccount",
        "summary": "Account and remaining quota",
        "description": "Check plan and remaining generations BEFORE spending a turn. remaining is null when the plan is unlimited.",
        "responses": {
          "200": {
            "description": "Account info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "userId": { "type": "string" },
                    "email": { "type": "string", "nullable": true },
                    "plan": { "type": "string" },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "used": { "type": "integer" },
                        "limit": { "type": "integer", "nullable": true },
                        "remaining": { "type": "integer", "nullable": true },
                        "unlimited": { "type": "boolean" },
                        "monthlyCapped": { "type": "boolean" }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/diagrams": {
      "get": {
        "operationId": "listDiagrams",
        "summary": "List diagrams created with this key",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Pass the previous response's nextCursor" }
        ],
        "responses": {
          "200": {
            "description": "Page of diagrams",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Diagram" } },
                    "nextCursor": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid key" }
        }
      },
      "post": {
        "operationId": "createDiagram",
        "summary": "Generate a diagram",
        "description": "Takes ~20-60 seconds. Describe the system in plain English, or paste Terraform / docker-compose / a SQL schema.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": { "type": "string", "description": "Plain-English description or source text" },
                  "format": { "type": "string", "enum": ["auto", "terraform", "docker-compose", "sql", "mermaid"], "default": "auto" },
                  "projectId": { "type": "string", "description": "Optional: add to an existing project" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Diagram created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Diagram" } } } },
          "400": { "description": "Body must include a string prompt" },
          "402": { "description": "Out of credits. Upgrade or buy a credit pack." },
          "401": { "description": "Missing or invalid key" }
        }
      }
    },
    "/diagrams/{id}": {
      "get": {
        "operationId": "getDiagram",
        "summary": "Retrieve one diagram",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Diagram", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Diagram" } } } },
          "404": { "description": "Diagram not found" }
        }
      },
      "patch": {
        "operationId": "editDiagram",
        "summary": "Iterate on an existing diagram in plain English",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["instruction"],
                "properties": {
                  "instruction": { "type": "string", "description": "e.g. 'add a Redis cache between the API and the database'" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated diagram", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Diagram" } } } },
          "404": { "description": "Diagram not found" },
          "402": { "description": "Out of credits" }
        }
      }
    }
  }
}