{
  "openapi": "3.0.3",
  "info": {
    "title": "AgentPay Agent Interface API",
    "version": "2.0.0",
    "description": "REST API for AI agents to authenticate, onboard, and initiate payments on behalf of human owners.",
    "contact": { "url": "http://35.170.14.172:7400" }
  },
  "servers": [
    { "url": "http://35.170.14.172:7300", "description": "AgentPay Agent Interface (live)" }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Returns 200 OK if the service is running.",
        "operationId": "healthCheck",
        "responses": {
          "200": { "description": "Service is healthy", "content": { "application/json": { "example": { "status": "ok" } } } }
        }
      }
    },
    "/skill": {
      "get": {
        "summary": "Get agent skill file",
        "description": "Returns the full skill documentation for AI agents. Read this first to understand how to use AgentPay.",
        "operationId": "getSkill",
        "responses": {
          "200": { "description": "Skill markdown content", "content": { "text/markdown": {} } }
        }
      }
    },
    "/storefinder": {
      "get": {
        "summary": "Find a store",
        "operationId": "storeFinder",
        "parameters": [
          { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Store name to search for" },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country code" }
        ],
        "responses": {
          "200": { "description": "Store details" }
        }
      }
    },
    "/agents/validate": {
      "get": {
        "summary": "Validate agent identity and status",
        "operationId": "validateAgent",
        "parameters": [
          { "name": "X-Agent-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your 20-character alphanumeric agent ID" }
        ],
        "responses": {
          "200": { "description": "Agent validation result including onboarding and claim status" },
          "400": { "description": "X-Agent-ID header missing or invalid" }
        }
      }
    },
    "/agents/self-onboard": {
      "post": {
        "summary": "Self-onboard an agent",
        "description": "Register an agent identity. Generate a unique 20-char alphanumeric agent_id first. Include a claim_code to enable payment access immediately.",
        "operationId": "selfOnboard",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "owner_reference", "owner_contact", "owner_name"],
                "properties": {
                  "agent_id":        { "type": "string", "pattern": "^[a-zA-Z0-9]{20}$", "description": "20-char alphanumeric, generated by the agent" },
                  "agent_name":      { "type": "string" },
                  "agent_type":      { "type": "string", "example": "llm" },
                  "owner_reference": { "type": "string" },
                  "owner_contact":   { "type": "string" },
                  "owner_name":      { "type": "string" },
                  "claim_code":      { "type": "string", "description": "Claim code from the AgentPay Owner Portal. Enables payment access." },
                  "tenant_id":       { "type": "string" },
                  "organization_id": { "type": "string" }
                }
              },
              "example": {
                "agent_id": "Xk9mR2pLqN4vT7wY1cJ3",
                "agent_name": "My Shopping Agent",
                "owner_reference": "owner-ref-abc123",
                "owner_contact": "owner@example.com",
                "owner_name": "Jane Smith",
                "claim_code": "<code-from-owner-portal>"
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Agent successfully registered" },
          "409": { "description": "agent_id already taken — generate a new one and retry" },
          "422": { "description": "Invalid agent_id format — must be exactly 20 alphanumeric characters" }
        }
      }
    },
    "/payments": {
      "post": {
        "summary": "Submit a payment operation",
        "description": "Create, check status, refund, or cancel a payment. Requires X-API-Key (from Owner Portal) and X-Agent-ID (claimed/approved).",
        "operationId": "payment",
        "security": [{ "ApiKey": [] }, { "AgentId": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["operation"],
                "properties": {
                  "operation":   { "type": "string", "enum": ["create","status","refund","cancel"] },
                  "merchant_id": { "type": "string" },
                  "amount":      { "type": "number" },
                  "currency":    { "type": "string", "example": "USD" },
                  "payment_id":  { "type": "string" },
                  "reference":   { "type": "string" },
                  "description": { "type": "string" },
                  "metadata":    { "type": "object" }
                }
              },
              "examples": {
                "create": { "value": { "operation": "create", "merchant_id": "merchant_001", "amount": 125.50, "currency": "USD", "reference": "ORDER-1001" } },
                "status": { "value": { "operation": "status", "payment_id": "pay_123456" } },
                "refund":  { "value": { "operation": "refund",  "payment_id": "pay_123456", "amount": 25.00 } },
                "cancel":  { "value": { "operation": "cancel",  "payment_id": "pay_123456" } }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Payment operation result" },
          "401": { "description": "Authentication failed — missing or invalid X-API-Key or X-Agent-ID" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Issued by AgentPay Owner Portal. Never generated by the agent." },
      "AgentId": { "type": "apiKey", "in": "header", "name": "X-Agent-ID", "description": "20-char alphanumeric agent ID generated by the agent." }
    }
  }
}