{
  "openapi": "3.1.0",
  "info": {
    "title": "Ralio API",
    "version": "1.0.0",
    "description": "AI-powered payment orchestration platform. This spec is the public programmatic surface of the API: authentication (registration, login, token refresh, and current-user profile), chat, transactions, and audit logs. Management operations (agents, conversations, spend limits, tool permissions, beneficiaries, and banking-integration credentials) require the human-only `agents:config` scope, are managed through the console, and are not part of this surface. The recommended client is the `ralio` Python SDK, which handles authentication and token refresh for you."
  },
  "servers": [
    {
      "url": "https://api.ralio.co",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Ralio JWT for the human path (the ralio SDK and the browser console)."
      },
      "dpop": {
        "type": "http",
        "scheme": "DPoP",
        "description": "DPoP-bound OAuth 2.1 access token for the machine path. Mint via /oauth/token with grant_type=client_credentials, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer, and a private_key_jwt assertion signed by the keypair registered via `ralio auth agent`. Resource requests must include a fresh `DPoP: <proof>` header per RFC 9449 in addition to `Authorization: DPoP <token>`."
      }
    },
    "schemas": {
      "Message": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "role": { "type": "string", "enum": ["user", "assistant", "tool", "system"] },
          "content": { "type": "string" },
          "status": { "type": "string", "enum": ["accepted", "sending", "streaming", "error"] },
          "metadata": { "type": "object", "additionalProperties": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "detail": { "type": "string", "example": "Agent not found" }
        },
        "required": ["detail"]
      }
    }
  },
  "security": [{ "bearerAuth": [] }, { "dpop": [] }],
  "paths": {
    "/api/auth/register": {
      "post": {
        "operationId": "register",
        "summary": "Register a new user account",
        "tags": ["auth"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string", "format": "email", "example": "alice@example.com" },
                  "password": { "type": "string", "example": "SecurePass123!" },
                  "first_name": { "type": "string", "example": "Alice" },
                  "surname": { "type": "string", "example": "Smith" },
                  "company": { "type": "string", "example": "Example Company" }
                },
                "required": ["email", "password", "first_name", "surname", "company"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Registration successful: confirmation email sent.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string" } } } } }
          },
          "409": { "description": "Email already registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/chat": {
      "post": {
        "operationId": "chat",
        "summary": "Queue a message for an agent",
        "tags": ["chat"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": { "type": "string", "example": "What is my balance?" },
                  "agent_id": { "type": "string", "format": "uuid" },
                  "conversation_id": { "type": "string", "example": "conv-my-session-001" }
                },
                "required": ["message", "agent_id"]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Chat request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["accepted"] },
                    "request_id": { "type": "string", "format": "uuid" },
                    "conversation_id": { "type": "string" }
                  },
                  "required": ["status", "request_id", "conversation_id"]
                }
              }
            }
          }
        }
      }
    },
    "/api/chat/stream": {
      "post": {
        "operationId": "chatStream",
        "summary": "Chat with an agent (streaming SSE)",
        "tags": ["chat"],
        "description": "Same as POST /api/chat but streams the response as Server-Sent Events. Uses standard SSE event names: tool_started, tool_completed, tool_failed, reply (token-by-token), done, error. Each event's data field is a JSON object.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": { "type": "string" },
                  "agent_id": { "type": "string" },
                  "conversation_id": { "type": "string" }
                },
                "required": ["message", "agent_id"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server-Sent Event stream.",
            "content": {
              "text/event-stream": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/api/transactions": {
      "get": {
        "operationId": "listTransactions",
        "summary": "List payment transactions",
        "tags": ["transactions"],
        "parameters": [
          { "name": "agent_id", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": { "200": { "description": "Transactions.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }
      }
    },
    "/api/payment-intents": {
      "get": {
        "operationId": "listPaymentIntents",
        "summary": "List payment intents",
        "tags": ["transactions"],
        "parameters": [
          { "name": "agent_id", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": {
          "200": {
            "description": "Payment intents.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "agent_id": { "type": "string" },
                      "amount": { "type": "number" },
                      "currency": { "type": "string" },
                      "creditor_account": { "type": "string" },
                      "debtor_account": { "type": "string" },
                      "status": { "type": "string", "enum": ["pending", "executed", "failed", "denied"] },
                      "created_at": { "type": "string", "format": "date-time" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/audit-logs": {
      "get": {
        "operationId": "listAuditLogs",
        "summary": "List audit log entries",
        "tags": ["audit"],
        "parameters": [
          { "name": "action", "in": "query", "schema": { "type": "string" } },
          { "name": "agent_id", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": { "200": { "description": "Audit log entries.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }
      }
    }
  },
  "tags": [
    { "name": "auth", "description": "Authentication: register, login, token refresh, and current-user profile (the ralio SDK wraps login/refresh for you)" },
    { "name": "chat", "description": "Chat with agents: synchronous and streaming" },
    { "name": "transactions", "description": "Payment transaction history" },
    { "name": "audit", "description": "Audit log queries" }
  ]
}