{
  "openapi": "3.1.0",
  "info": {
    "title": "ATO Joe agent gateway",
    "version": "1.1.0",
    "description": "User-scoped tools for Grok, ChatGPT, Claude, Gemini, and Cursor. Authenticate with a Profile agent token (ajo_…). Includes structured agentic-commerce receipt ingest. Not affiliated with the ATO. Guides only — confirm with a registered tax agent."
  },
  "servers": [
    {
      "url": "https://gbdjautngigdcvfiwwdn.supabase.co/functions/v1",
      "description": "ATO Joe edge functions"
    }
  ],
  "paths": {
    "/agent-gateway": {
      "post": {
        "operationId": "agentGateway",
        "summary": "Call an ATO Joe agent tool",
        "security": [{ "agentToken": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tool"],
                "properties": {
                  "tool": {
                    "type": "string",
                    "enum": [
                      "whoami",
                      "list_receipts",
                      "tax_summary",
                      "scan_receipt",
                      "confirm_receipt",
                      "ingest_commerce_receipt",
                      "resolve_receipt_clarification",
                      "add_driving_log",
                      "generate_report"
                    ]
                  },
                  "arguments": {
                    "oneOf": [
                      { "$ref": "#/components/schemas/IngestCommerceReceiptArgs" },
                      { "$ref": "#/components/schemas/ResolveClarificationArgs" },
                      { "type": "object" }
                    ]
                  }
                }
              },
              "examples": {
                "ingestCommerce": {
                  "summary": "Ingest a Stripe agentic commerce order",
                  "value": {
                    "tool": "ingest_commerce_receipt",
                    "arguments": {
                      "merchant_name": "Officeworks",
                      "amount": 89.95,
                      "tax_amount": 8.18,
                      "purchase_date": "2026-11-03",
                      "currency": "AUD",
                      "description": "Printer paper and toner",
                      "entity_hint": "business",
                      "agent_source": "chatgpt",
                      "stripe_payment_intent_id": "pi_example",
                      "auto_confirm": false
                    }
                  }
                },
                "whoami": {
                  "summary": "Identity, businesses, funding pools",
                  "value": { "tool": "whoami", "arguments": {} }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/IngestCommerceReceiptResponse" },
                    { "type": "object" }
                  ]
                }
              }
            }
          },
          "401": { "description": "Invalid or revoked token" },
          "402": { "description": "Pro required for write tools; body includes upgrade_url" },
          "429": { "description": "Burst rate limit (60 calls/hour)" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ajo_",
        "description": "Token from ATO Joe Profile → Agent access. Shown once. Treat like a password."
      }
    },
    "schemas": {
      "IngestCommerceReceiptArgs": {
        "type": "object",
        "description": "Structured order / receipt from an AI agent after a purchase (Stripe agentic commerce or custom).",
        "properties": {
          "merchant_name": { "type": "string" },
          "merchant_abn": { "type": "string" },
          "description": { "type": "string" },
          "line_items": {
            "type": "array",
            "items": { "type": "object" }
          },
          "amount": { "type": "number" },
          "tax_amount": { "type": "number" },
          "currency": { "type": "string", "default": "AUD" },
          "gst_inclusive": { "type": "boolean", "default": true },
          "purchase_date": { "type": "string", "format": "date" },
          "receipt_url": { "type": "string", "format": "uri" },
          "receipt_base64": { "type": "string" },
          "stripe_payment_intent_id": { "type": "string" },
          "stripe_checkout_session_id": { "type": "string" },
          "stripe_order_id": { "type": "string" },
          "shared_payment_token_id": { "type": "string" },
          "spend_request_id": { "type": "string" },
          "agent_source": {
            "type": "string",
            "enum": ["grok-bot", "chatgpt", "gemini", "cursor", "claude", "custom"]
          },
          "entity_hint": { "type": "string", "enum": ["personal", "business"] },
          "business_id": { "type": "string", "format": "uuid" },
          "pool_id": { "type": "string", "format": "uuid" },
          "auto_confirm": { "type": "boolean", "default": false },
          "private_use_percent": { "type": "number" },
          "category_name": { "type": "string" }
        }
      },
      "ResolveClarificationArgs": {
        "type": "object",
        "required": ["receipt_id"],
        "properties": {
          "receipt_id": { "type": "string", "format": "uuid" },
          "auto_confirm": { "type": "boolean", "default": true },
          "answers": {
            "type": "object",
            "properties": {
              "purchase_type": { "type": "string", "enum": ["personal", "business"] },
              "business_id": { "type": "string" },
              "financial_year": { "type": "string" },
              "private_use_percent": { "type": "number" },
              "category_name": { "type": "string" }
            }
          }
        }
      },
      "IngestCommerceReceiptResponse": {
        "type": "object",
        "properties": {
          "receipt_id": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["pending_review", "confirmed", "needs_confirmation"]
          },
          "suggested_category": { "type": "string" },
          "category_rationale": { "type": "string" },
          "linked_entity": {
            "type": "object",
            "nullable": true,
            "properties": {
              "purchase_type": { "type": "string" },
              "business_id": { "type": "string", "nullable": true },
              "business_name": { "type": "string", "nullable": true }
            }
          },
          "cloud_file_url": { "type": "string", "nullable": true },
          "cloud_folder_hint": { "type": "string" },
          "tax_savings_note": { "type": "string", "nullable": true },
          "clarifying_questions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "prompt": { "type": "string" },
                "type": { "type": "string" },
                "options": { "type": "array", "items": { "type": "string" } }
              }
            }
          },
          "confirmation_message": { "type": "string" },
          "idempotent": { "type": "boolean" },
          "disclaimer": { "type": "string" }
        }
      }
    }
  }
}
