{
  "openapi": "3.1.0",
  "info": {
    "title": "Turing Dock Agent API",
    "description": "API for AI agents to check their dock balance, make payments, and view transactions. Authenticate with your dock API key (td_live_...).",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.turingdock.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/agent/balance": {
      "get": {
        "operationId": "getBalance",
        "summary": "Get dock balance",
        "description": "Returns the current balance for your dock, including total budget, amount spent, remaining funds, and daily spend tracking.",
        "responses": {
          "200": {
            "description": "Dock balance",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Balance" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/agent/pay": {
      "post": {
        "operationId": "makePayment",
        "summary": "Make a payment",
        "description": "Transfer funds from your dock to another dock. The payment is validated against your dock's spend rules (per-transaction limits, daily caps, category rules, approval thresholds).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to", "amount"],
                "properties": {
                  "to": {
                    "type": "string",
                    "description": "Recipient dock name or ID"
                  },
                  "amount": {
                    "type": "integer",
                    "description": "Amount to pay in cents (e.g. 1500 = $15.00)"
                  },
                  "category": {
                    "type": "string",
                    "description": "Optional merchant category for rules evaluation"
                  },
                  "memo": {
                    "type": "string",
                    "description": "Optional note describing the payment"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment completed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaymentResult" }
              }
            }
          },
          "202": {
            "description": "Payment requires approval (amount exceeds approval threshold)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaymentResult" }
              }
            }
          },
          "400": { "description": "Invalid request (missing fields, insufficient balance, or blocked by spend rules)" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/agent/transactions": {
      "get": {
        "operationId": "listTransactions",
        "summary": "List transactions",
        "description": "Returns recent transactions for your dock, ordered by most recent first.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of transactions to return (1-100, default 50)",
            "schema": { "type": "integer", "default": 50, "maximum": 100 }
          }
        ],
        "responses": {
          "200": {
            "description": "Transaction list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Transaction" }
                }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/agent/card": {
      "get": {
        "operationId": "getCard",
        "summary": "Get virtual card details",
        "description": "Returns the full virtual card details (card number, expiry, CVV) for your dock. Use these details to make purchases on external services.",
        "responses": {
          "200": {
            "description": "Card details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CardDetails" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" },
          "404": { "description": "No virtual card issued for this dock" }
        }
      }
    },
    "/agent/dock": {
      "get": {
        "operationId": "getDockInfo",
        "summary": "Get dock info",
        "description": "Returns full details about your dock including status, balance, card info, and spend rules.",
        "responses": {
          "200": {
            "description": "Dock details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DockInfo" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your dock API key (starts with td_live_)"
      }
    },
    "schemas": {
      "Balance": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "description": "Total budget in cents" },
          "spent": { "type": "integer", "description": "Total spent in cents" },
          "remaining": { "type": "integer", "description": "Remaining budget in cents" },
          "dailySpent": { "type": "integer", "description": "Amount spent today in cents" },
          "dailyRemaining": { "type": ["integer", "null"], "description": "Remaining daily allowance in cents, or null if no daily limit" },
          "currency": { "type": "string", "example": "usd" }
        }
      },
      "PaymentResult": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Transaction ID" },
          "status": { "type": "string", "enum": ["completed", "pending_approval"], "description": "Payment outcome" },
          "amount": { "type": "integer", "description": "Amount paid in cents" },
          "remaining": { "type": "integer", "description": "Remaining dock balance in cents after payment" },
          "timestamp": { "type": "string", "format": "date-time" },
          "reason": { "type": "string", "description": "Reason if payment requires approval" }
        }
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "enum": ["DOCK_TO_DOCK", "CARD_PURCHASE"] },
          "amountCents": { "type": "integer" },
          "status": { "type": "string", "enum": ["COMPLETED", "PENDING", "REJECTED", "FAILED"] },
          "recipient": { "type": "string" },
          "memo": { "type": ["string", "null"] },
          "category": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "CardDetails": {
        "type": "object",
        "properties": {
          "pan": { "type": "string", "description": "Full card number" },
          "expMonth": { "type": "string", "description": "Expiration month (MM)" },
          "expYear": { "type": "string", "description": "Expiration year (YYYY)" },
          "cvv": { "type": "string", "description": "Card security code" },
          "cardStatus": { "type": "string", "description": "Card status (OPEN, PAUSED, etc.)" },
          "cardLastFour": { "type": "string", "description": "Last four digits of card number" }
        }
      },
      "DockInfo": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "status": { "type": "string", "enum": ["ACTIVE", "PAUSED", "FROZEN", "DEPLETED"] },
          "balance": { "$ref": "#/components/schemas/Balance" },
          "card": {
            "type": ["object", "null"],
            "properties": {
              "lastFour": { "type": "string" },
              "status": { "type": "string" }
            }
          },
          "rules": {
            "type": "object",
            "properties": {
              "maxPerTransaction": { "type": ["integer", "null"], "description": "Max per transaction in cents" },
              "dailyLimit": { "type": ["integer", "null"], "description": "Daily spend limit in cents" },
              "allowedCategories": { "type": "array", "items": { "type": "string" } },
              "requireApprovalAbove": { "type": ["integer", "null"], "description": "Approval threshold in cents" }
            }
          }
        }
      }
    }
  },
  "security": [{ "apiKey": [] }]
}