{
  "openapi": "3.1.0",
  "info": {
    "title": "Argus API",
    "version": "1.0.0",
    "description": "Agentic Spending Control Plane — allow AI agents to request payments, check balances, and query policies programmatically.",
    "contact": {
      "name": "Argus Support",
      "url": "https://argus.finance"
    }
  },
  "servers": [
    {
      "url": "https://jgwvrwaocmsbrxwszisk.supabase.co/functions/v1/api-v1",
      "description": "Production"
    }
  ],
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/v1/transactions": {
      "post": {
        "operationId": "createTransaction",
        "summary": "Request a payment",
        "description": "Submit a transaction request for policy evaluation. The engine will auto-approve, queue for review, or reject based on the agent's assigned policy.",
        "tags": ["Transactions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateTransactionRequest" },
              "example": {
                "agent_id": "agent_2024_abc123",
                "amount": 4999,
                "currency": "USD",
                "merchant": {
                  "name": "OpenAI",
                  "domain": "openai.com",
                  "category": "apis"
                },
                "justification": "GPT-4 API credits for support chatbot",
                "idempotency_key": "txn_unique_12345"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transaction created and evaluated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Transaction" }
              }
            }
          },
          "400": { "description": "Invalid request body" },
          "401": { "description": "Invalid or missing API key" },
          "429": { "description": "Rate limit exceeded" }
        }
      },
      "get": {
        "operationId": "listTransactions",
        "summary": "List transactions",
        "description": "Retrieve a list of transactions for the authenticated organization, ordered by most recent.",
        "tags": ["Transactions"],
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending_policy_check", "approved", "queued_for_approval", "rejected", "executing", "completed", "failed", "cancelled"] } },
          { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "List of transactions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transactions": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Transaction" }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/v1/transactions/{id}": {
      "get": {
        "operationId": "getTransaction",
        "summary": "Get transaction details",
        "tags": ["Transactions"],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": {
            "description": "Transaction details with audit trail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Transaction" }
              }
            }
          },
          "404": { "description": "Transaction not found" }
        }
      }
    },
    "/v1/balance": {
      "get": {
        "operationId": "getBalance",
        "summary": "Get wallet balance",
        "description": "Returns the current wallet balance and spending summary for the agent associated with the API key.",
        "tags": ["Wallet"],
        "responses": {
          "200": {
            "description": "Balance details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Balance" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/v1/agents/me": {
      "get": {
        "operationId": "getAgentProfile",
        "summary": "Get agent profile",
        "description": "Returns the profile of the agent associated with the current API key.",
        "tags": ["Agents"],
        "responses": {
          "200": {
            "description": "Agent profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentProfile" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/v1/policy": {
      "get": {
        "operationId": "getActivePolicy",
        "summary": "Get active policy",
        "description": "Returns the spending policy currently assigned to the agent, including limits, merchant rules, and approval thresholds.",
        "tags": ["Policies"],
        "responses": {
          "200": {
            "description": "Active policy definition",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PolicyDefinition" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Pass your Argus API key as a Bearer token: `Authorization: Bearer sk_live_...`"
      }
    },
    "schemas": {
      "CreateTransactionRequest": {
        "type": "object",
        "required": ["agent_id", "amount", "merchant"],
        "properties": {
          "agent_id": { "type": "string", "format": "uuid" },
          "amount": { "type": "integer", "description": "Amount in USD cents" },
          "currency": { "type": "string", "default": "USD" },
          "merchant": {
            "type": "object",
            "required": ["name"],
            "properties": {
              "name": { "type": "string" },
              "domain": { "type": "string" },
              "category": { "type": "string", "enum": ["saas", "cloud_compute", "data_providers", "apis", "marketplaces", "other"] }
            }
          },
          "justification": { "type": "string" },
          "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "idempotency_key": { "type": "string" }
        }
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "enum": ["pending_policy_check", "approved", "queued_for_approval", "rejected", "executing", "completed", "failed", "cancelled"] },
          "amount": { "type": "integer" },
          "currency": { "type": "string" },
          "merchant": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "domain": { "type": "string" },
              "category": { "type": "string" }
            }
          },
          "agent_id": { "type": "string", "format": "uuid" },
          "agent_name": { "type": "string" },
          "policy_evaluation": {
            "type": "object",
            "properties": {
              "final_decision": { "type": "string", "enum": ["approved", "queued", "rejected"] },
              "decision_reason": { "type": "string" },
              "rules_checked": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "rule_name": { "type": "string" },
                    "passed": { "type": "boolean" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Balance": {
        "type": "object",
        "properties": {
          "wallet_balance": { "type": "integer", "description": "Available balance in cents" },
          "spend_today": { "type": "integer" },
          "spend_7d": { "type": "integer" },
          "spend_30d": { "type": "integer" },
          "daily_limit": { "type": "integer" },
          "currency": { "type": "string" }
        }
      },
      "AgentProfile": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "type": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "paused", "quarantined", "archived"] },
          "policy_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "PolicyDefinition": {
        "type": "object",
        "properties": {
          "limits": {
            "type": "object",
            "properties": {
              "per_transaction": { "$ref": "#/components/schemas/PolicyLimit" },
              "per_day": { "$ref": "#/components/schemas/PolicyLimit" },
              "per_week": { "$ref": "#/components/schemas/PolicyLimit" },
              "per_month": { "$ref": "#/components/schemas/PolicyLimit" }
            }
          },
          "merchants": {
            "type": "object",
            "properties": {
              "mode": { "type": "string", "enum": ["whitelist", "blacklist", "all_allowed"] },
              "domains": { "type": "array", "items": { "type": "string" } },
              "categories": { "type": "array", "items": { "type": "string" } }
            }
          },
          "approvals": {
            "type": "object",
            "properties": {
              "auto_approve_under": { "type": "integer" },
              "block_over": { "type": "integer" },
              "require_approval_between": {
                "type": "object",
                "properties": {
                  "min": { "type": "integer" },
                  "max": { "type": "integer" }
                }
              },
              "approval_timeout_hours": { "type": "integer" }
            }
          }
        }
      },
      "PolicyLimit": {
        "type": "object",
        "properties": {
          "enabled": { "type": "boolean" },
          "amount": { "type": "integer", "description": "Amount in USD cents" },
          "currency": { "type": "string" }
        }
      }
    }
  }
}