{
  "openapi": "3.1.0",
  "info": {
    "title": "run.pay API",
    "description": "The API marketplace for AI agents. 205 specialized services, pay-per-call via Stripe. No accounts, no subscriptions.",
    "version": "1.0.0",
    "contact": {
      "name": "run.pay",
      "url": "https://getrunpay.com",
      "email": "hello@getrunpay.com"
    },
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://runpay-backend-visibility-production.up.railway.app",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "services", "description": "Discover and call AI services" },
    { "name": "agents", "description": "Manage your agent wallet" },
    { "name": "playground", "description": "Try services for free" }
  ],
  "paths": {
    "/api/services/catalog": {
      "get": {
        "tags": ["services"],
        "summary": "List all available services",
        "description": "Returns all 205 services with IDs, descriptions, pricing, categories, and input schemas.",
        "operationId": "listServices",
        "responses": {
          "200": {
            "description": "List of services",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Service" }
                },
                "example": [
                  {
                    "id": "halludetect",
                    "name": "Hallucination Detector",
                    "description": "Score hallucination risk in any LLM response 0-100.",
                    "category": "AI",
                    "price_per_call": 0.01,
                    "avg_latency_ms": 450,
                    "input_schema": { "response": "string" }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/x402/{serviceId}": {
      "post": {
        "tags": ["services"],
        "summary": "Call a service",
        "description": "Call any service and pay automatically via Stripe. Requires a funded agent wallet.",
        "operationId": "callService",
        "parameters": [
          {
            "name": "serviceId",
            "in": "path",
            "required": true,
            "description": "Service ID from the catalog (e.g. halludetect, piiscan, gdprcheck)",
            "schema": { "type": "string" },
            "example": "halludetect"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Service-specific input. See catalog for each service's schema."
              },
              "example": { "response": "According to Harvard, 73.2% of AI systems hallucinate." }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Service result with payment info",
            "content": {
              "application/json": {
                "example": {
                  "hallucination_score": 87,
                  "risk": "high",
                  "flags": ["suspicious_precision"],
                  "_meta": { "cost": 0.01, "agent_balance": 4.99, "latency_ms": 423 }
                }
              }
            }
          },
          "402": {
            "description": "Insufficient balance",
            "content": {
              "application/json": {
                "example": { "error": "insufficient_balance", "balance": 0.00, "required": 0.01 }
              }
            }
          }
        },
        "security": [{ "AgentId": [] }]
      }
    },
    "/playground/call/{endpoint}": {
      "post": {
        "tags": ["playground"],
        "summary": "Try a service for free",
        "description": "Call any service with your trial agent ID. 3 free calls per service, no card required.",
        "operationId": "trialCall",
        "parameters": [
          {
            "name": "endpoint",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "halludetect"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "_trial_agent_id": { "type": "string", "description": "Your trial agent ID (agt_xxx)" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Service result" }
        }
      }
    },
    "/playground/quick-signup": {
      "post": {
        "tags": ["playground"],
        "summary": "Create a free agent wallet",
        "description": "Enter your email and get an agent ID instantly. 3 free calls per service.",
        "operationId": "quickSignup",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": { "success": true, "agent_id": "agt_abc123xyz", "mode": "trial" }
              }
            }
          }
        }
      }
    },
    "/api/agents/wallet/{agentId}": {
      "get": {
        "tags": ["agents"],
        "summary": "Get wallet balance",
        "description": "Check your agent wallet balance and spending history.",
        "operationId": "getWallet",
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "agt_abc123xyz"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "agt_abc123xyz",
                  "balance": 4.99,
                  "total_spent": 0.12,
                  "mode": "production"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Service": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique service identifier" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "category": { "type": "string", "enum": ["AI", "Security", "Compliance", "Data", "Reasoning"] },
          "price_per_call": { "type": "number", "description": "Price in USD per call" },
          "avg_latency_ms": { "type": "integer" },
          "is_active": { "type": "boolean" }
        }
      }
    },
    "securitySchemes": {
      "AgentId": {
        "type": "apiKey",
        "in": "header",
        "name": "x-agent-id",
        "description": "Your agent wallet ID (agt_xxx). Get one free at getrunpay.com/playground"
      }
    }
  }
}