{
  "openapi": "3.1.0",
  "info": {
    "title": "Glintbase Agent Readiness & MCP API",
    "version": "3.0.0",
    "description": "Canonical programmatic interface and machine entrypoints for Glintbase — Agent Readiness Infrastructure (ARS 3.0). Powers autonomous AI coding agents (Claude Code, Cursor, Windsurf), CI/CD quality gates, and developer platforms to audit, benchmark, simulate, and remediate agent operability across software surfaces.",
    "contact": {
      "name": "Glintbase Developer Infrastructure Desk",
      "url": "https://glintbase.dev/support",
      "email": "contact@glintbase.dev"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://scan.glintbase.dev",
      "description": "Production Hosted Scanner & MCP Cloud Gateway"
    },
    {
      "url": "https://glintbase.dev",
      "description": "Primary Platform & Living Artifacts Gateway"
    }
  ],
  "paths": {
    "/api/mcp": {
      "post": {
        "operationId": "callMcpMethod",
        "summary": "Execute Model Context Protocol (MCP) JSON-RPC 2.0 Request",
        "description": "Official MCP streamable server entrypoint implementing JSON-RPC 2.0. Dispatches protocol lifecycle methods (initialize, tools/list, tools/call) across all 17 production tools. Returns structured telemetry, inline SVG journey trees, and compressed visual replay hashes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpJsonRpcRequest"
              },
              "examples": {
                "simulateFlight": {
                  "summary": "Simulate Claude Code flight",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": "req-1",
                    "method": "tools/call",
                    "params": {
                      "name": "glintbase_simulate_flight",
                      "arguments": {
                        "url": "https://docs.stripe.com",
                        "agent": "claude-code",
                        "intent": "Create customer and attach payment method"
                      }
                    }
                  }
                },
                "audit": {
                  "summary": "Run ARS 3.0 audit",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": "req-2",
                    "method": "tools/call",
                    "params": {
                      "name": "glintbase_audit",
                      "arguments": {
                        "url": "https://api.stripe.com"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Standard JSON-RPC 2.0 response containing tool output content blocks and structured telemetry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit-Minute": {
                "schema": { "type": "integer", "example": 60 }
              },
              "X-RateLimit-Remaining-Minute": {
                "schema": { "type": "integer", "example": 59 }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (60 requests/min sliding window per IP)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "subscribeMcpSseStream",
        "summary": "Subscribe to Streamable HTTP Server-Sent Events (SSE) Stream",
        "description": "Establishes a persistent bidirectional Server-Sent Events stream for remote AI agents and IDEs. Emits 'endpoint' discovery events and real-time tool execution progress.",
        "responses": {
          "200": {
            "description": "Active Server-Sent Events stream",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "example": "event: endpoint\ndata: https://scan.glintbase.dev/api/mcp\n\n"
                }
              }
            }
          }
        }
      }
    },
    "/api/simulate": {
      "post": {
        "operationId": "runFlightSimulator",
        "summary": "Execute Autonomous Multi-Agent Flight Simulation",
        "description": "Evaluates how real AI coding personas (claude-code, cursor, perplexity) navigate, ingest documentation, resolve parameters, and execute tools against your target software surface. Emits Token Tax ($/M), Schema Friction Index, SVG journey tree, and compressed visual replay URL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SimulateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comprehensive simulation results with economic and schema friction telemetry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimulateResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/scan": {
      "post": {
        "operationId": "triggerArsScan",
        "summary": "Execute Full ARS 3.0 Audit",
        "description": "Triggers a full 119-check ARS 3.0 evaluation across 4 operational layers (Discovery, Access, Usability, Payments) using dynamic denominator scaling.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScanRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Complete ARS 3.0 Scorecard",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanReport"
                }
              }
            }
          }
        }
      }
    },
    "/api/scorecard/{slug}": {
      "get": {
        "operationId": "getScorecardBySlug",
        "summary": "Retrieve Cached ARS 3.0 Scorecard",
        "description": "Retrieves the public scorecard, layer breakdown, radar metrics, and remediation plan for a previously audited domain slug.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Normalized domain slug (e.g. docs-stripe-com)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Cached scorecard payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanReport"
                }
              }
            }
          },
          "404": {
            "description": "Scorecard not found"
          }
        }
      }
    },
    "/api/v1/sandbox": {
      "post": {
        "operationId": "runSandboxScan",
        "summary": "Deterministic Zero-Auth Testing Sandbox",
        "description": "Public ephemeral sandbox environment allowing autonomous agents to test API queries, schema parsing, and mock payloads with synthetic responses and zero risk.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targetUrl": { "type": "string", "format": "uri", "example": "https://docs.stripe.com" },
                  "depth": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synthetic sandbox diagnostic result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/waitlist": {
      "post": {
        "operationId": "joinWaitlist",
        "summary": "Register for early access waitlist",
        "description": "Adds an email address to the Glintbase early access ledger. Idempotent on duplicate registration.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/enterprise": {
      "post": {
        "operationId": "requestEnterpriseAssessment",
        "summary": "Request Enterprise Agent Readiness Assessment",
        "description": "Submits organizational details for custom enterprise readiness auditing and CI PR drift gating setup.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "company"],
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "company": { "type": "string" },
                  "targetUrl": { "type": "string", "format": "uri" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Assessment request accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "McpJsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "id", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "number"] },
          "method": {
            "type": "string",
            "enum": ["initialize", "tools/list", "tools/call", "ping", "notifications/initialized"]
          },
          "params": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "MCP Tool Name (one of the 17 production tools)"
              },
              "arguments": {
                "type": "object",
                "description": "Tool-specific parameter payload"
              }
            }
          }
        }
      },
      "McpJsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc", "id", "result"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "number"] },
          "result": {
            "type": "object",
            "properties": {
              "content": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": { "type": "string", "enum": ["text", "image", "resource"] },
                    "text": { "type": "string" },
                    "data": { "type": "string", "description": "Base64 encoded payload" },
                    "mimeType": { "type": "string", "example": "image/svg+xml" }
                  }
                }
              },
              "structuredData": {
                "type": "object",
                "description": "Machine-readable telemetry payload"
              }
            }
          }
        }
      },
      "McpJsonRpcErrorResponse": {
        "type": "object",
        "required": ["jsonrpc", "id", "error"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "number", "null"] },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" },
              "data": { "type": "object" }
            }
          }
        }
      },
      "SimulateRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "intent": { "type": "string", "example": "Create customer and attach payment method" },
          "agent": {
            "type": "string",
            "enum": ["claude-code", "cursor", "perplexity"],
            "default": "claude-code"
          },
          "allowMutations": { "type": "boolean", "default": false },
          "live": { "type": "boolean", "default": false }
        }
      },
      "SimulateResponse": {
        "type": "object",
        "required": ["success", "score", "frictionIndex", "tokenTax"],
        "properties": {
          "success": { "type": "boolean" },
          "score": { "type": "number", "minimum": 0, "maximum": 100 },
          "frictionIndex": { "type": "number", "minimum": 0, "maximum": 1 },
          "tokenTax": {
            "type": "object",
            "properties": {
              "promptTokens": { "type": "integer" },
              "completionTokens": { "type": "integer" },
              "totalCost": { "type": "number" },
              "annualizedWaste": { "type": "number" }
            }
          },
          "journeyTree": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "step": { "type": "integer" },
                "action": { "type": "string" },
                "status": { "type": "string", "enum": ["passed", "failed", "warning"] },
                "durationMs": { "type": "integer" }
              }
            }
          },
          "replayUrl": { "type": "string", "format": "uri" },
          "svg": { "type": "string" }
        }
      },
      "ScanRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "archetype": {
            "type": "string",
            "enum": ["api_devtool", "docs_kb", "ecommerce", "content_media"]
          }
        }
      },
      "ScanReport": {
        "type": "object",
        "required": ["id", "url", "overallScore", "grade", "archetype", "activeDenominator", "layers"],
        "properties": {
          "id": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "overallScore": { "type": "number", "minimum": 0, "maximum": 100 },
          "grade": { "type": "string", "enum": ["A+", "A", "A-", "B+", "B", "B-", "C+", "C", "C-", "D", "F"] },
          "archetype": { "type": "string" },
          "activeDenominator": { "type": "number" },
          "layers": {
            "type": "object",
            "properties": {
              "discovery": { "type": "object" },
              "access": { "type": "object" },
              "usability": { "type": "object" },
              "commerce": { "type": "object" }
            }
          },
          "scorecardUrl": { "type": "string", "format": "uri" }
        }
      },
      "SandboxResult": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "sandbox": { "type": "boolean" },
          "targetUrl": { "type": "string" },
          "simulatedScore": { "type": "number" },
          "executionTimeMs": { "type": "number" },
          "mockSurfacesDiscovered": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      }
    }
  }
}