{"openapi": "3.1.0", "info": {"title": "Lowtides API", "version": "1.1.0", "summary": "One budget and a STOP button between AI agents and money.", "description": "Agents ask Lowtides before they buy (`POST /v1/spend`) and send model calls through it (OpenAI- and Anthropic-compatible). Approved purchases are paid with PayPal Payouts. Plain-English rules, approvals and a stop switch are on the dashboard API. The public demo at https://lowtides.ai needs no password: get an agent key from `GET /api/state`.", "license": {"name": "AGPL-3.0-only", "identifier": "AGPL-3.0-only"}, "contact": {"name": "Lowtides", "url": "https://github.com/seniorhelper/lowtides"}}, "servers": [{"url": "https://lowtides.ai", "description": "Public demo (PayPal sandbox, simulated models)"}, {"url": "http://127.0.0.1:8787", "description": "Your own copy"}], "tags": [{"name": "Agent: purchases", "description": "Ask before buying. Auth: the agent's Lowtides key."}, {"name": "Agent: AI proxy", "description": "Drop-in OpenAI and Anthropic endpoints with budgets."}, {"name": "Dashboard: agents", "description": "Create agents and read their keys."}, {"name": "Dashboard: approvals", "description": "A person approves or denies held purchases."}, {"name": "Dashboard: stop switch", "description": "Shut off one agent or STOP ALL."}, {"name": "Dashboard: rules", "description": "Rules, merchants, forecast and audit."}, {"name": "Dashboard: webhooks", "description": "Send events to Zapier, Make or any URL."}, {"name": "Dashboard: assistant", "description": "Ask Lowtides: a guide that suggests, and a person confirms."}, {"name": "Consent Shopping", "description": "Store Policies, the Handshake (both sides must say yes), GuardPooch, trust scores and shopper preferences."}], "paths": {"/v1/spend": {"post": {"operationId": "requestSpend", "tags": ["Agent: purchases"], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}], "summary": "Ask before buying", "description": "Call before every purchase. The agent's rules approve it (and Lowtides pays the merchant through PayPal Payouts), deny it, or hold it for a person. Always 200 for a decision: read `decision`.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpendRequest"}, "example": {"amount": 12.5, "merchant": "Acme Data", "item": "1,000 enrichment credits", "category": "data", "reason": "Needed to finish the lead list"}}}}, "responses": {"200": {"description": "The decision.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpendDecision"}, "example": {"id": "sp_3f9a1c0b7d2e4a61", "ts": 1793301188.08, "agent_id": 1, "agent_name": "Research bot", "task_id": null, "amount": 12.5, "merchant": "Acme Data", "item": "1,000 enrichment credits", "category": "data", "reason": "Needed to finish the lead list", "decision": "approved", "status": "paid", "reasons": ["Within the $20.00 auto-approve limit and today's $200.00 budget.", "Acme Data is a known merchant."], "flags": [], "payee": "merchant-demo@example.com", "payout_batch_id": "5UXD2E8A7EBQJ", "payout_item_id": "8AELMXH8UB2P8", "payout_status": "UNCLAIMED", "payout_env": "sandbox", "simulated": false, "decided_by": "rules", "decided_ts": 1793301188.4, "note": "", "payout_proof": "PayPal sandbox payout batch 5UXD2E8A7EBQJ, item 8AELMXH8UB2P8 (UNCLAIMED)"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/spend/{id}": {"get": {"operationId": "getSpend", "tags": ["Agent: purchases"], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}], "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Spend request ID (sp_...)."}], "summary": "Check a purchase", "description": "Poll this while a request is pending. It also refreshes the PayPal payout status.", "responses": {"200": {"description": "Current status.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpendDecision"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/budget": {"get": {"operationId": "getBudget", "tags": ["Agent: purchases"], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}], "summary": "What this agent may still spend today", "responses": {"200": {"description": "Budget and rules.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Budget"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/stores": {"get": {"operationId": "agentListStores", "tags": ["Agent: purchases"], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}], "summary": "Stores, their signed policies for AI shoppers, and their items", "responses": {"200": {"description": "Stores with policy, store check and items.", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/handshake": {"post": {"operationId": "agentHandshake", "tags": ["Agent: purchases"], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}], "summary": "Run a Handshake: the agent's Pass and the store's policy are checked both ways", "description": "Same engine as the site's buttons. `signal` is match, needs_yes or no_match. With `execute: true` a match pays through PayPal Payouts (sandbox; simulated and labeled when the server has no keys) and needs_yes becomes a held request for the owner. Always 200 for an answer: read `signal` and `next`.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["store_id"], "properties": {"store_id": {"type": "string"}, "item_id": {"type": "string"}, "amount": {"type": "number"}, "category": {"type": "string"}, "title": {"type": "string"}, "execute": {"type": "boolean"}}}, "example": {"store_id": "harbor", "item_id": "harbor-tape", "execute": false}}}}, "responses": {"200": {"description": "The Handshake answer.", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/handshake/{id}": {"get": {"operationId": "agentGetHandshake", "tags": ["Agent: purchases"], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}], "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Spend request ID (sp_...)."}], "summary": "Read one of this agent's Handshakes again (a held one may have been approved)", "responses": {"200": {"description": "The Handshake answer.", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/models": {"get": {"operationId": "listModels", "tags": ["Agent: AI proxy"], "summary": "Models this Lowtides knows", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ModelList"}}}}}}}, "/v1/chat/completions": {"post": {"operationId": "createChatCompletion", "tags": ["Agent: AI proxy"], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}], "summary": "OpenAI-compatible chat (budgeted)", "description": "Drop-in for OpenAI: point base_url at Lowtides and use the agent's Lowtides key. Budgets, the loop guard and the leash run before the call reaches a model.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ChatCompletionRequest"}, "example": {"model": "sim-large", "messages": [{"role": "user", "content": "Translate: hello"}]}}}}, "responses": {"200": {"description": "The model's answer, plus Lowtides cost headers.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ChatCompletion"}}, "text/event-stream": {"schema": {"type": "string"}, "description": "Sent when the request sets stream: true."}}, "headers": {"X-Lowtides-Model-Used": {"schema": {"type": "string"}, "description": "The model that actually answered."}, "X-Lowtides-Cost": {"schema": {"type": "string"}, "description": "Dollars this call cost."}, "X-Lowtides-Saved": {"schema": {"type": "string"}, "description": "Dollars saved against the model asked for."}, "X-Lowtides-Budget-Left-Today": {"schema": {"type": "string"}, "description": "Dollars left in today's AI budget."}}}, "402": {"description": "Lowtides refused the call before it reached a model, so it cost nothing. 402: over budget; 403: agent stopped or paused; 429: loop detected or rate limited. `error.code` says which.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BlockedError"}}}}, "403": {"description": "Lowtides refused the call before it reached a model, so it cost nothing. 402: over budget; 403: agent stopped or paused; 429: loop detected or rate limited. `error.code` says which.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BlockedError"}}}}, "429": {"description": "Lowtides refused the call before it reached a model, so it cost nothing. 402: over budget; 403: agent stopped or paused; 429: loop detected or rate limited. `error.code` says which.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BlockedError"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/messages": {"post": {"operationId": "createMessage", "tags": ["Agent: AI proxy"], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}], "summary": "Anthropic-compatible messages (budgeted)", "description": "Drop-in for the Anthropic API: point base_url at Lowtides and use the agent's Lowtides key.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MessageRequest"}, "example": {"model": "sim-large", "max_tokens": 300, "messages": [{"role": "user", "content": "Translate: hello"}]}}}}, "responses": {"200": {"description": "The model's answer, plus Lowtides cost headers.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Message"}}, "text/event-stream": {"schema": {"type": "string"}, "description": "Sent when the request sets stream: true."}}, "headers": {"X-Lowtides-Model-Used": {"schema": {"type": "string"}, "description": "The model that actually answered."}, "X-Lowtides-Cost": {"schema": {"type": "string"}, "description": "Dollars this call cost."}, "X-Lowtides-Saved": {"schema": {"type": "string"}, "description": "Dollars saved against the model asked for."}, "X-Lowtides-Budget-Left-Today": {"schema": {"type": "string"}, "description": "Dollars left in today's AI budget."}}}, "402": {"description": "Lowtides refused the call before it reached a model, so it cost nothing. 402: over budget; 403: agent stopped or paused; 429: loop detected or rate limited. `error.code` says which.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BlockedError"}}}}, "403": {"description": "Lowtides refused the call before it reached a model, so it cost nothing. 402: over budget; 403: agent stopped or paused; 429: loop detected or rate limited. `error.code` says which.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BlockedError"}}}}, "429": {"description": "Lowtides refused the call before it reached a model, so it cost nothing. 402: over budget; 403: agent stopped or paused; 429: loop detected or rate limited. `error.code` says which.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BlockedError"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/health": {"get": {"operationId": "health", "tags": ["Agent: AI proxy"], "summary": "Health check", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "version": {"type": "string"}}}}}}}}}, "/api/state": {"get": {"operationId": "getState", "tags": ["Dashboard: agents"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Dashboard state (agents with their keys, events, totals)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/State"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/agents": {"post": {"operationId": "createAgent", "tags": ["Dashboard: agents"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Create an agent (returns its Lowtides key)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"agent": {"$ref": "#/components/schemas/Agent"}}}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentCreate"}, "example": {"name": "Research bot", "daily_budget": 5}}}}}}, "/api/spend": {"get": {"operationId": "listSpend", "tags": ["Dashboard: approvals"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "List purchase requests", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpendList"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "status", "in": "query", "schema": {"type": "string", "enum": ["pending", "all", "paid", "denied", "approved", "cancelled", "failed"], "default": "all"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 100, "maximum": 1000}}]}}, "/api/spend/{id}/approve": {"post": {"operationId": "approveSpend", "tags": ["Dashboard: approvals"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Approve a held purchase (pays it)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpendDecision"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object"}, "example": {}}}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Spend request ID (sp_...)."}]}}, "/api/spend/{id}/deny": {"post": {"operationId": "denySpend", "tags": ["Dashboard: approvals"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Deny a held purchase", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpendDecision"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "maxLength": 300}}}, "example": {"note": "Not needed"}}}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Spend request ID (sp_...)."}]}}, "/api/spend/{id}/evidence": {"get": {"operationId": "getEvidence", "tags": ["Dashboard: approvals"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Download the dispute evidence pack", "responses": {"200": {"description": "Evidence pack (JSON).", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Spend request ID (sp_...)."}]}}, "/api/agents/{agent_id}/kill": {"post": {"operationId": "killAgent", "tags": ["Dashboard: stop switch"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Shut off one agent", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KillResult"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object"}, "example": {}}}}, "parameters": [{"name": "agent_id", "in": "path", "required": true, "schema": {"type": "integer"}, "description": "Agent ID."}], "description": "Stops the agent, denies its pending purchases, voids its open PayPal holds and cancels its unclaimed payouts."}}, "/api/ask": {"post": {"operationId": "askLowtides", "tags": ["Dashboard: assistant"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Ask Lowtides (the talking guide)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AskAnswer"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["question"], "properties": {"question": {"type": "string", "maxLength": 500}, "page": {"type": "string", "description": "The page the person is on, like /shop/."}}}, "example": {"question": "Why was my purchase held?", "page": "/shop/"}}}}, "description": "Answers from real data. `source` is `claude` or `scripted`, honestly. It can only suggest changes (`actions`); nothing happens until a person confirms one. Claude calls are metered into the ledger as the agent `Ask Lowtides`, under a hard daily dollar cap."}}, "/api/ask/confirm": {"post": {"operationId": "confirmAsk", "tags": ["Dashboard: assistant"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Confirm (or cancel) one suggestion from Ask Lowtides", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "410": {"description": "Gone: the suggestion expired.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "501": {"description": "That part of Lowtides isn't available on this server yet.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["action_id"], "properties": {"action_id": {"type": "string"}, "cancel": {"type": "boolean"}}}, "example": {"action_id": "act_example"}}}}, "description": "Runs the suggestion through the existing rules, once. The id belongs to the visitor it was shown to and expires after a few minutes."}}, "/api/stop-all": {"post": {"operationId": "stopAll", "tags": ["Dashboard: stop switch"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "STOP ALL", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StopAllResult"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object"}, "example": {}}}}, "description": "Stop all, for every agent."}}, "/api/agents/{agent_id}/rules": {"get": {"operationId": "getRules", "tags": ["Dashboard: rules"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Read an agent's rules", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"rules": {"$ref": "#/components/schemas/Rules"}, "plain": {"type": "array", "items": {"type": "string"}}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "agent_id", "in": "path", "required": true, "schema": {"type": "integer"}, "description": "Agent ID."}]}, "post": {"operationId": "saveRules", "tags": ["Dashboard: rules"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Save an agent's rules", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"rules": {"$ref": "#/components/schemas/Rules"}, "plain": {"type": "array", "items": {"type": "string"}}}}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["rules"], "properties": {"rules": {"$ref": "#/components/schemas/Rules"}}}, "example": {"rules": {"max_per_purchase": 60, "daily_purchase_limit": 100, "approval_over": 25}}}}}, "parameters": [{"name": "agent_id", "in": "path", "required": true, "schema": {"type": "integer"}, "description": "Agent ID."}]}}, "/api/rules/compile": {"post": {"operationId": "compileRules", "tags": ["Dashboard: rules"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Turn plain English into rules (does not save)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RulesCompileResult"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string"}}}, "example": {"text": "Max $100 a day. No more than $60 per purchase. Ask me over $25. Never buy gift cards or crypto."}}}}, "description": "Claude translates the text when ANTHROPIC_API_KEY is set; otherwise an offline parser does. A person reviews the result before saving it. The AI never decides a payment."}}, "/api/merchants": {"get": {"operationId": "listMerchants", "tags": ["Dashboard: rules"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "List merchants (payee allowlist)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"merchants": {"type": "array", "items": {"$ref": "#/components/schemas/Merchant"}}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"operationId": "saveMerchant", "tags": ["Dashboard: rules"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Add or update a merchant", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"merchant": {"$ref": "#/components/schemas/Merchant"}}}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}, "paypal_email": {"type": "string", "format": "email"}, "category": {"type": "string"}}}, "example": {"name": "Acme Data", "paypal_email": "merchant-demo@example.com", "category": "data"}}}}}}, "/api/forecast": {"get": {"operationId": "getForecast", "tags": ["Dashboard: rules"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "When each agent will hit its limit", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Forecast"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/audit/verify": {"get": {"operationId": "verifyAudit", "tags": ["Dashboard: rules"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Check the tamper-evident audit chain", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuditVerify"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/webhooks": {"get": {"operationId": "listWebhooks", "tags": ["Dashboard: webhooks"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "List outbound webhooks and recent deliveries", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookList"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"operationId": "addWebhook", "tags": ["Dashboard: webhooks"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Add a webhook (Zapier, Make or any URL)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookCreated"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookCreate"}, "example": {"url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/", "label": "Text me approvals", "events": ["spend.needs_approval"]}}}}}}, "/api/webhooks/{webhook_id}": {"delete": {"operationId": "deleteWebhook", "tags": ["Dashboard: webhooks"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Delete a webhook", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "webhook_id", "in": "path", "required": true, "schema": {"type": "integer"}, "description": "Webhook ID."}]}}, "/api/webhooks/{webhook_id}/test": {"post": {"operationId": "testWebhook", "tags": ["Dashboard: webhooks"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Send a signed test.ping now", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookTestResult"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object"}, "example": {}}}}, "parameters": [{"name": "webhook_id", "in": "path", "required": true, "schema": {"type": "integer"}, "description": "Webhook ID."}]}}, "/api/stores": {"get": {"operationId": "listStores", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "The demo stores with their signed Store Policy and GuardPooch verdict", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"stores": {"type": "array", "items": {"type": "object", "properties": {"store_trust": {"type": "object", "description": "What the shopper should think of the store: GuardPooch's verdict plus this shopper's own orders there. A heuristic, not a public rating. See docs/TRUST-SCORE.md.", "properties": {"badge": {"type": "string", "enum": ["trusted", "careful", "danger"]}, "word": {"type": "string", "description": "Trusted store, Be careful or Danger"}, "score": {"type": "integer", "minimum": 0, "maximum": 100}, "factors": {"type": "array", "items": {"type": "object", "properties": {"label": {"type": "string"}, "delta": {"type": "integer"}, "detail": {"type": "string"}}}}, "kind": {"type": "string", "enum": ["heuristic"]}, "note": {"type": "string"}}}}}}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "agent_id", "in": "query", "schema": {"type": "integer"}, "description": "Defaults to the demo shopper, Scout, or the first agent."}]}}, "/api/stores/{store_id}/policy": {"put": {"operationId": "putStorePolicy", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Change a store's rules for AI shoppers (re-signed)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"max_order_no_human": {"type": "number"}, "categories": {"type": "array", "items": {"type": "string"}}, "min_trust": {"type": "integer"}, "require_evidence": {"type": "boolean"}, "blocked_agents": {"type": "array", "items": {"type": "string"}}, "mode": {"type": "string", "enum": ["auto", "review", "closed"], "description": "auto accepts in-policy orders; review needs a person for each; closed refuses all"}}}, "example": {"max_order_no_human": 150}}}}, "parameters": [{"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "harbor, pinepost, brightside, tidepool or fakeharbor."}]}}, "/.well-known/lowtides-store-policy.json": {"get": {"operationId": "getStorePolicyDocument", "tags": ["Consent Shopping"], "security": [], "summary": "A store's signed Store Policy (public)", "parameters": [{"name": "store_id", "in": "query", "schema": {"type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Check the signature with the public keys at /.well-known/lowtides-pass-keys.json."}}, "/api/catalog": {"get": {"operationId": "matchFinder", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Match Finder: every item with its Handshake signal for this shopper (green first)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"items": {"type": "array", "items": {"type": "object", "properties": {"store_trust": {"type": "object", "properties": {"badge": {"type": "string", "enum": ["trusted", "careful", "danger"]}, "score": {"type": "integer"}}}}}}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "q", "in": "query", "schema": {"type": "string"}}, {"name": "max_price", "in": "query", "schema": {"type": "number"}}, {"name": "agent_id", "in": "query", "schema": {"type": "integer"}, "description": "Defaults to the demo shopper, Scout, or the first agent."}, {"name": "store_id", "in": "query", "schema": {"type": "string"}}]}}, "/api/handshake": {"post": {"operationId": "doHandshake", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Run a Handshake (Pass vs Store Policy vs GuardPooch); with execute:true a match pays", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}, "signal": {"type": "string", "enum": ["match", "needs_yes", "no_match"]}, "headline": {"type": "string"}, "shopper_checks": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ok": {"type": "boolean"}, "level": {"type": "string", "enum": ["ok", "ask", "fail"]}, "detail": {"type": "string"}}}}, "store_checks": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ok": {"type": "boolean"}, "level": {"type": "string", "enum": ["ok", "ask", "fail"]}, "detail": {"type": "string"}}}}, "guardpooch": {"type": "object", "properties": {"verdict": {"type": "string", "enum": ["safe", "caution", "danger"]}, "score": {"type": "integer"}, "reasons": {"type": "array", "items": {"type": "string"}}, "checks": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ok": {"type": "boolean"}, "level": {"type": "string", "enum": ["ok", "ask", "fail"]}, "detail": {"type": "string"}}}}}}, "trust": {"type": "object", "properties": {"score": {"type": "integer"}}}, "store_trust": {"type": "object", "description": "What the shopper should think of the store: GuardPooch's verdict plus this shopper's own orders there. A heuristic, not a public rating. See docs/TRUST-SCORE.md.", "properties": {"badge": {"type": "string", "enum": ["trusted", "careful", "danger"]}, "word": {"type": "string", "description": "Trusted store, Be careful or Danger"}, "score": {"type": "integer", "minimum": 0, "maximum": 100}, "factors": {"type": "array", "items": {"type": "object", "properties": {"label": {"type": "string"}, "delta": {"type": "integer"}, "detail": {"type": "string"}}}}, "kind": {"type": "string", "enum": ["heuristic"]}, "note": {"type": "string"}}}, "receipt": {"type": "object", "description": "Signed with Ed25519 (kid, alg, signature); also written to the audit log."}, "order": {"type": ["object", "null"], "description": "PayPal sandbox payout (paypal_order_id is the payout batch id) or a labeled simulation."}, "approval_id": {"type": ["string", "null"]}, "at": {"type": "string"}}}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["store_id"], "properties": {"agent_id": {"type": "integer"}, "store_id": {"type": "string"}, "item_id": {"type": "string"}, "amount": {"type": "number"}, "category": {"type": "string"}, "title": {"type": "string"}, "execute": {"type": "boolean", "default": false}}}, "example": {"store_id": "harbor", "item_id": "harbor-hammer", "execute": false}}}}, "description": "match: both sides said yes. needs_yes: a person must approve (a normal held approval). no_match: no money moved. execute:true pays through the normal spend path, with a PayPal sandbox payout when keys are set and a labeled simulation otherwise."}}, "/api/handshakes": {"get": {"operationId": "listHandshakes", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Recent Handshakes, newest first", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"handshakes": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "signal": {"type": "string", "enum": ["match", "needs_yes", "no_match"]}, "headline": {"type": "string"}, "shopper_checks": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ok": {"type": "boolean"}, "level": {"type": "string", "enum": ["ok", "ask", "fail"]}, "detail": {"type": "string"}}}}, "store_checks": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ok": {"type": "boolean"}, "level": {"type": "string", "enum": ["ok", "ask", "fail"]}, "detail": {"type": "string"}}}}, "guardpooch": {"type": "object", "properties": {"verdict": {"type": "string", "enum": ["safe", "caution", "danger"]}, "score": {"type": "integer"}, "reasons": {"type": "array", "items": {"type": "string"}}, "checks": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ok": {"type": "boolean"}, "level": {"type": "string", "enum": ["ok", "ask", "fail"]}, "detail": {"type": "string"}}}}}}, "trust": {"type": "object", "properties": {"score": {"type": "integer"}}}, "store_trust": {"type": "object", "description": "What the shopper should think of the store: GuardPooch's verdict plus this shopper's own orders there. A heuristic, not a public rating. See docs/TRUST-SCORE.md.", "properties": {"badge": {"type": "string", "enum": ["trusted", "careful", "danger"]}, "word": {"type": "string", "description": "Trusted store, Be careful or Danger"}, "score": {"type": "integer", "minimum": 0, "maximum": 100}, "factors": {"type": "array", "items": {"type": "object", "properties": {"label": {"type": "string"}, "delta": {"type": "integer"}, "detail": {"type": "string"}}}}, "kind": {"type": "string", "enum": ["heuristic"]}, "note": {"type": "string"}}}, "receipt": {"type": "object", "description": "Signed with Ed25519 (kid, alg, signature); also written to the audit log."}, "order": {"type": ["object", "null"], "description": "PayPal sandbox payout (paypal_order_id is the payout batch id) or a labeled simulation."}, "approval_id": {"type": ["string", "null"]}, "at": {"type": "string"}}}}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "limit", "in": "query", "schema": {"type": "integer", "default": 50, "maximum": 500}}, {"name": "agent_id", "in": "query", "schema": {"type": "integer"}, "description": "Defaults to the demo shopper, Scout, or the first agent."}, {"name": "store_id", "in": "query", "schema": {"type": "string"}}]}}, "/api/handshakes/{handshake_id}/proof": {"get": {"operationId": "getHandshakeProof", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Proof pack: Pass, Store Policy, signed receipt, approval, PayPal ids, audit entry", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "handshake_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Handshake id (hs_...)."}], "description": "Verifiable with public keys only."}}, "/api/agents/{agent_id}/trust": {"get": {"operationId": "getTrust", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Agent trust score (0-100), a heuristic from its own history", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"score": {"type": "integer"}, "grade": {"type": "string"}, "factors": {"type": "array", "items": {"type": "object"}}, "history": {"type": "array", "items": {"type": "object"}}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "agent_id", "in": "path", "required": true, "schema": {"type": "integer"}, "description": "Agent ID."}]}}, "/api/merchant/kpis": {"get": {"operationId": "merchantKpis", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Store KPIs computed from real Handshakes and payments", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "store_id", "in": "query", "schema": {"type": "string"}}]}}, "/api/merchant/opportunities": {"get": {"operationId": "merchantOpportunities", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Rule-based suggestions from the store's own orders (what-if re-runs of the Handshake)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"findings": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "kind": {"type": "string", "enum": ["grow", "protect"]}, "title": {"type": "string"}, "detail": {"type": "string"}, "impact_usd": {"type": "number", "nullable": true}, "action": {"type": "object", "nullable": true, "properties": {"label": {"type": "string"}, "policy_patch": {"type": "object"}}}}}}, "note": {"type": "string"}}}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "store_id", "in": "query", "schema": {"type": "string"}, "required": true}], "description": "Apply a suggestion by sending its policy_patch to PUT /api/stores/{store_id}/policy."}}, "/api/handshakes/{handshake_id}/rating": {"post": {"operationId": "rateHandshake", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Was this what you wanted? Thumbs up or down for a paid purchase (changeable)", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}, "rating": {"type": "string", "enum": ["up", "down"]}, "store_trust": {"type": "object", "description": "What the shopper should think of the store: GuardPooch's verdict plus this shopper's own orders there. A heuristic, not a public rating. See docs/TRUST-SCORE.md.", "properties": {"badge": {"type": "string", "enum": ["trusted", "careful", "danger"]}, "word": {"type": "string", "description": "Trusted store, Be careful or Danger"}, "score": {"type": "integer", "minimum": 0, "maximum": 100}, "factors": {"type": "array", "items": {"type": "object", "properties": {"label": {"type": "string"}, "delta": {"type": "integer"}, "detail": {"type": "string"}}}}, "kind": {"type": "string", "enum": ["heuristic"]}, "note": {"type": "string"}}}, "agent_trust": {"type": "object", "properties": {"score": {"type": "integer"}, "grade": {"type": "string"}}}}}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["rating"], "properties": {"rating": {"type": "string", "enum": ["up", "down"]}}}, "example": {"rating": "up"}}}}, "parameters": [{"name": "handshake_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Handshake id (hs_...)."}], "description": "Thumbs down lowers the agent's trust score (see docs/TRUST-SCORE.md) and feeds satisfaction_rate in the store KPIs."}}, "/api/shopper/agents": {"get": {"operationId": "listShopperAgents", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "The shopper's AI shoppers: mode, Pass state, trust, today's spend, PayPal on file", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"agents": {"type": "array", "items": {"type": "object"}}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"operationId": "addShopperAgent", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Add an AI shopper from a preset (everyday, bargain, restock); issues its Pass", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"agent": {"type": "object"}}}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["preset"], "properties": {"preset": {"type": "string", "enum": ["everyday", "bargain", "restock"]}, "name": {"type": "string"}}}, "example": {"preset": "bargain"}}}}}}, "/api/shopper/prefs": {"get": {"operationId": "getShopperPrefs", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "A shopper's preferences in plain terms", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"daily_cap": {"type": "number"}, "per_item_cap": {"type": "number"}, "ask_above": {"type": "number"}, "guard_strictness": {"type": "string", "enum": ["relaxed", "balanced", "strict"]}, "deal_mode": {"type": "integer", "minimum": 0, "maximum": 100}, "mode": {"type": "string", "enum": ["autopilot", "assist", "off"], "description": "autopilot buys greens alone; assist asks before any money moves; off buys nothing"}, "categories_allowed": {"type": "array", "items": {"type": "string"}}, "never_buy": {"type": "array", "items": {"type": "string"}}}}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "agent_id", "in": "query", "schema": {"type": "integer"}, "description": "Defaults to the demo shopper, Scout, or the first agent."}]}, "put": {"operationId": "putShopperPrefs", "tags": ["Consent Shopping"], "security": [{"adminToken": []}, {"adminCookie": []}, {}], "summary": "Change preferences: rewrites the agent's enforced rules and re-issues its Pass", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"daily_cap": {"type": "number"}, "per_item_cap": {"type": "number"}, "ask_above": {"type": "number"}, "guard_strictness": {"type": "string", "enum": ["relaxed", "balanced", "strict"]}, "deal_mode": {"type": "integer", "minimum": 0, "maximum": 100}, "mode": {"type": "string", "enum": ["autopilot", "assist", "off"], "description": "autopilot buys greens alone; assist asks before any money moves; off buys nothing"}, "categories_allowed": {"type": "array", "items": {"type": "string"}}, "never_buy": {"type": "array", "items": {"type": "string"}}}}}}}, "400": {"description": "Bad request: the reason is in `error`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing or unknown key (or admin password).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Refused (cross-site request, or turned off in the public demo).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict: the request is no longer in a state that allows this.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Send JSON with Content-Type: application/json.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"daily_cap": {"type": "number"}, "per_item_cap": {"type": "number"}, "ask_above": {"type": "number"}, "guard_strictness": {"type": "string", "enum": ["relaxed", "balanced", "strict"]}, "deal_mode": {"type": "integer", "minimum": 0, "maximum": 100}, "mode": {"type": "string", "enum": ["autopilot", "assist", "off"], "description": "autopilot buys greens alone; assist asks before any money moves; off buys nothing"}, "categories_allowed": {"type": "array", "items": {"type": "string"}}, "never_buy": {"type": "array", "items": {"type": "string"}}}}, "example": {"guard_strictness": "balanced"}}}}, "parameters": [{"name": "agent_id", "in": "query", "schema": {"type": "integer"}, "description": "Defaults to the demo shopper, Scout, or the first agent."}]}}}, "webhooks": {"spend.needs_approval": {"post": {"operationId": "on_spend_needs_approval", "summary": "A purchase is waiting for a person to approve or deny it.", "parameters": [{"name": "X-Lowtides-Signature", "in": "header", "required": true, "schema": {"type": "string"}, "description": "t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">"}, {"name": "X-Lowtides-Event", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}}, "responses": {"200": {"description": "Any 2xx means received. Anything else is retried with backoff."}}}}, "spend.paid": {"post": {"operationId": "on_spend_paid", "summary": "A purchase was paid (PayPal Payouts, or simulated without PayPal keys).", "parameters": [{"name": "X-Lowtides-Signature", "in": "header", "required": true, "schema": {"type": "string"}, "description": "t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">"}, {"name": "X-Lowtides-Event", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}}, "responses": {"200": {"description": "Any 2xx means received. Anything else is retried with backoff."}}}}, "spend.denied": {"post": {"operationId": "on_spend_denied", "summary": "A purchase was blocked by the rules or denied by a person.", "parameters": [{"name": "X-Lowtides-Signature", "in": "header", "required": true, "schema": {"type": "string"}, "description": "t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">"}, {"name": "X-Lowtides-Event", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}}, "responses": {"200": {"description": "Any 2xx means received. Anything else is retried with backoff."}}}}, "agent.killed": {"post": {"operationId": "on_agent_killed", "summary": "An agent was shut off: stopped, pending buys denied, holds voided, unclaimed payouts canceled.", "parameters": [{"name": "X-Lowtides-Signature", "in": "header", "required": true, "schema": {"type": "string"}, "description": "t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">"}, {"name": "X-Lowtides-Event", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}}, "responses": {"200": {"description": "Any 2xx means received. Anything else is retried with backoff."}}}}, "stop_all": {"post": {"operationId": "on_stop_all", "summary": "STOP ALL was pressed (by a person or the outside spend guard).", "parameters": [{"name": "X-Lowtides-Signature", "in": "header", "required": true, "schema": {"type": "string"}, "description": "t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">"}, {"name": "X-Lowtides-Event", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}}, "responses": {"200": {"description": "Any 2xx means received. Anything else is retried with backoff."}}}}, "loop_guard.paused": {"post": {"operationId": "on_loop_guard_paused", "summary": "The loop guard paused an agent that kept repeating itself.", "parameters": [{"name": "X-Lowtides-Signature", "in": "header", "required": true, "schema": {"type": "string"}, "description": "t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">"}, {"name": "X-Lowtides-Event", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}}, "responses": {"200": {"description": "Any 2xx means received. Anything else is retried with backoff."}}}}}, "components": {"schemas": {"Error": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string", "description": "What went wrong, in plain English."}, "issue": {"type": "string", "description": "PayPal issue code, when PayPal refused something."}}}, "SpendRequest": {"type": "object", "required": ["amount", "merchant"], "additionalProperties": false, "properties": {"amount": {"type": "number", "exclusiveMinimum": 0, "maximum": 1000000, "description": "Dollars."}, "merchant": {"type": "string", "maxLength": 120, "description": "Who is being paid. Must match the merchant list to auto-approve."}, "item": {"type": "string", "maxLength": 300, "description": "What is being bought."}, "category": {"type": "string", "maxLength": 60, "description": "For category rules, e.g. data, software, travel."}, "reason": {"type": "string", "maxLength": 1000, "description": "Why the agent needs it. Checked for prompt-injection text."}, "task_id": {"type": "string", "maxLength": 80, "description": "Optional task to charge it to."}, "settle": {"type": "string", "enum": ["external"], "description": "Set to external when the caller (e.g. PayPal's Agent Toolkit) moves the money itself."}}}, "SpendDecision": {"type": "object", "required": ["id", "decision", "status", "amount", "merchant", "reasons", "flags"], "properties": {"id": {"type": "string", "pattern": "^sp_[0-9a-f]{16}$"}, "ts": {"type": "number", "description": "Unix time the request was made."}, "agent_id": {"type": "integer"}, "agent_name": {"type": ["string", "null"]}, "task_id": {"type": ["string", "null"]}, "amount": {"type": "number"}, "merchant": {"type": "string"}, "item": {"type": "string"}, "category": {"type": "string"}, "reason": {"type": "string"}, "decision": {"type": "string", "enum": ["approved", "needs_approval", "denied"], "description": "What the rules decided. Code decides, never the AI."}, "status": {"type": "string", "enum": ["approved", "pending", "paid", "denied", "cancelled", "failed"], "description": "Where the money is now. pending = waiting for a person; failed = no money moved."}, "reasons": {"type": "array", "items": {"type": "string"}, "description": "Plain-English reasons for the decision."}, "flags": {"type": "array", "items": {"type": "string", "enum": ["new_merchant", "possible_injection", "duplicate", "unusual_amount", "velocity", "paid_by_caller"]}}, "payee": {"type": "string", "description": "The PayPal email paid."}, "payout_batch_id": {"type": ["string", "null"]}, "payout_item_id": {"type": ["string", "null"]}, "payout_status": {"type": "string", "description": "PayPal payout item status (SUCCESS, UNCLAIMED, PENDING, RETURNED...), SIMULATED without PayPal keys, or PAID_BY_CALLER."}, "payout_env": {"type": "string", "enum": ["", "sandbox", "live"]}, "payout_proof": {"type": "string", "description": "One line you can check against PayPal."}, "simulated": {"type": "boolean"}, "decided_by": {"type": ["string", "null"]}, "decided_ts": {"type": ["number", "null"]}, "note": {"type": "string"}}}, "Budget": {"type": "object", "required": ["agent", "status", "tokens", "purchases", "rules"], "properties": {"agent": {"type": "string"}, "status": {"type": "string", "enum": ["on", "paused", "stopped"]}, "tokens": {"type": "object", "properties": {"daily_budget": {"type": "number"}, "spent_today": {"type": "number"}}}, "purchases": {"type": "object", "properties": {"daily_limit": {"type": "number"}, "spent_today": {"type": "number"}, "remaining_today": {"type": "number"}, "auto_approve_up_to": {"type": "number"}, "max_per_purchase": {"type": "number"}}}, "wallet_balance": {"type": ["number", "null"], "description": "Prepaid PayPal-funded wallet, when the agent uses one."}, "rules": {"$ref": "#/components/schemas/Rules"}, "rules_in_plain_english": {"type": "array", "items": {"type": "string"}}}}, "Rules": {"type": "object", "description": "Per-agent spending rules. Missing fields take their defaults.", "properties": {"max_per_purchase": {"type": "number", "default": 50}, "daily_purchase_limit": {"type": "number", "default": 200}, "approval_over": {"type": "number", "default": 20, "description": "Purchases above this wait for a person."}, "daily_total_limit": {"type": ["number", "null"], "description": "AI usage plus purchases together. null = off."}, "allowed_categories": {"type": "array", "items": {"type": "string"}, "description": "Empty = any category not blocked."}, "blocked_categories": {"type": "array", "items": {"type": "string"}, "default": ["gift cards", "crypto"]}, "blocked_merchants": {"type": "array", "items": {"type": "string"}}, "new_merchant_needs_approval": {"type": "boolean", "default": true}, "hours": {"type": ["object", "null"], "properties": {"start": {"type": "integer"}, "end": {"type": "integer"}}}, "max_purchases_per_hour": {"type": "integer", "default": 10}, "max_reply_tokens": {"type": ["integer", "null"]}, "max_input_tokens": {"type": ["integer", "null"]}, "max_cost_per_call": {"type": ["number", "null"]}, "dump_alert_multiple": {"type": ["number", "null"], "default": 5}}}, "RulesCompileResult": {"type": "object", "properties": {"rules": {"$ref": "#/components/schemas/Rules"}, "set": {"type": "array", "items": {"type": "string"}}, "source": {"type": "string", "enum": ["claude", "offline"]}, "model": {"type": "string"}, "notes": {"type": "array", "items": {"type": "string"}}}}, "Agent": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "key": {"type": "string", "pattern": "^lt-", "description": "The agent's Lowtides key: use it as the API key."}, "daily_budget": {"type": "number"}, "task_budget": {"type": "number"}, "status": {"type": "string", "enum": ["on", "paused", "stopped"]}, "client_id": {"type": ["integer", "null"]}, "use_wallet": {"type": "integer"}, "rules": {"type": ["string", "null"]}, "created": {"type": "number"}}}, "AgentCreate": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}, "daily_budget": {"type": "number", "exclusiveMinimum": 0, "description": "AI usage, dollars a day."}, "task_budget": {"type": "number", "exclusiveMinimum": 0}, "client_id": {"type": ["integer", "null"]}, "use_wallet": {"type": "boolean", "description": "Spend only from a prepaid PayPal-funded wallet."}}}, "State": {"type": "object", "additionalProperties": true, "description": "Everything the dashboard shows.", "properties": {"version": {"type": "string"}, "mode": {"type": "string", "enum": ["home", "business"]}, "agents": {"type": "array", "items": {"$ref": "#/components/schemas/Agent"}}, "events": {"type": "array", "items": {"type": "object"}}, "public_demo": {"type": "boolean"}, "paypal_ready": {"type": "boolean"}}}, "SpendList": {"type": "object", "properties": {"requests": {"type": "array", "items": {"$ref": "#/components/schemas/SpendDecision"}}}}, "KillResult": {"type": "object", "properties": {"stopped": {"type": "boolean"}, "denied": {"type": "integer"}, "holds_voided": {"type": "integer"}, "payouts_cancelled": {"type": "integer"}, "problems": {"type": "array", "items": {"type": "string"}}}}, "AskAnswer": {"type": "object", "properties": {"answer": {"type": "string"}, "source": {"type": "string", "enum": ["claude", "scripted"]}, "actions": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "kind": {"type": "string"}, "params": {"type": "object"}}}}, "cost_usd": {"type": "number"}}}, "StopAllResult": {"type": "object", "properties": {"ok": {"type": "boolean"}, "denied": {"type": "integer"}, "holds_voided": {"type": "integer"}, "payouts_cancelled": {"type": "integer"}}}, "Merchant": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "paypal_email": {"type": "string"}, "category": {"type": "string"}, "created": {"type": "number"}}}, "Forecast": {"type": "object", "properties": {"generated": {"type": "number"}, "agents": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "status": {"type": "string"}, "tokens_today": {"type": "number"}, "purchases_today": {"type": "number"}, "spent_today": {"type": "number"}, "limit": {"type": ["number", "null"]}, "limit_kind": {"type": "string"}, "rate_per_hour": {"type": "number"}, "projected_today": {"type": "number"}, "minutes_to_limit": {"type": ["number", "null"]}}}}}}, "AuditVerify": {"type": "object", "properties": {"ok": {"type": "boolean"}, "count": {"type": "integer"}, "broken_at": {"type": ["integer", "null"]}}}, "ModelList": {"type": "object", "properties": {"object": {"const": "list"}, "data": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "object": {"const": "model"}, "owned_by": {"type": ["string", "null"]}}}}}}, "ChatCompletionRequest": {"type": "object", "required": ["model", "messages"], "additionalProperties": true, "description": "OpenAI Chat Completions request. Other OpenAI fields pass through.", "properties": {"model": {"type": "string", "description": "The model asked for. Lowtides may route an easy step to a cheaper one."}, "messages": {"type": "array", "items": {"type": "object", "properties": {"role": {"type": "string"}, "content": {}}, "required": ["role"]}}, "max_tokens": {"type": "integer"}, "stream": {"type": "boolean"}, "tools": {"type": "array", "items": {"type": "object"}}}}, "ChatCompletion": {"type": "object", "additionalProperties": true, "properties": {"id": {"type": "string"}, "object": {"type": "string"}, "model": {"type": "string"}, "choices": {"type": "array", "items": {"type": "object"}}, "usage": {"type": "object"}}}, "MessageRequest": {"type": "object", "required": ["model", "messages", "max_tokens"], "additionalProperties": true, "description": "Anthropic Messages request. Other Anthropic fields pass through.", "properties": {"model": {"type": "string"}, "max_tokens": {"type": "integer"}, "system": {}, "messages": {"type": "array", "items": {"type": "object"}}, "stream": {"type": "boolean"}}}, "Message": {"type": "object", "additionalProperties": true, "properties": {"id": {"type": "string"}, "type": {"type": "string"}, "model": {"type": "string"}, "content": {"type": "array", "items": {"type": "object"}}, "usage": {"type": "object"}}}, "BlockedError": {"type": "object", "description": "OpenAI-style or Anthropic-style error body.", "properties": {"type": {"type": "string"}, "error": {"type": "object", "properties": {"type": {"type": "string", "examples": ["lowtides_blocked"]}, "code": {"type": "string", "examples": ["over_daily_budget", "agent_stopped", "agent_paused", "loop_detected"]}, "message": {"type": "string"}}}}}, "WebhookCreate": {"type": "object", "required": ["url"], "properties": {"url": {"type": "string", "format": "uri", "description": "For example a Zapier Catch Hook URL."}, "label": {"type": "string", "maxLength": 80}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/EventType"}, "description": "Empty or missing = every event."}}}, "Webhook": {"type": "object", "properties": {"id": {"type": "integer"}, "url": {"type": "string"}, "label": {"type": "string"}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/EventType"}}, "active": {"type": "boolean"}, "created": {"type": "number"}, "secret_hint": {"type": "string"}}}, "WebhookCreated": {"type": "object", "properties": {"webhook": {"$ref": "#/components/schemas/Webhook"}, "secret": {"type": "string", "description": "Signing secret (whsec_...). Shown only once: save it now."}}}, "WebhookDelivery": {"type": "object", "properties": {"id": {"type": "integer"}, "ts": {"type": "number"}, "webhook_id": {"type": "integer"}, "event_id": {"type": "string"}, "event": {"type": "string"}, "attempt": {"type": "integer"}, "ok": {"type": "integer"}, "status": {"type": ["integer", "null"]}, "error": {"type": "string"}, "ms": {"type": "integer"}}}, "WebhookList": {"type": "object", "properties": {"webhooks": {"type": "array", "items": {"$ref": "#/components/schemas/Webhook"}}, "deliveries": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookDelivery"}}, "events": {"type": "object", "additionalProperties": {"type": "string"}}, "signature_header": {"type": "string"}}}, "WebhookTestResult": {"type": "object", "properties": {"ok": {"type": "boolean"}, "status": {"type": ["integer", "null"]}, "error": {"type": ["string", "null"]}, "event": {"$ref": "#/components/schemas/Event"}}}, "EventType": {"type": "string", "enum": ["spend.needs_approval", "spend.paid", "spend.denied", "agent.killed", "stop_all", "loop_guard.paused"]}, "Event": {"type": "object", "required": ["id", "type", "created", "data"], "description": "What Lowtides POSTs to your webhook. Signed with the X-Lowtides-Signature header: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with your webhook secret>.", "properties": {"id": {"type": "string", "pattern": "^evt_"}, "type": {"type": "string", "description": "An EventType, or test.ping from the Test button."}, "created": {"type": "integer"}, "description": {"type": "string"}, "dashboard": {"type": ["string", "null"]}, "data": {"type": "object", "additionalProperties": true, "description": "spend.* events carry the spend request (id, agent_name, amount, merchant, item, reasons, status...); spend.needs_approval adds approve_url. agent.killed carries the kill result; stop_all the totals; loop_guard.paused agent_id, agent_name and repeats."}}}}, "securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "lt-...", "description": "The agent's Lowtides key (from the dashboard)."}, "apiKeyHeader": {"type": "apiKey", "in": "header", "name": "x-api-key", "description": "The same agent key, Anthropic-style."}, "adminToken": {"type": "apiKey", "in": "header", "name": "X-Admin-Token", "description": "Dashboard password (LOWTIDES_ADMIN_TOKEN). Not needed in the public demo."}, "adminCookie": {"type": "apiKey", "in": "cookie", "name": "lt_admin", "description": "Set by POST /api/login."}}}}