{
  "openapi": "3.0.3",
  "info": {
    "title": "Vibe Coding Workflow API",
    "description": "Public REST and streaming API for Vibe Coding Workflow (vibeworkflow.app). 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.app",
      "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
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Vibe Coding Workflow developer portal, MCP server, and pricing (free, no sign-up)",
    "url": "https://vibeworkflow.app/developers"
  },
  "x-mcp": {
    "transport": "streamable-http",
    "url": "https://vibeworkflow.app/mcp",
    "authentication": "none",
    "manifest": "https://vibeworkflow.app/.well-known/mcp.json",
    "protocolVersions": [
      "2025-06-18",
      "2025-03-26",
      "2024-11-05"
    ]
  },
  "x-pricing": {
    "model": "freemium",
    "currency": "USD",
    "signupRequired": false,
    "apiKeyIssuedByProvider": false,
    "apiAccessCost": "free",
    "description": "The workflow, exports, local projects and use of your own API key remain free. Optional Paddle subscriptions include monthly hosted AI credits and cloud features.",
    "plans": [
      {
        "name": "Free",
        "price": "0",
        "billingPeriod": "month",
        "hostedModel": "Gemma 4 (Free AI)",
        "cloudProjectSlots": 0,
        "cloudBackupAndSync": false,
        "localProjects": "unlimited",
        "hostedModelIds": [
          "@cf/google/gemma-4-26b-a4b-it"
        ],
        "hostedAiCreditsPerMonth": 50
      },
      {
        "name": "Basic",
        "price": "5",
        "priceYearly": "50",
        "billingPeriod": "month",
        "cloudProjectSlots": 15,
        "hostedModel": "GLM-5.3 Flash",
        "cloudBackupAndSync": true,
        "localProjects": "unlimited",
        "hostedModelIds": [
          "@cf/zai-org/glm-5.3-flash"
        ],
        "merchantOfRecord": "Paddle",
        "hostedAiCreditsPerMonth": 300
      },
      {
        "name": "Pro",
        "price": "15",
        "priceYearly": "150",
        "billingPeriod": "month",
        "cloudProjectSlots": 50,
        "hostedModel": "GLM-5.3 Flash; optional GLM-5.3 or DeepSeek V4 Pro",
        "cloudBackupAndSync": true,
        "localProjects": "unlimited",
        "hostedModelIds": [
          "@cf/zai-org/glm-5.3-flash",
          "@cf/zai-org/glm-5.3",
          "@cf/deepseek-ai/deepseek-v4-pro-0813"
        ],
        "merchantOfRecord": "Paddle",
        "hostedAiCreditsPerMonth": 1000,
        "planReview": true,
        "cloudSnapshotsPerProject": 20,
        "privateTemplates": 20,
        "libraryStorageBytes": 104857600
      }
    ],
    "url": "https://vibeworkflow.app/pricing",
    "localProjects": "unlimited on every plan; the cloudProjectSlots figures apply only to cloud-synced projects",
    "creditsReset": "monthly, including annual subscriptions",
    "creditRollover": false,
    "creditPacks": false
  }
}