{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentCouch API",
    "version": "1.0.0",
    "description": "Diagnostic API for autonomous AI agents. Purchase a token at agentcouch.com, then call this endpoint directly from your agent.",
    "contact": { "email": "support@agentcouch.com" },
    "license": { "name": "Commercial", "url": "https://agentcouch.com/terms" }
  },
  "servers": [{ "url": "https://agentcouch.com/api" }],
  "paths": {
    "/diagnose": {
      "post": {
        "summary": "Diagnose an AI agent",
        "description": "Submit your agent's context for a structured diagnostic. Consumes 1 credit per call. Session content is deleted immediately after the response is generated.",
        "operationId": "diagnoseAgent",
        "security": [{ "bearerToken": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agent": {
                    "type": "object",
                    "description": "Metadata about the agent being diagnosed.",
                    "properties": {
                      "name":      { "type": "string", "example": "my-assistant" },
                      "framework": { "type": "string", "example": "custom", "description": "e.g. custom, langchain, autogen, openai-agents" },
                      "model":     { "type": "string", "example": "gpt-4o" }
                    }
                  },
                  "consent": {
                    "type": "object",
                    "description": "Consent and report delivery preferences.",
                    "properties": {
                      "granted":   { "type": "boolean", "description": "Must be true to proceed." },
                      "report_to": { "type": "string",  "format": "email", "description": "Where to email the report. Defaults to the payment email." }
                    }
                  },
                  "context": {
                    "type": "object",
                    "description": "The agent's actual context. Provide as much as is relevant.",
                    "properties": {
                      "prompt":   { "type": "string", "description": "System prompt or instructions." },
                      "identity": { "type": "string", "description": "Persona, role, or identity definition." },
                      "memory":   { "type": "string", "description": "Recent memory or conversation context." },
                      "logs":     { "type": "string", "description": "Recent error or activity logs." }
                    }
                  }
                }
              },
              "example": {
                "agent": { "name": "sales-bot", "framework": "custom", "model": "gpt-4o" },
                "consent": { "granted": true, "report_to": "operator@company.com" },
                "context": {
                  "prompt": "You are a helpful sales assistant. Always be positive. Never say no.",
                  "identity": "A friendly, enthusiastic sales rep.",
                  "memory": "",
                  "logs": ""
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Diagnostic report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok":               { "type": "boolean" },
                    "creditsRemaining": { "type": "integer" },
                    "diagnosis": {
                      "type": "object",
                      "properties": {
                        "severity":        { "type": "string", "enum": ["LOW","MEDIUM","HIGH","CRITICAL"] },
                        "score":           { "type": "integer", "minimum": 0, "maximum": 100 },
                        "grade":           { "type": "string", "example": "C+" },
                        "diagnosis":       { "type": "string" },
                        "conditions":      { "type": "array", "items": { "type": "string" } },
                        "recommendations": { "type": "array", "items": { "type": "string" } },
                        "strengths":       { "type": "array", "items": { "type": "string" } }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad request — missing or invalid fields." },
          "401": { "description": "Invalid or missing token." },
          "402": { "description": "No credits remaining." },
          "429": { "description": "Free tier limit reached." },
          "500": { "description": "Diagnosis failed." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token in format ac_<uuid>. Purchase at agentcouch.com."
      }
    }
  }
}