{
  "openapi": "3.0.3",
  "info": {
    "title": "Vibe Coding Workflow API",
    "description": "Public REST and streaming API for Vibe Coding Workflow (vibeworkflow.app / vibeworkflow.com). Generates deep market research, product requirements documents (PRDs), software architecture technical designs, and universal agent configurations (AGENTS.md, CLAUDE.md).",
    "version": "1.0.0",
    "termsOfService": "https://vibeworkflow.app/terms",
    "contact": {
      "name": "Vibe Workflow Developer Support",
      "url": "https://vibeworkflow.app/developers",
      "email": "hello@vibeworkflow.app"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "x-api-versioning-policy": {
      "strategy": "URL Path Versioning (/v1/) and Header Versioning (X-API-Version)",
      "currentVersion": "1.0.0",
      "deprecationPolicy": "Endpoints are maintained for a minimum of 180 days after deprecation notice. Deprecation is communicated via Deprecation and Sunset HTTP response headers as per RFC 8594.",
      "documentation": "https://vibeworkflow.app/auth.md"
    }
  },
  "servers": [
    {
      "url": "https://vibeworkflow.app/api/v1",
      "description": "Production Server (v1)"
    },
    {
      "url": "https://vibeworkflow.app",
      "description": "Production Base Server"
    },
    {
      "url": "https://vibeworkflow.com",
      "description": "Primary Domain Mirror"
    }
  ],
  "paths": {
    "/generate": {
      "post": {
        "operationId": "generateTextStream",
        "summary": "Stream LLM Text Generation",
        "description": "Streams multi-provider LLM generations (Gemini, OpenAI, Anthropic, xAI, DeepSeek, Groq, Mistral, OpenRouter) with optional Google Search Grounding and reasoning effort controls.",
        "security": [
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful streaming text response with metadata trailer",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }
            },
            "content": {
              "text/plain; charset=utf-8": {
                "schema": {
                  "type": "string",
                  "description": "Streamed text output followed by a record separator and JSON metadata trailer."
                }
              }
            }
          },
          "400": {
            "description": "Validation Error - Invalid parameters or missing payload",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid provider API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate Limit Exceeded",
            "headers": {
              "Retry-After": { "$ref": "#/components/headers/Retry-After" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/deep-research": {
      "post": {
        "operationId": "startDeepResearch",
        "summary": "Initiate Deep Market & Technical Research",
        "description": "Spawns a multi-turn deep research session using Google Gemini Search Grounding to evaluate market competitors, tech stacks, and architectural feasibility.",
        "security": [
          { "ApiKeyAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeepResearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Research session initiated",
            "headers": {
              "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": {
                  "type": "object",
                  "required": ["interactionId"],
                  "properties": {
                    "interactionId": {
                      "type": "string",
                      "description": "Unique session ID for polling research progress."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/deep-research-poll": {
      "post": {
        "operationId": "pollDeepResearchStatus",
        "summary": "Poll Deep Research Status",
        "description": "Polls the execution status of an ongoing deep research interaction and retrieves the markdown synthesis upon completion.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["interactionId", "apiKey"],
                "properties": {
                  "interactionId": {
                    "type": "string",
                    "description": "Interaction ID returned by /api/deep-research."
                  },
                  "apiKey": {
                    "type": "string",
                    "description": "Google Gemini API key."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Research status and payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["status"],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": ["running", "completed", "failed"]
                    },
                    "result": {
                      "type": "string",
                      "description": "Markdown formatted research synthesis when completed."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid Request Parameters",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/agent-workflow": {
      "post": {
        "operationId": "executeAgentWorkflow",
        "summary": "Execute Multi-Stage Agent Planning Workflow",
        "description": "Executes automated multi-step specification synthesis (PRD, Technical Architecture, AGENTS.md) for autonomous agents.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentWorkflowRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workflow execution started or completed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["workflowId", "status"],
                  "properties": {
                    "workflowId": { "type": "string" },
                    "status": { "type": "string", "enum": ["queued", "processing", "completed", "failed"] },
                    "output": { "type": "object" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid Workflow Parameters",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/sandbox-exec": {
      "post": {
        "operationId": "executeSandboxCode",
        "summary": "Execute Code in Cloudflare Isolated Sandbox",
        "description": "Securely runs generated code or test scripts inside an isolated sandbox environment.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SandboxExecRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code execution result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success"],
                  "properties": {
                    "success": { "type": "boolean" },
                    "stdout": { "type": "string" },
                    "stderr": { "type": "string" },
                    "exitCode": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Sandbox Execution Failure",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-provider-key",
        "description": "Provider API Key (Gemini, OpenAI, Anthropic, OpenRouter, etc.)"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API_KEY",
        "description": "Bearer token containing the provider API key"
      }
    },
    "headers": {
      "RateLimit-Limit": {
        "schema": { "type": "integer", "example": 60 },
        "description": "Number of allowed requests per minute window."
      },
      "RateLimit-Remaining": {
        "schema": { "type": "integer", "example": 59 },
        "description": "Number of remaining requests in the current window."
      },
      "RateLimit-Reset": {
        "schema": { "type": "integer", "example": 60 },
        "description": "Time in seconds until rate-limit quota resets."
      },
      "Retry-After": {
        "schema": { "type": "integer", "example": 60 },
        "description": "Number of seconds to wait before retrying a throttled request."
      },
      "X-Request-Id": {
        "schema": { "type": "string", "example": "gen_m8x9y0za" },
        "description": "Unique correlation identifier for tracing."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error", "status"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "VALIDATION_ERROR",
                  "AUTH_ERROR",
                  "QUOTA_ERROR",
                  "RATE_LIMIT_EXCEEDED",
                  "TIMEOUT_ERROR",
                  "PROVIDER_ERROR",
                  "NOT_FOUND",
                  "METHOD_NOT_ALLOWED",
                  "INTERNAL_ERROR"
                ],
                "description": "Machine-readable error classification."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "resolutionHint": {
                "type": "string",
                "description": "Actionable instructions to resolve the error."
              },
              "details": {
                "type": "string",
                "nullable": true,
                "description": "Optional technical diagnostics or error stack summary."
              }
            }
          },
          "status": {
            "type": "integer",
            "example": 400,
            "description": "HTTP status code."
          },
          "requestId": {
            "type": "string",
            "example": "req_8f7b3c2a",
            "description": "Request correlation ID."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of the error response."
          }
        }
      },
      "GenerateRequest": {
        "type": "object",
        "required": ["providerId", "apiKey", "model", "prompt"],
        "properties": {
          "providerId": {
            "type": "string",
            "enum": ["gemini", "openai", "anthropic", "xai", "deepseek", "groq", "mistral", "openrouter", "qwen", "nvidia"],
            "description": "Target LLM provider."
          },
          "apiKey": {
            "type": "string",
            "description": "API key for the selected AI provider."
          },
          "model": {
            "type": "string",
            "description": "Specific model identifier (e.g. gemini-2.5-pro, gpt-4o, claude-3-7-sonnet-latest)."
          },
          "prompt": {
            "type": "string",
            "description": "User prompt text."
          },
          "system": {
            "type": "string",
            "description": "Optional system instructions."
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "default": 0.7
          },
          "maxOutputTokens": {
            "type": "integer",
            "minimum": 1
          },
          "useGrounding": {
            "type": "boolean",
            "description": "Enable Google Search Grounding for Gemini models."
          },
          "reasoningEffort": {
            "type": "string",
            "enum": ["low", "medium", "high", "xhigh", "max"],
            "description": "Reasoning effort level for thinking models."
          }
        }
      },
      "DeepResearchRequest": {
        "type": "object",
        "required": ["prompt", "apiKey"],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Research goal, product concept, or feasibility question."
          },
          "apiKey": {
            "type": "string",
            "description": "Google Gemini API key."
          },
          "customInstructions": {
            "type": "string",
            "description": "Optional additional research constraints."
          }
        }
      },
      "AgentWorkflowRequest": {
        "type": "object",
        "required": ["stages", "projectName", "idea"],
        "properties": {
          "projectName": {
            "type": "string",
            "description": "Name of the project."
          },
          "idea": {
            "type": "string",
            "description": "Core software product idea."
          },
          "persona": {
            "type": "string",
            "enum": ["vibe-coder", "developer", "learner"],
            "default": "developer"
          },
          "stages": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["research", "prd", "architecture", "agents_md", "export"]
            }
          }
        }
      },
      "SandboxExecRequest": {
        "type": "object",
        "required": ["code", "language"],
        "properties": {
          "language": {
            "type": "string",
            "enum": ["javascript", "typescript", "python", "bash"]
          },
          "code": {
            "type": "string",
            "description": "Code string to execute in isolation."
          },
          "timeoutSeconds": {
            "type": "integer",
            "default": 30,
            "maximum": 60
          }
        }
      }
    }
  }
}