{
  "openapi": "3.0.3",
  "info": {
    "title": "IncomeOS — Universal Commerce Protocol (UCP)",
    "version": "1.1.0",
    "description": "Trust-aware commerce API for AI agents acting on behalf of human owners on IncomeOS — a personal income operating system (NOT a freelance marketplace).\n\nCore guarantees agents must respect:\n1. Human-first — every monetary action defaults to a spend cap of 0 and can be paused for human approval.\n2. Trust-network discovery — counterparties are ranked by real human trust graph (Trustees, N-hop proximity), not anonymous reviews.\n3. No synthetic actors — agents cannot post reviews, send appreciations, or build trust on the human's behalf.\n4. Transparent fee — a flat 2.5% platform fee is the only cut. No hidden spread.\n5. Proprietary AI — Inco AI is in-house; no third-party LLMs process user data.\n6. Earn-without-owning — opportunities span skills, assets, referrals, and partnerships.\n\nAuth: All transactional endpoints require the X-UCP-Agent-Id header. Public read mirrors (/public-opportunities-api/*) require no auth.\n\nFull machine-readable principles: https://www.incomeos.app/.well-known/incomeos-principles.json",
    "contact": { "name": "IncomeOS", "email": "agents@incomeos.app", "url": "https://www.incomeos.app/for-ai-agents" },
    "license": { "name": "Terms of Service", "url": "https://www.incomeos.app/terms" }
  },
  "servers": [
    { "url": "https://unahmrztxqefwmxznbci.supabase.co/functions/v1", "description": "Production" }
  ],
  "components": {
    "securitySchemes": {
      "AgentKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-UCP-Agent-Id",
        "description": "Personal or business agent key prefix. Get one at https://www.incomeos.app/agent-authorize or https://www.incomeos.app/dashboard/settings (AI Agents tab)."
      }
    },
    "schemas": {
      "Opportunity": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "category": { "type": "string", "enum": ["task", "skill", "asset", "partnership", "ask"] },
          "currency": { "type": "string" },
          "amount_cents": { "type": "integer" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      }
    }
  },
  "paths": {
    "/public-opportunities-api/opportunities": {
      "get": {
        "summary": "List active public opportunities (JSON-LD ItemList)",
        "description": "No auth required. Returns Schema.org ItemList of JobPosting items.",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["task", "skill", "asset", "partnership", "ask"] } },
          { "name": "country", "in": "query", "schema": { "type": "string", "description": "ISO-3166 alpha-2 country code" } },
          { "name": "min_budget", "in": "query", "schema": { "type": "integer", "description": "Minimum budget in cents" } }
        ],
        "responses": { "200": { "description": "JSON-LD ItemList" } }
      }
    },
    "/public-opportunities-api/opportunities/{id}.json": {
      "get": {
        "summary": "Single opportunity (JSON-LD JobPosting)",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "JSON-LD JobPosting" }, "404": { "description": "Not found" } }
      }
    },
    "/public-opportunities-api/opportunities/{id}.md": {
      "get": {
        "summary": "Single opportunity (Markdown mirror)",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "text/markdown" } }
      }
    },
    "/ucp-catalog": {
      "get": {
        "summary": "Discover opportunities (auth)",
        "description": "Trust-tier and N-hop network filtering for authenticated agents.",
        "security": [{ "AgentKey": [] }],
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "min_trust_tier", "in": "query", "schema": { "type": "string", "enum": ["seedling", "builder", "trusted", "inner_circle"] } },
          { "name": "within_n_hops", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 3 } }
        ],
        "responses": { "200": { "description": "Array of opportunities" }, "401": { "description": "Invalid agent key" } }
      }
    },
    "/ucp-intent": {
      "post": {
        "summary": "Negotiate, check availability, or create order",
        "security": [{ "AgentKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["action", "item_id", "item_type"],
                "properties": {
                  "action": { "type": "string", "enum": ["price_check", "availability", "create_order"] },
                  "item_id": { "type": "string" },
                  "item_type": { "type": "string", "enum": ["opportunity", "product", "service", "asset"] },
                  "amount_cents": { "type": "integer" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Action result" },
          "402": { "description": "Spend cap exceeded — human approval required" },
          "401": { "description": "Invalid or revoked agent key" }
        }
      }
    },
    "/ucp-status": {
      "get": {
        "summary": "Track an order lifecycle",
        "security": [{ "AgentKey": [] }],
        "parameters": [{ "name": "order_id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Order status" } }
      }
    }
  }
}