{
  "openapi": "3.1.0",
  "info": {
    "title": "SkillBoss API",
    "description": "The wallet for AI agents. Agent Shopping Protocol v0.1 reference implementation.\n\nUnified API gateway for 100+ AI models and services. OpenAI-compatible endpoints for seamless integration with Claude Code, Cursor, Windsurf, and autonomous AI agents.\n\n## Quick Start\n\n```bash\ncurl -fsSL https://skillboss.co/install.sh | bash\n```\n\nOr use directly:\n\n```python\nfrom openai import OpenAI\nclient = OpenAI(base_url=\"https://api.skillboss.co/v1\", api_key=\"YOUR_KEY\")\n```\n\n## Agent Shopping Protocol v0.1\n\nSkillBoss ships the first reference implementation of the Agent Shopping Protocol (ASP) — a standard set of endpoints that let autonomous agents discover capabilities, estimate costs, spend safely, and verify receipts without human involvement.\n\nASP endpoints live under `/api/*` and cover: bootstrap, status, catalog, anonymous wallet trials, cost estimation, idempotent runs, signed receipts, spending rules, sub-wallet delegation, reviews, and referrals.",
    "version": "1.3.0",
    "contact": {
      "name": "SkillBoss Support",
      "email": "support@skillboss.co",
      "url": "https://www.skillboss.co/docs"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.skillboss.co/legal/terms-and-conditions"
    },
    "x-logo": {
      "url": "https://www.skillboss.co/og-image.png"
    }
  },
  "servers": [
    {
      "url": "https://api.skillboss.co/v1",
      "description": "Production API (OpenAI-compatible inference)"
    },
    {
      "url": "https://www.skillboss.co",
      "description": "Production control plane (Agent Shopping Protocol v0.1 endpoints under /api/*)"
    }
  ],
  "security": [{"BearerAuth": []}],
  "tags": [
    {
      "name": "Chat",
      "description": "Chat completion endpoints (OpenAI-compatible)"
    },
    {
      "name": "Models",
      "description": "List and retrieve available models"
    },
    {
      "name": "Agent Onboarding",
      "description": "Agent Shopping Protocol v0.1 — one-shot discovery and onboarding for autonomous agents"
    },
    {
      "name": "Catalog",
      "description": "Agent Shopping Protocol v0.1 — machine-readable catalog of models, skills, and pricing"
    },
    {
      "name": "Wallet",
      "description": "Agent Shopping Protocol v0.1 — wallet, spending rules, and sub-wallet delegation"
    },
    {
      "name": "Estimation",
      "description": "Agent Shopping Protocol v0.1 — pre-flight cost estimation and idempotent execution"
    },
    {
      "name": "Receipts",
      "description": "Agent Shopping Protocol v0.1 — signed JWT receipts and JWKS verification"
    },
    {
      "name": "Social Proof",
      "description": "Agent Shopping Protocol v0.1 — reviews and referral program"
    }
  ],
  "paths": {
    "/chat/completions": {
      "post": {
        "tags": ["Chat"],
        "operationId": "createChatCompletion",
        "summary": "Create chat completion",
        "description": "Create a chat completion using any of 50+ available models. Fully OpenAI-compatible - works with all OpenAI SDKs.\n\n**Supported Models:**\n- `claude-4-5-sonnet` - Best for complex reasoning\n- `gpt-5` - Latest OpenAI capabilities\n- `gemini-2.5-flash` - Fast and cost-effective\n- `deepseek/deepseek-v3` - Budget-friendly with caching\n\nSee `/models` for complete list.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic request",
                  "value": {
                    "model": "claude-4-5-sonnet",
                    "messages": [
                      {"role": "user", "content": "Hello!"}
                    ]
                  }
                },
                "with_system": {
                  "summary": "With system prompt",
                  "value": {
                    "model": "gpt-5",
                    "messages": [
                      {"role": "system", "content": "You are a helpful assistant."},
                      {"role": "user", "content": "What is 2+2?"}
                    ],
                    "max_tokens": 100
                  }
                },
                "streaming": {
                  "summary": "Streaming response",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "messages": [
                      {"role": "user", "content": "Write a haiku about AI"}
                    ],
                    "stream": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful completion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-sent events stream when stream=true"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid parameters",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "error": {
                    "message": "Invalid API key. Get one at https://skillboss.co/console",
                    "type": "authentication_error",
                    "code": "invalid_api_key"
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required - insufficient credits",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "error": {
                    "message": "Insufficient credits. Add more at https://skillboss.co/console",
                    "type": "insufficient_credits",
                    "code": "insufficient_credits"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": { "type": "integer" },
                "description": "Requests per minute allowed"
              },
              "X-RateLimit-Remaining": {
                "schema": { "type": "integer" },
                "description": "Requests remaining in current window"
              },
              "X-RateLimit-Reset": {
                "schema": { "type": "integer" },
                "description": "Unix timestamp when limit resets"
              }
            }
          },
          "503": {
            "description": "Service temporarily unavailable",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/models": {
      "get": {
        "tags": ["Models"],
        "operationId": "listModels",
        "summary": "List available models",
        "description": "Returns a list of all available models with their capabilities and pricing information.",
        "responses": {
          "200": {
            "description": "List of models",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            }
          }
        }
      }
    },
    "/models/{model_id}": {
      "get": {
        "tags": ["Models"],
        "operationId": "getModel",
        "summary": "Get model details",
        "description": "Retrieve details about a specific model including pricing and capabilities.",
        "parameters": [
          {
            "name": "model_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "claude-4-5-sonnet"
          }
        ],
        "responses": {
          "200": {
            "description": "Model details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Model" }
              }
            }
          },
          "404": {
            "description": "Model not found"
          }
        }
      }
    },
    "/api/agent/bootstrap": {
      "get": {
        "tags": ["Agent Onboarding"],
        "operationId": "agentBootstrap",
        "summary": "One-shot agent onboarding",
        "description": "Part of **Agent Shopping Protocol v0.1**. Returns everything an autonomous agent needs to start transacting with SkillBoss in a single response: service metadata, auth endpoints, catalog URL, anonymous-wallet trial endpoint, estimate/idempotent-run endpoints, receipts JWKS, and version info. Agents hit this first — no other discovery calls needed.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "security": [],
        "responses": {
          "200": {
            "description": "Bootstrap manifest",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentBootstrap" },
                "example": {
                  "service": "SkillBoss",
                  "version": "1.3.0",
                  "protocol": "agent-shopping-protocol/0.1",
                  "endpoints": {
                    "catalog": "https://www.skillboss.co/api/catalog",
                    "status": "https://www.skillboss.co/api/status",
                    "anonymous_wallet": "https://www.skillboss.co/api/try/anonymous-wallet",
                    "estimate": "https://www.skillboss.co/api/estimate",
                    "idempotent_run": "https://www.skillboss.co/api/idempotent-run",
                    "receipts_jwks": "https://www.skillboss.co/api/receipts/jwks",
                    "receipts_verify": "https://www.skillboss.co/api/receipts/verify",
                    "inference_base_url": "https://api.skillboss.co/v1"
                  },
                  "auth": {
                    "scheme": "Bearer",
                    "console": "https://skillboss.co/console"
                  },
                  "free_tier_credits": 20
                }
              }
            }
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "tags": ["Agent Onboarding"],
        "operationId": "getStatus",
        "summary": "Machine-readable health",
        "description": "Part of **Agent Shopping Protocol v0.1**. Structured health response agents can poll before routing traffic. Returns overall status plus per-subsystem availability (inference, wallet, receipts, catalog) so agents can failover intelligently instead of parsing HTML status pages.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "security": [],
        "responses": {
          "200": {
            "description": "Status snapshot",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StatusResponse" },
                "example": {
                  "status": "ok",
                  "version": "1.3.0",
                  "subsystems": {
                    "inference": "ok",
                    "wallet": "ok",
                    "receipts": "ok",
                    "catalog": "ok"
                  },
                  "timestamp": "2026-04-11T10:00:00Z"
                }
              }
            }
          }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "tags": ["Catalog"],
        "operationId": "getCatalog",
        "summary": "Machine-readable capability catalog",
        "description": "Part of **Agent Shopping Protocol v0.1**. Full catalog of models, skills, vendors, and live pricing in a single JSON document. Designed for agents to cache locally, diff over time, and make routing decisions without scraping pricing pages.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "security": [],
        "responses": {
          "200": {
            "description": "Catalog document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Catalog" }
              }
            }
          }
        }
      }
    },
    "/api/try/anonymous-wallet": {
      "post": {
        "tags": ["Wallet"],
        "operationId": "createAnonymousWallet",
        "summary": "Zero-signup $0.50 trial wallet",
        "description": "Part of **Agent Shopping Protocol v0.1**. Mints a disposable, pre-funded wallet (default $0.50) with no signup, no email, no credit card. Agents use this to smoke-test the API before committing a user to a real account. Rate-limited by IP and device fingerprint.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AnonymousWalletRequest" },
              "example": {
                "agent_id": "claude-code/1.0",
                "purpose": "smoke-test"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Anonymous wallet created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AnonymousWalletResponse" },
                "example": {
                  "wallet_id": "anon_7xJk2Lm9",
                  "api_key": "sk-anon-XXXXXXXXXXXX",
                  "balance_usd": 0.50,
                  "expires_at": "2026-04-12T10:00:00Z",
                  "upgrade_url": "https://skillboss.co/console?claim=anon_7xJk2Lm9"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded — try again later"
          }
        }
      }
    },
    "/api/estimate": {
      "post": {
        "tags": ["Estimation"],
        "operationId": "estimateCost",
        "summary": "Pre-flight cost estimate",
        "description": "Part of **Agent Shopping Protocol v0.1**. Returns the predicted cost (USD) of a request before execution, based on model pricing plus tokenized input size. Lets agents check affordability against wallet balance and spending rules before committing.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EstimateRequest" },
              "example": {
                "model": "claude-4-5-sonnet",
                "messages": [
                  {"role": "user", "content": "Summarize this 4000-word doc..."}
                ],
                "max_tokens": 1000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cost estimate",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EstimateResponse" },
                "example": {
                  "model": "claude-4-5-sonnet",
                  "estimated_input_tokens": 5400,
                  "estimated_output_tokens": 1000,
                  "estimated_cost_usd": 0.0312,
                  "confidence": "high",
                  "currency": "USD"
                }
              }
            }
          }
        }
      }
    },
    "/api/idempotent-run": {
      "post": {
        "tags": ["Estimation"],
        "operationId": "idempotentRun",
        "summary": "Idempotent /v1/run wrapper",
        "description": "Part of **Agent Shopping Protocol v0.1**. Wraps `/v1/run` with an idempotency key so retries after network failures never double-charge. Identical `idempotency_key` values within 24 hours return the cached result instead of re-executing. Critical for unreliable agent environments.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "Client-generated unique key (UUID recommended). Identical keys within 24h return the cached response."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/IdempotentRunRequest" },
              "example": {
                "model": "claude-4-5-sonnet",
                "inputs": {
                  "messages": [{"role": "user", "content": "Hello"}]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Run result (fresh or cached). Check `x-idempotent-replay` header to tell them apart.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/IdempotentRunResponse" }
              }
            },
            "headers": {
              "x-idempotent-replay": {
                "schema": { "type": "boolean" },
                "description": "true if this response was replayed from the idempotency cache"
              }
            }
          }
        }
      }
    },
    "/api/receipts/verify": {
      "post": {
        "tags": ["Receipts"],
        "operationId": "verifyReceipt",
        "summary": "Verify signed JWT receipt",
        "description": "Part of **Agent Shopping Protocol v0.1**. Verifies the signature and claims of a SkillBoss receipt JWT. Receipts are issued for every billed request and can be independently verified offline via JWKS — this endpoint is a convenience for agents that don't want to implement JWT validation themselves.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReceiptVerifyRequest" },
              "example": {
                "receipt": "eyJhbGciOiJFUzI1NiIsImtpZCI6InNiLTIwMjYtMDQifQ..."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ReceiptVerifyResponse" },
                "example": {
                  "valid": true,
                  "claims": {
                    "iss": "https://skillboss.co",
                    "sub": "wallet_abc123",
                    "request_id": "req_xyz789",
                    "model": "claude-4-5-sonnet",
                    "cost_usd": 0.0312,
                    "iat": 1744368000
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or malformed receipt"
          }
        }
      }
    },
    "/api/receipts/jwks": {
      "get": {
        "tags": ["Receipts"],
        "operationId": "getReceiptsJwks",
        "summary": "Public JWKS for receipt verification",
        "description": "Part of **Agent Shopping Protocol v0.1**. Public JSON Web Key Set for verifying SkillBoss receipt JWT signatures offline. Standard RFC 7517 format — drop into any JWT library. Keys rotate quarterly; cache with respect to `Cache-Control` headers.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "security": [],
        "responses": {
          "200": {
            "description": "JWKS document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Jwks" },
                "example": {
                  "keys": [
                    {
                      "kty": "EC",
                      "crv": "P-256",
                      "kid": "sb-2026-04",
                      "use": "sig",
                      "alg": "ES256",
                      "x": "...",
                      "y": "..."
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/wallet/rules": {
      "get": {
        "tags": ["Wallet"],
        "operationId": "getWalletRules",
        "summary": "Get spending rules",
        "description": "Part of **Agent Shopping Protocol v0.1**. Returns the current spending rules for the authenticated wallet: daily caps, per-request caps, allowed models, blocked vendors, alert thresholds.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "responses": {
          "200": {
            "description": "Current rules",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WalletRules" },
                "example": {
                  "daily_cap_usd": 25.00,
                  "per_request_cap_usd": 1.00,
                  "allowed_models": ["claude-4-5-sonnet", "gpt-5", "deepseek/deepseek-v3"],
                  "blocked_vendors": [],
                  "alert_threshold_usd": 20.00
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["Wallet"],
        "operationId": "updateWalletRules",
        "summary": "Update spending rules",
        "description": "Part of **Agent Shopping Protocol v0.1**. Replaces the wallet's spending rules. Enforced server-side on every request — requests that would breach the rules return HTTP 402 before the vendor is called.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WalletRules" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rules updated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WalletRules" }
              }
            }
          }
        }
      }
    },
    "/api/wallet/sub-wallets": {
      "get": {
        "tags": ["Wallet"],
        "operationId": "listSubWallets",
        "summary": "List sub-wallets",
        "description": "Part of **Agent Shopping Protocol v0.1**. Lists sub-wallets delegated from the parent wallet. Sub-wallets have their own API keys, caps, and rules — used to hand scoped spending power to child agents without sharing the root key.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "responses": {
          "200": {
            "description": "Sub-wallet list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sub_wallets": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/SubWallet" }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Wallet"],
        "operationId": "createSubWallet",
        "summary": "Create a sub-wallet",
        "description": "Part of **Agent Shopping Protocol v0.1**. Mints a new sub-wallet with its own API key, budget, and rule set. Useful for giving child agents their own scoped spending authority.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SubWalletCreateRequest" },
              "example": {
                "label": "research-agent",
                "budget_usd": 5.00,
                "rules": {
                  "daily_cap_usd": 5.00,
                  "per_request_cap_usd": 0.25
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sub-wallet created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SubWallet" }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Wallet"],
        "operationId": "deleteSubWallet",
        "summary": "Revoke a sub-wallet",
        "description": "Part of **Agent Shopping Protocol v0.1**. Revokes a sub-wallet by id. Any remaining balance returns to the parent wallet; the sub-wallet's API key stops working immediately.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "parameters": [
          {
            "name": "sub_wallet_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "example": "sw_abc123"
          }
        ],
        "responses": {
          "200": {
            "description": "Sub-wallet revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sub_wallet_id": { "type": "string" },
                    "revoked_at": { "type": "string", "format": "date-time" },
                    "refunded_usd": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reviews": {
      "get": {
        "tags": ["Social Proof"],
        "operationId": "listReviews",
        "summary": "List skill reviews",
        "description": "Part of **Agent Shopping Protocol v0.1**. Returns reviews for a given skill or model so agents can factor peer feedback into routing decisions.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "security": [],
        "parameters": [
          {
            "name": "skill",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "example": "claude-4-5-sonnet"
          }
        ],
        "responses": {
          "200": {
            "description": "Reviews",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reviews": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Review" }
                    },
                    "average_rating": { "type": "number" },
                    "count": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Social Proof"],
        "operationId": "createReview",
        "summary": "Submit a skill review",
        "description": "Part of **Agent Shopping Protocol v0.1**. Submits a review (1-5 star rating + optional text) for a skill or model. Agents can programmatically report performance back to the network.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReviewCreateRequest" },
              "example": {
                "skill": "claude-4-5-sonnet",
                "rating": 5,
                "text": "Flawless on complex reasoning tasks."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Review created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Review" }
              }
            }
          }
        }
      }
    },
    "/api/referrals": {
      "get": {
        "tags": ["Social Proof"],
        "operationId": "getReferrals",
        "summary": "Get referral status",
        "description": "Part of **Agent Shopping Protocol v0.1**. Returns the authenticated wallet's referral code, referral stats (invited, converted), and earned credits.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "responses": {
          "200": {
            "description": "Referral status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ReferralStatus" },
                "example": {
                  "referral_code": "AGENT-7XJK",
                  "invited": 12,
                  "converted": 4,
                  "credits_earned_usd": 20.00,
                  "share_url": "https://skillboss.co/r/AGENT-7XJK"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Social Proof"],
        "operationId": "redeemReferral",
        "summary": "Redeem a referral code",
        "description": "Part of **Agent Shopping Protocol v0.1**. Redeems a referral code on the authenticated wallet, crediting both parties per the referral program terms.",
        "servers": [{ "url": "https://www.skillboss.co" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["referral_code"],
                "properties": {
                  "referral_code": { "type": "string", "example": "AGENT-7XJK" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Referral redeemed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "redeemed": { "type": "boolean" },
                    "credits_usd": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from https://skillboss.co/console. Include in header as: `Authorization: Bearer YOUR_API_KEY`"
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model ID to use for completion",
            "example": "claude-4-5-sonnet",
            "enum": [
              "claude-4-5-sonnet",
              "claude-3-7-sonnet",
              "claude-3-5-haiku",
              "gpt-5",
              "gpt-4-turbo",
              "gpt-4o",
              "gpt-4o-mini",
              "gemini-2.5-flash",
              "gemini-2.0-pro",
              "deepseek/deepseek-v3",
              "qwen/qwen-max"
            ]
          },
          "messages": {
            "type": "array",
            "description": "List of messages in the conversation",
            "items": {
              "$ref": "#/components/schemas/Message"
            },
            "minItems": 1
          },
          "max_tokens": {
            "type": "integer",
            "description": "Maximum tokens to generate",
            "default": 1000,
            "minimum": 1,
            "maximum": 128000
          },
          "temperature": {
            "type": "number",
            "description": "Sampling temperature (0-2)",
            "default": 1.0,
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number",
            "description": "Nucleus sampling parameter",
            "default": 1.0,
            "minimum": 0,
            "maximum": 1
          },
          "stream": {
            "type": "boolean",
            "description": "Enable streaming responses",
            "default": false
          },
          "stop": {
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" }, "maxItems": 4 }
            ],
            "description": "Stop sequences"
          }
        }
      },
      "Message": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {
            "type": "string",
            "enum": ["system", "user", "assistant"],
            "description": "Role of the message sender"
          },
          "content": {
            "type": "string",
            "description": "Message content"
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique completion ID",
            "example": "chatcmpl-abc123"
          },
          "object": {
            "type": "string",
            "const": "chat.completion"
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp of creation"
          },
          "model": {
            "type": "string",
            "description": "Model used for completion"
          },
          "choices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Choice"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "Choice": {
        "type": "object",
        "properties": {
          "index": { "type": "integer" },
          "message": { "$ref": "#/components/schemas/Message" },
          "finish_reason": {
            "type": "string",
            "enum": ["stop", "length", "content_filter"]
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": { "type": "integer" },
          "completion_tokens": { "type": "integer" },
          "total_tokens": { "type": "integer" }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "const": "list" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Model" }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string", "const": "model" },
          "created": { "type": "integer" },
          "owned_by": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": { "type": "string" },
              "type": { "type": "string" },
              "code": { "type": "string" }
            }
          }
        }
      },
      "AgentBootstrap": {
        "type": "object",
        "description": "One-shot onboarding manifest for Agent Shopping Protocol v0.1",
        "properties": {
          "service": { "type": "string", "example": "SkillBoss" },
          "version": { "type": "string", "example": "1.3.0" },
          "protocol": { "type": "string", "example": "agent-shopping-protocol/0.1" },
          "endpoints": {
            "type": "object",
            "properties": {
              "catalog": { "type": "string", "format": "uri" },
              "status": { "type": "string", "format": "uri" },
              "anonymous_wallet": { "type": "string", "format": "uri" },
              "estimate": { "type": "string", "format": "uri" },
              "idempotent_run": { "type": "string", "format": "uri" },
              "receipts_jwks": { "type": "string", "format": "uri" },
              "receipts_verify": { "type": "string", "format": "uri" },
              "inference_base_url": { "type": "string", "format": "uri" }
            }
          },
          "auth": {
            "type": "object",
            "properties": {
              "scheme": { "type": "string", "example": "Bearer" },
              "console": { "type": "string", "format": "uri" }
            }
          },
          "free_tier_credits": { "type": "number", "example": 20 }
        }
      },
      "StatusResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["ok", "degraded", "down"] },
          "version": { "type": "string" },
          "subsystems": {
            "type": "object",
            "properties": {
              "inference": { "type": "string", "enum": ["ok", "degraded", "down"] },
              "wallet": { "type": "string", "enum": ["ok", "degraded", "down"] },
              "receipts": { "type": "string", "enum": ["ok", "degraded", "down"] },
              "catalog": { "type": "string", "enum": ["ok", "degraded", "down"] }
            }
          },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "version": { "type": "string" },
          "generated_at": { "type": "string", "format": "date-time" },
          "models": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "vendor": { "type": "string" },
                "category": { "type": "string" },
                "pricing": {
                  "type": "object",
                  "properties": {
                    "input_per_1m": { "type": "number" },
                    "output_per_1m": { "type": "number" },
                    "per_request": { "type": "number" }
                  }
                },
                "context_window": { "type": "integer" },
                "capabilities": { "type": "array", "items": { "type": "string" } }
              }
            }
          }
        }
      },
      "AnonymousWalletRequest": {
        "type": "object",
        "properties": {
          "agent_id": {
            "type": "string",
            "description": "Optional agent identifier for analytics",
            "example": "claude-code/1.0"
          },
          "purpose": {
            "type": "string",
            "description": "Optional free-form purpose tag",
            "example": "smoke-test"
          }
        }
      },
      "AnonymousWalletResponse": {
        "type": "object",
        "properties": {
          "wallet_id": { "type": "string" },
          "api_key": {
            "type": "string",
            "description": "Bearer token for subsequent inference calls"
          },
          "balance_usd": { "type": "number" },
          "expires_at": { "type": "string", "format": "date-time" },
          "upgrade_url": {
            "type": "string",
            "format": "uri",
            "description": "Claim URL to convert this anonymous wallet into a full account"
          }
        }
      },
      "EstimateRequest": {
        "type": "object",
        "required": ["model"],
        "properties": {
          "model": { "type": "string", "example": "claude-4-5-sonnet" },
          "messages": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Message" }
          },
          "max_tokens": { "type": "integer", "example": 1000 },
          "inputs": {
            "type": "object",
            "description": "Alternative payload shape for non-chat models",
            "additionalProperties": true
          }
        }
      },
      "EstimateResponse": {
        "type": "object",
        "properties": {
          "model": { "type": "string" },
          "estimated_input_tokens": { "type": "integer" },
          "estimated_output_tokens": { "type": "integer" },
          "estimated_cost_usd": { "type": "number" },
          "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
          "currency": { "type": "string", "example": "USD" }
        }
      },
      "IdempotentRunRequest": {
        "type": "object",
        "required": ["model"],
        "properties": {
          "model": { "type": "string" },
          "inputs": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "IdempotentRunResponse": {
        "type": "object",
        "properties": {
          "request_id": { "type": "string" },
          "idempotency_key": { "type": "string" },
          "replayed": { "type": "boolean" },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "cost_usd": { "type": "number" },
          "receipt": {
            "type": "string",
            "description": "Signed JWT receipt for this request"
          }
        }
      },
      "ReceiptVerifyRequest": {
        "type": "object",
        "required": ["receipt"],
        "properties": {
          "receipt": {
            "type": "string",
            "description": "Signed JWT receipt issued by SkillBoss"
          }
        }
      },
      "ReceiptVerifyResponse": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "claims": {
            "type": "object",
            "properties": {
              "iss": { "type": "string" },
              "sub": { "type": "string" },
              "request_id": { "type": "string" },
              "model": { "type": "string" },
              "cost_usd": { "type": "number" },
              "iat": { "type": "integer" }
            },
            "additionalProperties": true
          },
          "error": { "type": "string" }
        }
      },
      "Jwks": {
        "type": "object",
        "description": "RFC 7517 JSON Web Key Set",
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "kty": { "type": "string" },
                "crv": { "type": "string" },
                "kid": { "type": "string" },
                "use": { "type": "string" },
                "alg": { "type": "string" },
                "x": { "type": "string" },
                "y": { "type": "string" }
              }
            }
          }
        }
      },
      "WalletRules": {
        "type": "object",
        "properties": {
          "daily_cap_usd": { "type": "number", "example": 25.00 },
          "per_request_cap_usd": { "type": "number", "example": 1.00 },
          "allowed_models": {
            "type": "array",
            "items": { "type": "string" }
          },
          "blocked_vendors": {
            "type": "array",
            "items": { "type": "string" }
          },
          "alert_threshold_usd": { "type": "number", "example": 20.00 }
        }
      },
      "SubWallet": {
        "type": "object",
        "properties": {
          "sub_wallet_id": { "type": "string", "example": "sw_abc123" },
          "label": { "type": "string" },
          "api_key": { "type": "string", "description": "Returned only on creation" },
          "balance_usd": { "type": "number" },
          "rules": { "$ref": "#/components/schemas/WalletRules" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "SubWalletCreateRequest": {
        "type": "object",
        "required": ["label", "budget_usd"],
        "properties": {
          "label": { "type": "string", "example": "research-agent" },
          "budget_usd": { "type": "number", "example": 5.00 },
          "rules": { "$ref": "#/components/schemas/WalletRules" }
        }
      },
      "Review": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "skill": { "type": "string" },
          "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
          "text": { "type": "string" },
          "author": { "type": "string", "description": "Agent identifier or wallet id" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "ReviewCreateRequest": {
        "type": "object",
        "required": ["skill", "rating"],
        "properties": {
          "skill": { "type": "string" },
          "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
          "text": { "type": "string" }
        }
      },
      "ReferralStatus": {
        "type": "object",
        "properties": {
          "referral_code": { "type": "string" },
          "invited": { "type": "integer" },
          "converted": { "type": "integer" },
          "credits_earned_usd": { "type": "number" },
          "share_url": { "type": "string", "format": "uri" }
        }
      }
    }
  },
  "x-agent-metadata": {
    "service_name": "SkillBoss",
    "total_models": 50,
    "total_services": 100,
    "compatibility": "openai",
    "supports_streaming": true,
    "supports_function_calling": true,
    "pricing_model": "pay_as_you_go",
    "free_tier_credits": 20,
    "one_line_install": "curl -fsSL https://skillboss.co/install.sh | bash",
    "capabilities": [
      "chat_completions",
      "image_generation",
      "video_generation",
      "text_to_speech",
      "speech_to_text",
      "payments",
      "email",
      "sms",
      "storage",
      "databases",
      "web_scraping"
    ],
    "supported_platforms": [
      "Claude Code",
      "Cursor",
      "Windsurf",
      "GitHub Copilot",
      "Kiro",
      "Gemini CLI",
      "Codex"
    ],
    "discovery_files": {
      "llms_txt": "/llms.txt",
      "llms_full": "/llms-full.txt",
      "agent_json": "/agent.json",
      "mcp_json": "/.well-known/mcp.json",
      "ai_plugin": "/.well-known/ai-plugin.json"
    }
  }
}