{ "openapi": "3.1.0", "info": { "title": "dogabot REST API", "version": "1.0.0", "description": "Public API-key surface for Pro and Institutional accounts. Authenticate with Bearer dbk_live_\u2026 at https://api.dogabot.com/api/v1. This catalog is exactly the API-key allowlist \u2014 session-only routes are omitted. MCP tools: https://docs.dogabot.com/mcp/" }, "servers": [ { "url": "https://api.dogabot.com" } ], "tags": [ { "name": "Account" }, { "name": "Automations" }, { "name": "Orders" }, { "name": "Signals" }, { "name": "Backtests" }, { "name": "Markets" }, { "name": "Terminal" }, { "name": "Credentials" }, { "name": "Ask AI" } ], "paths": { "/api/v1/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "Current user profile for the API key owner", "description": "Returns the account that owns this API key (id, plan flags, and display fields).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:account" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "user_id": "user_2abcExample", "has_pro_access": true, "has_premium_access": true, "plan_tier": "pro", "eligible_for_trial": false, "running_automations_total": 2, "max_concurrent_automations": 10 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/me/statistics": { "get": { "operationId": "getMeStatistics", "tags": [ "Account" ], "summary": "Aggregated account statistics", "description": "Returns aggregated trading statistics for the key owner.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:account" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "running_count": 2, "total_volume": 125000, "update_interval_minutes": 15 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/me/positions": { "get": { "operationId": "getMePositions", "tags": [ "Account" ], "summary": "Open positions across automations", "description": "Lists open positions across the key owner's automations.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:account" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "symbol": "BTC", "exchange": "hyperliquid", "side": "Long", "quantity": 0.01, "unrealized_pnl": 12.5 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/me/position-legs": { "get": { "operationId": "getMePositionlegs", "tags": [ "Account" ], "summary": "Position legs across automations", "description": "Lists position legs (per-fill breakdown) across the key owner's automations.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:account" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "symbol": "BTC", "exchange": "hyperliquid", "quantity": 0.01, "side": "Long" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/me/available-cash": { "get": { "operationId": "getMeAvailablecash", "tags": [ "Account" ], "summary": "Free stable cash across credential venues", "description": "Returns the sum of live free stable balances (USDT, USDC, USD, FDUSD, BUSD) across the key owner's credential venues. Per-venue failures are omitted and incomplete is true.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:account" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "cash": 12450.32, "asset_basis": [ "USDT", "USDC", "USD", "FDUSD", "BUSD" ], "by_exchange": [ { "exchange": "binance_usdm", "free": 1253.47 } ], "incomplete": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/me/orders": { "get": { "operationId": "getMeOrders", "tags": [ "Account" ], "summary": "Recent orders for the account", "description": "Lists recent automation orders for the key owner.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 9001, "side": "buy", "quantity": 0.01, "status": "filled", "symbol": "BTC", "exchange": "hyperliquid" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/me/signals": { "get": { "operationId": "getMeSignals", "tags": [ "Account" ], "summary": "Recent signals for the account", "description": "Lists recent emitter signals for the key owner.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:signals" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 501, "side": "buy", "symbol": "BTC", "created_at": "2026-04-01T12:00:00Z" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/me/emitters": { "get": { "operationId": "getMeEmitters", "tags": [ "Account" ], "summary": "Emitters owned by the account (terminal leader list)", "description": "Lists emitters the key owner can use as a terminal leader.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 1001, "name": "Desk BTC emitter", "exchange": "hyperliquid", "symbol": "BTC", "status": "running", "trading_mode": "paper" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/me/emitters/summary": { "post": { "operationId": "postMeEmittersSummary", "tags": [ "Account" ], "summary": "Filtered summary of owned emitters", "description": "Returns a filtered summary of the key owner's emitters. Optional JSON body (limit default 50, max 100, offset, filters). Response is { items, total, limit, offset }. This is a read.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 1001, "name": "Desk BTC emitter", "status": "running" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Default 50, max 100.", "example": 20 }, "offset": { "type": "integer", "minimum": 0, "description": "Items to skip. Default 0. Use with total from the previous page.", "example": 0 }, "sortBy": { "type": "string", "description": "Sort field (e.g. pnl).", "example": "pnl" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" }, "symbol": { "type": "string", "example": "BTC" }, "exchange": { "type": "string", "example": "hyperliquid" }, "status": { "type": "string", "description": "running, stopped, or omit for all.", "example": "running" }, "tradingMode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "marketType": { "type": "string" }, "category": { "type": "string" }, "nameQuery": { "type": "string", "description": "Case-insensitive name search." }, "day_trade_mode": { "type": "boolean" }, "enabled_rule": { "type": "string", "description": "Only rows with this strategy rule enabled." } } }, "example": { "limit": 20, "offset": 0, "sortBy": "pnl", "sortDir": "desc", "status": "running", "tradingMode": "paper", "exchange": "hyperliquid", "symbol": "BTC" } } } } } }, "/api/v1/automations/summary": { "post": { "operationId": "postAutomationsSummary", "tags": [ "Automations" ], "summary": "Filtered summary of automations", "description": "Returns a filtered summary of the key owner's automations (followers, bots, emitters, portfolios). Optional JSON body (limit default 50, max 100, offset, filters, types). Response is { items, total, limit, offset }. This is a read.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 42, "type": "follower", "name": "BTC paper follower", "status": "running" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Default 50, max 100.", "example": 20 }, "offset": { "type": "integer", "minimum": 0, "description": "Items to skip. Default 0. Use with total from the previous page.", "example": 0 }, "sortBy": { "type": "string", "description": "Sort field (e.g. pnl).", "example": "pnl" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" }, "symbol": { "type": "string", "example": "BTC" }, "exchange": { "type": "string", "example": "hyperliquid" }, "status": { "type": "string", "description": "running, stopped, or omit for all.", "example": "running" }, "tradingMode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "marketType": { "type": "string" }, "category": { "type": "string" }, "nameQuery": { "type": "string", "description": "Case-insensitive name search." }, "day_trade_mode": { "type": "boolean" }, "enabled_rule": { "type": "string", "description": "Only rows with this strategy rule enabled." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "follower", "bot", "emitter", "portfolio" ] }, "description": "Restrict to these automation types. Omit for all." } } }, "example": { "limit": 20, "offset": 0, "sortBy": "pnl", "sortDir": "desc", "status": "running", "tradingMode": "paper", "exchange": "hyperliquid", "symbol": "BTC", "types": [ "follower", "bot" ] } } } } } }, "/api/v1/automations/status-counts": { "post": { "operationId": "postAutomationsStatuscounts", "tags": [ "Automations" ], "summary": "Running/stopped totals for automations", "description": "Returns { running, stopped, total } for the key owner's automations under the same filters as POST /automations/summary (pagination/sort/status ignored). This is a read.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "running": 3, "stopped": 5, "total": 8 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "example": "BTC" }, "exchange": { "type": "string", "example": "hyperliquid" }, "tradingMode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "marketType": { "type": "string" }, "category": { "type": "string" }, "nameQuery": { "type": "string" }, "day_trade_mode": { "type": "boolean" }, "enabled_rule": { "type": "string" }, "types": { "type": "array", "items": { "type": "string", "enum": [ "follower", "bot", "emitter", "portfolio" ] } } } }, "example": { "tradingMode": "paper", "exchange": "hyperliquid", "types": [ "follower", "bot" ] } } } } } }, "/api/v1/automations/summary/by-ids": { "post": { "operationId": "postAutomationsSummaryByids", "tags": [ "Automations" ], "summary": "Batch automation summaries by typed ids", "description": "Returns owned automation summaries for a batch of typed ids (max 50). Body: { ids: [{ type, id }] }. Missing or unauthorized ids are omitted. Response is { items, total, limit, offset }. This is a read.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 7, "type": "bot", "name": "BTC paper bot", "status": "stopped" }, { "id": 42, "type": "follower", "name": "BTC paper follower", "status": "running" } ], "total": 2, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "follower", "bot", "emitter", "portfolio" ] }, "id": { "type": "integer", "minimum": 1, "example": 7 } } } } } }, "example": { "ids": [ { "type": "bot", "id": 7 }, { "type": "follower", "id": 42 } ] } } } } } }, "/api/v1/followers": { "get": { "operationId": "getFollowers", "tags": [ "Automations" ], "summary": "List followers", "description": "Lists followers the key owner can access.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 42, "name": "BTC paper follower", "exchange": "hyperliquid", "symbol": "BTC", "status": "stopped", "trading_mode": "paper", "emitter_id": 1001, "initial_capital": 10000 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "post": { "operationId": "postFollowers", "tags": [ "Automations" ], "summary": "Create a follower", "description": "Creates a follower for the key owner. Optional loss_limit_pct (0\u2013100) blocks new risk after total PnL reaches \u2212pct% of initial_capital until restart. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "data": { "id": 42, "name": "BTC paper follower", "exchange": "hyperliquid", "symbol": "BTC", "status": "stopped", "trading_mode": "paper", "emitter_id": 1001, "initial_capital": 10000 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emitter_id", "name", "exchange", "symbol", "initial_capital" ], "properties": { "emitter_id": { "type": "integer", "example": 1001 }, "name": { "type": "string", "example": "BTC paper follower" }, "exchange": { "type": "string", "example": "hyperliquid" }, "symbol": { "type": "string", "example": "BTC" }, "initial_capital": { "type": "number", "example": 10000 }, "loss_limit_pct": { "type": "number", "minimum": 0, "maximum": 100, "example": 20, "description": "Optional max loss as % of initial_capital. When total PnL hits \u2212pct%, new risk is blocked until the follower is restarted. 0 or omit = off. Create-only." }, "trading_mode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "market_type_id": { "type": "integer", "description": "Optional; looked up from the exchange when omitted." }, "markets": { "type": "array", "description": "Optional multi-leg markets. When omitted, a single primary leg is built from exchange/symbol.", "items": { "type": "object", "additionalProperties": true } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Existing catalog lookup_keys (max 5)." }, "params": { "type": "object", "additionalProperties": true, "description": "Optional strategy overrides. Same shape as the webapp save payload. Omit to inherit from the emitter." } } }, "example": { "emitter_id": 1001, "name": "BTC paper follower", "exchange": "hyperliquid", "symbol": "BTC", "initial_capital": 10000, "trading_mode": "paper" } } } } } }, "/api/v1/followers/{id}": { "get": { "operationId": "getFollowersById", "tags": [ "Automations" ], "summary": "Get a follower", "description": "Returns one follower by id, if the key owner can access it.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 42, "name": "BTC paper follower", "exchange": "hyperliquid", "symbol": "BTC", "status": "stopped", "trading_mode": "paper", "emitter_id": 1001, "initial_capital": 10000 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "patch": { "operationId": "patchFollowersById", "tags": [ "Automations" ], "summary": "Update a follower", "description": "Partial update of an owned follower. The follower must be stopped. Omit fields you do not want to change. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 42, "name": "BTC paper follower", "exchange": "hyperliquid", "symbol": "BTC", "status": "stopped", "trading_mode": "paper", "emitter_id": 1001, "initial_capital": 10000 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update. Follower must be stopped. Omit a field to leave it unchanged.", "properties": { "name": { "type": "string", "example": "BTC paper follower" }, "exchange": { "type": "string", "example": "hyperliquid" }, "symbol": { "type": "string", "example": "BTC" }, "orderQuantityMultiplier": { "type": "number", "minimum": 1, "description": "Absolute lots vs venue min lot (1 = min lot). Create default is 2\u00d7 for min-notional close headroom." }, "include_in_agg_stats": { "type": "boolean" }, "markets": { "type": "array", "description": "When present, replaces all trade legs. Omit to leave markets unchanged.", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "name": "BTC paper follower", "exchange": "hyperliquid", "symbol": "BTC", "include_in_agg_stats": true } } } } }, "delete": { "operationId": "deleteFollowersById", "tags": [ "Automations" ], "summary": "Delete a follower", "description": "Deletes an owned follower (requires confirm_delete). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "follower deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "confirm_delete": true } } } } } }, "/api/v1/followers/summary": { "post": { "operationId": "postFollowersSummary", "tags": [ "Automations" ], "summary": "Filtered follower summaries", "description": "Returns filtered follower summaries. Optional JSON body: limit (default 50, max 100), offset, sortBy/sortDir, and filters (symbol, exchange, status, tradingMode, \u2026). Response is { items, total, limit, offset }. This is a read.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 42, "name": "BTC paper follower", "status": "running" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Default 50, max 100.", "example": 20 }, "offset": { "type": "integer", "minimum": 0, "description": "Items to skip. Default 0. Use with total from the previous page.", "example": 0 }, "sortBy": { "type": "string", "description": "Sort field (e.g. pnl).", "example": "pnl" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" }, "symbol": { "type": "string", "example": "BTC" }, "exchange": { "type": "string", "example": "hyperliquid" }, "status": { "type": "string", "description": "running, stopped, or omit for all.", "example": "running" }, "tradingMode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "marketType": { "type": "string" }, "category": { "type": "string" }, "nameQuery": { "type": "string", "description": "Case-insensitive name search." }, "day_trade_mode": { "type": "boolean" }, "enabled_rule": { "type": "string", "description": "Only rows with this strategy rule enabled." } } }, "example": { "limit": 20, "offset": 0, "sortBy": "pnl", "sortDir": "desc", "status": "running", "tradingMode": "paper", "exchange": "hyperliquid", "symbol": "BTC" } } } } } }, "/api/v1/followers/summary/{id}": { "get": { "operationId": "getFollowersSummaryById", "tags": [ "Automations" ], "summary": "Follower summary by id", "description": "Returns a compact summary card for one follower.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 42, "name": "BTC paper follower", "status": "running" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/followers/{id}/pnl-series": { "get": { "operationId": "getFollowersPnlseriesById", "tags": [ "Automations" ], "summary": "Follower PnL series", "description": "Returns historical PnL points for a follower.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "timestamp": 1711929600, "open_pnl": 8.25, "closed_pnl": 4.0, "total_pnl": 12.25 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/followers/{id}/position": { "get": { "operationId": "getFollowersPositionById", "tags": [ "Automations" ], "summary": "Follower position", "description": "Returns the current position for a follower.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "symbol": "BTC", "exchange": "hyperliquid", "side": "Long", "quantity": 0.01, "unrealized_pnl": 12.5 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/bots": { "get": { "operationId": "getBots", "tags": [ "Automations" ], "summary": "List bots", "description": "Lists bots the key owner can access.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 7, "name": "BTC paper bot", "exchange": "hyperliquid", "symbol": "BTC", "status": "stopped", "trading_mode": "paper" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "post": { "operationId": "postBots", "tags": [ "Automations" ], "summary": "Create a bot", "description": "Creates a bot for the key owner. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "data": { "id": 7, "name": "BTC paper bot", "exchange": "hyperliquid", "symbol": "BTC", "status": "stopped", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "exchange", "symbol", "initial_capital", "execution_interval", "candle_timeframe" ], "properties": { "name": { "type": "string", "example": "Paper BTC trend" }, "exchange": { "type": "string", "example": "binance_usdm" }, "symbol": { "type": "string", "example": "BTC" }, "initial_capital": { "type": "number", "minimum": 0, "example": 10000 }, "execution_interval": { "type": "integer", "description": "Strategy tick in milliseconds (must be compatible with candle_timeframe).", "example": 3600000 }, "candle_timeframe": { "type": "string", "description": "Candle size, e.g. 1h or 60.", "example": "1h" }, "trading_mode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper", "description": "REST defaults to live when omitted. Prefer paper for new bots." }, "market_type_id": { "type": "integer", "description": "Optional; looked up from the exchange when omitted." }, "markets": { "type": "array", "description": "Optional multi-leg markets. When omitted, a single primary leg is built from exchange/symbol.", "items": { "type": "object", "additionalProperties": true } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Existing catalog lookup_keys (max 5)." }, "params": { "type": "object", "additionalProperties": true, "description": "Strategy params in the webapp save shape. Needs entry.rules (and usually exit/increase/reversal sections) for validation. Named-rule wire shapes: https://docs.dogabot.com/rules/ (JSON: /rule-examples.json). Ask AI / customLogic recipes: https://docs.dogabot.com/recipes/ (JSON: /recipe-examples.json)." } } }, "example": { "name": "Paper BTC trend", "trading_mode": "paper", "exchange": "binance_usdm", "symbol": "BTC", "initial_capital": 10000, "execution_interval": 3600000, "candle_timeframe": "1h", "params": { "entry": { "combinationMode": "all_agree", "agreementThreshold": 1, "rules": { "rsi": { "enabled": true, "invert": false, "params": { "period": 14, "oversold": 30, "overbought": 70 } } } }, "exit": { "combinationMode": "all_agree", "rules": {} }, "increase": { "combinationMode": "all_agree", "rules": {} }, "reversal": { "combinationMode": "all_agree", "rules": {} } } } } } } } }, "/api/v1/bots/{id}": { "get": { "operationId": "getBotsById", "tags": [ "Automations" ], "summary": "Get a bot", "description": "Returns one bot by id, if the key owner can access it.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 7, "name": "BTC paper bot", "exchange": "hyperliquid", "symbol": "BTC", "status": "stopped", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "patch": { "operationId": "patchBotsById", "tags": [ "Automations" ], "summary": "Update a bot", "description": "Partial update of an owned bot. The bot must be stopped. Omit fields you do not want to change. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 7, "name": "BTC paper bot", "exchange": "hyperliquid", "symbol": "BTC", "status": "stopped", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update. Bot must be stopped. Omit a field to leave it unchanged.", "properties": { "name": { "type": "string", "example": "BTC paper bot" }, "exchange": { "type": "string", "example": "hyperliquid" }, "symbol": { "type": "string", "example": "BTC" }, "initial_capital": { "type": "number", "example": 10000 }, "execution_interval": { "type": "integer", "description": "Milliseconds.", "example": 3600000 }, "candle_timeframe": { "type": "string", "example": "1h" }, "include_in_agg_stats": { "type": "boolean", "example": true }, "markets": { "type": "array", "description": "When present, replaces all trade legs. Omit to leave markets unchanged.", "items": { "type": "object", "additionalProperties": true } }, "params": { "type": "object", "additionalProperties": true, "description": "Strategy params. Same shape as the webapp save payload. Omit to leave unchanged." } } }, "example": { "name": "BTC paper bot", "exchange": "hyperliquid", "symbol": "BTC", "initial_capital": 10000, "execution_interval": 3600000, "candle_timeframe": "1h", "include_in_agg_stats": true } } } } }, "delete": { "operationId": "deleteBotsById", "tags": [ "Automations" ], "summary": "Delete a bot", "description": "Deletes an owned bot (requires confirm_delete). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "bot deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "confirm_delete": true } } } } } }, "/api/v1/bots/summary": { "post": { "operationId": "postBotsSummary", "tags": [ "Automations" ], "summary": "Filtered bot summaries", "description": "Returns filtered bot summaries. Optional JSON body: limit (default 50, max 100), offset, and the same filter fields as follower summary. Response is { items, total, limit, offset }. This is a read.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 7, "name": "BTC paper bot", "status": "stopped" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Default 50, max 100.", "example": 20 }, "offset": { "type": "integer", "minimum": 0, "description": "Items to skip. Default 0. Use with total from the previous page.", "example": 0 }, "sortBy": { "type": "string", "description": "Sort field (e.g. pnl).", "example": "pnl" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" }, "symbol": { "type": "string", "example": "BTC" }, "exchange": { "type": "string", "example": "hyperliquid" }, "status": { "type": "string", "description": "running, stopped, or omit for all.", "example": "running" }, "tradingMode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "marketType": { "type": "string" }, "category": { "type": "string" }, "nameQuery": { "type": "string", "description": "Case-insensitive name search." }, "day_trade_mode": { "type": "boolean" }, "enabled_rule": { "type": "string", "description": "Only rows with this strategy rule enabled." } } }, "example": { "limit": 20, "offset": 0, "sortBy": "pnl", "sortDir": "desc", "status": "running", "tradingMode": "paper", "exchange": "hyperliquid", "symbol": "BTC" } } } } } }, "/api/v1/bots/{id}/pnl-series": { "get": { "operationId": "getBotsPnlseriesById", "tags": [ "Automations" ], "summary": "Bot PnL series", "description": "Returns historical PnL points for a bot.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "timestamp": 1711929600, "open_pnl": 8.25, "closed_pnl": 4.0, "total_pnl": 12.25 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/bots/{id}/position": { "get": { "operationId": "getBotsPositionById", "tags": [ "Automations" ], "summary": "Bot position", "description": "Returns the current position for a bot.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "symbol": "BTC", "exchange": "hyperliquid", "side": "Long", "quantity": 0.01, "unrealized_pnl": 12.5 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/emitters": { "get": { "operationId": "getEmitters", "tags": [ "Automations" ], "summary": "List emitters", "description": "Lists emitters the key owner can access.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 1001, "name": "Desk BTC emitter", "exchange": "hyperliquid", "symbol": "BTC", "status": "running", "trading_mode": "paper" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "post": { "operationId": "postEmitters", "tags": [ "Automations" ], "summary": "Create an emitter", "description": "Creates an emitter for the key owner. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "data": { "id": 1001, "name": "Desk BTC emitter", "exchange": "hyperliquid", "symbol": "BTC", "status": "running", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "exchange", "symbol", "initial_capital", "execution_interval", "candle_timeframe" ], "properties": { "name": { "type": "string", "example": "Desk BTC emitter" }, "exchange": { "type": "string", "example": "hyperliquid" }, "symbol": { "type": "string", "example": "BTC" }, "initial_capital": { "type": "number", "minimum": 0, "example": 10000 }, "execution_interval": { "type": "integer", "description": "Strategy tick in milliseconds (must be compatible with candle_timeframe).", "example": 3600000 }, "candle_timeframe": { "type": "string", "description": "Candle size, e.g. 1h or 60.", "example": "1h" }, "category_id": { "type": "integer", "description": "Optional marketplace category id." }, "accept_terminal_signals": { "type": "boolean", "description": "When true, the emitter accepts terminal dock signals." }, "market_type_id": { "type": "integer", "description": "Optional; looked up from the exchange when omitted." }, "markets": { "type": "array", "description": "Optional multi-leg markets. When omitted, a single primary leg is built from exchange/symbol.", "items": { "type": "object", "additionalProperties": true } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Existing catalog lookup_keys (max 5)." }, "params": { "type": "object", "additionalProperties": true, "description": "Strategy params in the webapp save shape. Needs entry.rules (and usually exit/increase/reversal sections) for validation. Named-rule wire shapes: https://docs.dogabot.com/rules/ (JSON: /rule-examples.json). Ask AI / customLogic recipes: https://docs.dogabot.com/recipes/ (JSON: /recipe-examples.json)." } } }, "example": { "name": "Desk BTC emitter", "exchange": "hyperliquid", "symbol": "BTC", "initial_capital": 10000, "execution_interval": 3600000, "candle_timeframe": "1h", "params": { "entry": { "combinationMode": "all_agree", "agreementThreshold": 1, "rules": { "rsi": { "enabled": true, "invert": false, "params": { "period": 14, "oversold": 30, "overbought": 70 } } } }, "exit": { "combinationMode": "all_agree", "rules": {} }, "increase": { "combinationMode": "all_agree", "rules": {} }, "reversal": { "combinationMode": "all_agree", "rules": {} } } } } } } } }, "/api/v1/emitters/{id}": { "get": { "operationId": "getEmittersById", "tags": [ "Automations" ], "summary": "Get an emitter", "description": "Returns one emitter by id, if the key owner can access it.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 1001, "name": "Desk BTC emitter", "exchange": "hyperliquid", "symbol": "BTC", "status": "running", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "patch": { "operationId": "patchEmittersById", "tags": [ "Automations" ], "summary": "Update an emitter", "description": "Partial update of an owned emitter. The emitter must be stopped. Omit fields you do not want to change. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 1001, "name": "Desk BTC emitter", "exchange": "hyperliquid", "symbol": "BTC", "status": "running", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update. Emitter must be stopped. Omit a field to leave it unchanged.", "properties": { "name": { "type": "string", "example": "Desk BTC emitter" }, "exchange": { "type": "string", "example": "hyperliquid" }, "symbol": { "type": "string", "example": "BTC" }, "initial_capital": { "type": "number", "example": 10000 }, "execution_interval": { "type": "integer", "description": "Milliseconds.", "example": 3600000 }, "candle_timeframe": { "type": "string", "example": "1h" }, "market_type_id": { "type": "integer" }, "category_id": { "type": "integer" }, "accept_terminal_signals": { "type": "boolean" }, "markets": { "type": "array", "description": "When present, replaces all trade legs. Omit to leave markets unchanged.", "items": { "type": "object", "additionalProperties": true } }, "params": { "type": "object", "additionalProperties": true, "description": "Strategy params. Same shape as the webapp save payload. Omit to leave unchanged." } } }, "example": { "name": "Desk BTC emitter", "exchange": "hyperliquid", "symbol": "BTC", "initial_capital": 10000, "execution_interval": 3600000, "candle_timeframe": "1h" } } } } }, "delete": { "operationId": "deleteEmittersById", "tags": [ "Automations" ], "summary": "Delete an emitter", "description": "Deletes an owned emitter (requires confirm_delete). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "emitter deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "confirm_delete": true } } } } } }, "/api/v1/emitters/summary": { "post": { "operationId": "postEmittersSummary", "tags": [ "Automations" ], "summary": "Filtered emitter summaries", "description": "Public automation leaderboard (same as the app ranking page): platform automations and active public marketplace listings, never other users' private emitters, strategy params redacted. Optional JSON body: limit (default 50, max 100), offset, sortBy (default ranking), sortDir, roiWindow (7d/30d/90d), symbol, exchange, category, marketType, status, recentActivity7d, day_trade_mode, marketplaceOnly. Response is { items, total, limit, offset }. This is a read.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 1001, "name": "Desk BTC emitter", "status": "running" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Default 50, max 100.", "example": 20 }, "offset": { "type": "integer", "minimum": 0, "description": "Items to skip. Default 0. Use with total from the previous page.", "example": 0 }, "sortBy": { "type": "string", "description": "Sort field (e.g. pnl).", "example": "pnl" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" }, "symbol": { "type": "string", "example": "BTC" }, "exchange": { "type": "string", "example": "hyperliquid" }, "status": { "type": "string", "description": "running, stopped, or omit for all.", "example": "running" }, "tradingMode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "marketType": { "type": "string" }, "category": { "type": "string" }, "nameQuery": { "type": "string", "description": "Case-insensitive name search." }, "day_trade_mode": { "type": "boolean" }, "enabled_rule": { "type": "string", "description": "Only rows with this strategy rule enabled." } } }, "example": { "limit": 20, "offset": 0, "sortBy": "pnl", "sortDir": "desc", "status": "running", "tradingMode": "paper", "exchange": "hyperliquid", "symbol": "BTC" } } } } } }, "/api/v1/emitters/summary/{id}": { "get": { "operationId": "getEmittersSummaryById", "tags": [ "Automations" ], "summary": "Emitter summary by id", "description": "Returns a compact summary card for one emitter.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 1001, "name": "Desk BTC emitter", "status": "running" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/emitters/curated": { "get": { "operationId": "getEmittersCurated", "tags": [ "Automations" ], "summary": "Curated emitters", "description": "Lists featured public emitters available to follow.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 1001, "name": "Desk BTC emitter" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/emitters/{id}/pnl-series": { "get": { "operationId": "getEmittersPnlseriesById", "tags": [ "Automations" ], "summary": "Emitter PnL series", "description": "Returns historical PnL points for an emitter.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "timestamp": 1711929600, "open_pnl": 8.25, "closed_pnl": 4.0, "total_pnl": 12.25 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/emitters/{id}/position": { "get": { "operationId": "getEmittersPositionById", "tags": [ "Automations" ], "summary": "Emitter position", "description": "Returns the current position for an emitter.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "symbol": "BTC", "exchange": "hyperliquid", "side": "Long", "quantity": 0.01, "unrealized_pnl": 12.5 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/portfolios": { "get": { "operationId": "getPortfolios", "tags": [ "Automations" ], "summary": "List portfolios", "description": "Lists portfolios the key owner can access.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 3, "name": "Paper desk", "status": "stopped", "trading_mode": "paper" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "post": { "operationId": "postPortfolios", "tags": [ "Automations" ], "summary": "Create a portfolio", "description": "Creates a portfolio for the key owner. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "data": { "id": 3, "name": "Paper desk", "status": "stopped", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Paper desk" }, "initial_capital": { "type": "number", "minimum": 0, "example": 2000 }, "max_members": { "type": "integer", "minimum": 1, "example": 10 }, "trading_mode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper", "description": "REST defaults to paper when omitted (unlike bots, which default to live)." }, "members": { "type": "array", "description": "Optional emitter members to attach on create. member_type must be emitter (or empty).", "items": { "type": "object", "properties": { "member_type": { "type": "string", "enum": [ "emitter" ], "description": "Must be emitter (or omit). Portfolios cannot be nested." }, "member_id": { "type": "integer", "example": 1001 }, "weight": { "type": "number", "example": 1 } } } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Existing catalog lookup_keys (max 5)." } } }, "example": { "name": "Paper desk", "trading_mode": "paper", "initial_capital": 2000, "max_members": 10, "members": [ { "member_type": "emitter", "member_id": 1001, "weight": 1 }, { "member_type": "emitter", "member_id": 1002, "weight": 1 } ] } } } } } }, "/api/v1/portfolios/{id}": { "get": { "operationId": "getPortfoliosById", "tags": [ "Automations" ], "summary": "Get a portfolio", "description": "Returns one portfolio by id, if the key owner can access it.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 3, "name": "Paper desk", "status": "stopped", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "patch": { "operationId": "patchPortfoliosById", "tags": [ "Automations" ], "summary": "Update a portfolio", "description": "Partial update of an owned portfolio. The portfolio must be stopped. Omit fields you do not want to change. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 3, "name": "Paper desk", "status": "stopped", "trading_mode": "paper" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "name": "Paper desk" } } } } }, "delete": { "operationId": "deletePortfoliosById", "tags": [ "Automations" ], "summary": "Delete a portfolio", "description": "Deletes an owned portfolio (requires confirm_delete). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "portfolio deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "confirm_delete": true } } } } } }, "/api/v1/portfolios/summary": { "post": { "operationId": "postPortfoliosSummary", "tags": [ "Automations" ], "summary": "Filtered portfolio summaries", "description": "Returns filtered portfolio summaries. Optional JSON body: limit (default 50, max 100), offset, tradingMode, status, nameQuery. Response is { items, total, limit, offset }. This is a read.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 3, "name": "Paper desk", "status": "stopped" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Default 50, max 100.", "example": 20 }, "offset": { "type": "integer", "minimum": 0, "description": "Items to skip. Default 0. Use with total from the previous page.", "example": 0 }, "sortBy": { "type": "string", "description": "Sort field (e.g. pnl).", "example": "pnl" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" }, "tradingMode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "status": { "type": "string", "example": "running" }, "nameQuery": { "type": "string" } } }, "example": { "limit": 20, "offset": 0, "sortBy": "pnl", "sortDir": "desc", "status": "running", "tradingMode": "paper" } } } } } }, "/api/v1/portfolios/{id}/pnl-series": { "get": { "operationId": "getPortfoliosPnlseriesById", "tags": [ "Automations" ], "summary": "Portfolio PnL series", "description": "Returns historical PnL points for a portfolio.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "timestamp": 1711929600, "open_pnl": 8.25, "closed_pnl": 4.0, "total_pnl": 12.25 } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/portfolios/{id}/positions": { "get": { "operationId": "getPortfoliosPositionsById", "tags": [ "Automations" ], "summary": "Portfolio positions", "description": "Returns current positions held by a portfolio's members.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "symbol": "BTC", "exchange": "hyperliquid", "side": "Long", "quantity": 0.01, "unrealized_pnl": 12.5 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/orders": { "get": { "operationId": "getOrders", "tags": [ "Orders" ], "summary": "Orders for a follower or bot", "description": "Lists order history for one follower or one bot. Pass follower_id or bot_id, not both.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "follower_id", "in": "query", "schema": { "type": "integer" }, "description": "Required unless bot_id is set." }, { "name": "bot_id", "in": "query", "schema": { "type": "integer" }, "description": "Required unless follower_id is set." }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 9001, "side": "buy", "quantity": 0.01, "status": "filled", "symbol": "BTC", "exchange": "hyperliquid" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/signals": { "get": { "operationId": "getSignals", "tags": [ "Signals" ], "summary": "Signals for an emitter", "description": "Lists signal history for one emitter. emitter_id is required.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:signals" ], "x-dogabot-write": false, "parameters": [ { "name": "emitter_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 501, "side": "buy", "symbol": "BTC", "created_at": "2026-04-01T12:00:00Z" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/quota": { "get": { "operationId": "getBacktestQuota", "tags": [ "Backtests" ], "summary": "Backtest quota", "description": "Returns remaining backtest quota and in-flight limits for the key owner.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "used": 3, "base_limit": 20, "base_remaining": 17, "purchased_balance": 0, "remaining": 17, "limit": 17 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtests": { "get": { "operationId": "getBacktests", "tags": [ "Backtests" ], "summary": "List backtests", "description": "Lists backtest jobs the key owner can access.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "items": [ { "id": "bt-1a2b3c4d", "name": "BTC 1h sample", "status": "completed" } ], "total": 1, "limit": 20, "offset": 0 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtests/summary": { "get": { "operationId": "getBacktestsSummary", "tags": [ "Backtests" ], "summary": "Summarize a backtest batch", "description": "Ranks jobs in a bulk backtest batch (best per symbol by default) with compact metrics, robustness gates, and app URLs.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [ { "name": "batch_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "schema": { "type": "string" }, "description": "symbol (default), exchange, timeframe, or none." }, { "name": "rank_by", "in": "query", "schema": { "type": "string" }, "description": "quality (default), roi, sharpe, sortino, or calmar." }, { "name": "top_n", "in": "query", "schema": { "type": "integer" }, "description": "Completed jobs kept per group after the winner (default 3, max 8)." }, { "name": "max_drawdown", "in": "query", "schema": { "type": "number" }, "description": "Drop completed jobs with max_drawdown above this fraction." }, { "name": "require_gates", "in": "query", "schema": { "type": "string" }, "description": "pass drops completed jobs that fail a robustness gate (warnings still rank)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "batch_id": "cde2a214-8827-4651-9f98-52f0221ff666", "group_by": "symbol", "rank_by": "quality", "top_n": 3, "total": 2, "groups": [ { "key": "BTCUSDT", "completed": 1, "best": { "id": "bt-1a2b3c4d", "name": "BTC 1h sample", "roi": 0.42, "max_drawdown": 0.08, "url": "https://app.dogabot.com/backtest/bt-1a2b3c4d" }, "why": "BTC 1h sample ranked first by quality" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/community-examples": { "get": { "operationId": "getBacktestCommunityexamples", "tags": [ "Backtests" ], "summary": "List Community examples", "description": "Lists public Community examples (shared completed backtests) with the same filter axes as list backtests.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": "bt-1a2b3c4d", "name": "Shared RSI BTC", "status": "completed", "roi": 0.12, "community_example": { "id": "ce-uuid", "job_id": "bt-1a2b3c4d", "title": "Shared RSI BTC", "visibility": "public", "is_active": true } } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/{job_id}": { "get": { "operationId": "getBacktestByJob_id", "tags": [ "Backtests" ], "summary": "Get a backtest job", "description": "Returns one backtest job, including status and summary metrics. While enqueued: queue_ahead / queue_position. While running: progress_pct (0\u2013100) and progress_phase (fetching|simulating) when a gateway worker reports them. Owners always; others when the job is an active Community example (public or unlisted).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bt-1a2b3c4d" }, "example": "bt-1a2b3c4d" }, { "name": "view", "in": "query", "schema": { "type": "string" }, "description": "summary for compact metrics; omit for the full payload." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "job_id": "bt-1a2b3c4d", "batch_id": "cde2a214-8827-4651-9f98-52f0221ff666", "name": "BTC 1h sample", "symbol": "BTC", "exchange": "hyperliquid", "status": "completed", "candle_timeframe": "1h" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/{job_id}/signals": { "get": { "operationId": "getBacktestSignalsByJob_id", "tags": [ "Backtests" ], "summary": "Backtest trade history / signals", "description": "Returns trades for a backtest. Full history is kept briefly, then only recent trades.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bt-1a2b3c4d" }, "example": "bt-1a2b3c4d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": 501, "side": "buy", "symbol": "BTC", "created_at": "2026-04-01T12:00:00Z" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/bulk/seed": { "get": { "operationId": "getBacktestBulkSeed", "tags": [ "Backtests" ], "summary": "Seed a bulk sweep from a source", "description": "Returns a bulk backtest config seeded from an automation or backtest you own. Every sweep axis starts with the source's current value; add values before posting it to /backtest/bulk. Requires the bulk backtest feature.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [ { "name": "automation_type", "in": "query", "schema": { "type": "string" }, "description": "bot, emitter, or follower. Use with automation_id." }, { "name": "automation_id", "in": "query", "schema": { "type": "integer" } }, { "name": "backtest_id", "in": "query", "schema": { "type": "string" }, "description": "Seed from a backtest job instead of an automation." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "config": { "name": "Sweep: BTC paper bot", "run": false, "template": { "exchange": "hyperliquid", "candle_timeframe": "1h", "execution_interval": 3600000, "start_time": 1711929600000, "end_time": 1714521600000, "initial_capital": 10000, "params": { "entry": { "combinationMode": "all_agree", "agreementThreshold": 1, "rules": { "rsi": { "enabled": true, "invert": false, "params": { "period": 14, "oversold": 30, "overbought": 70 } } } }, "exit": { "combinationMode": "all_agree", "rules": {} }, "increase": { "combinationMode": "all_agree", "rules": {} }, "reversal": { "combinationMode": "all_agree", "rules": {} } } }, "symbols": [ "BTC" ], "candle_timeframes": [ "1h" ], "param_ranges": [ { "param_key": "entry.rules.rsi.0.params.period", "values": [ 14, 21 ] } ] }, "source": { "kind": "automation", "type": "bot", "id": "42", "name": "BTC paper bot" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/bulk/batches": { "get": { "operationId": "getBacktestBulkBatches", "tags": [ "Backtests" ], "summary": "List bulk backtest batches", "description": "Lists bulk backtest batches with job progress. Requires the bulk backtest feature.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "include_summary", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": "cde2a214-8827-4651-9f98-52f0221ff666", "name": "BTC RSI sweep", "status": "running", "total_jobs": 8, "queued_jobs": 8, "completed_jobs": 3, "failed_jobs": 0 } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/bulk/batches/{batch_id}": { "get": { "operationId": "getBacktestBulkBatchesByBatch_id", "tags": [ "Backtests" ], "summary": "Get a bulk backtest batch", "description": "Returns one bulk backtest batch: status, progress, saved config, and performance summary once completed.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:backtests" ], "x-dogabot-write": false, "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include_performance_summary", "in": "query", "schema": { "type": "boolean" } }, { "name": "include_job_ids", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "cde2a214-8827-4651-9f98-52f0221ff666", "name": "BTC RSI sweep", "status": "running", "total_jobs": 8, "queued_jobs": 8, "completed_jobs": 3, "failed_jobs": 0, "config": { "name": "BTC RSI sweep", "run": false, "template": { "exchange": "hyperliquid", "candle_timeframe": "1h", "execution_interval": 3600000, "start_time": 1711929600000, "end_time": 1714521600000, "initial_capital": 10000, "params": { "entry": { "combinationMode": "all_agree", "agreementThreshold": 1, "rules": { "rsi": { "enabled": true, "invert": false, "params": { "period": 14, "oversold": 30, "overbought": 70 } } } }, "exit": { "combinationMode": "all_agree", "rules": {} }, "increase": { "combinationMode": "all_agree", "rules": {} }, "reversal": { "combinationMode": "all_agree", "rules": {} } } }, "symbols": [ "BTC", "ETH" ], "candle_timeframes": [ "1h", "4h" ], "param_ranges": [ { "param_key": "entry.rules.rsi.0.params.period", "values": [ 14, 21 ] } ] }, "job_ids": [] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/ticker": { "get": { "operationId": "getTicker", "tags": [ "Markets" ], "summary": "Latest ticker", "description": "Returns the latest ticker for an exchange and symbol.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string", "example": "hyperliquid" }, "description": "Venue code, e.g. binance_spot or hyperliquid.", "example": "hyperliquid" }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol, e.g. BTC or BTCUSDT.", "example": "BTC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "symbol": "BTC", "price": "68450.5", "change_24h": "1.2", "volume_24h": "1200000", "exchange": "hyperliquid", "market_type": "perpetual" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/funding-rate": { "get": { "operationId": "getFundingrate", "tags": [ "Markets" ], "summary": "Latest perpetual funding rate", "description": "Returns the latest perpetual funding rate when the venue supports it.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string", "example": "hyperliquid" }, "description": "Venue code, e.g. binance_spot or hyperliquid.", "example": "hyperliquid" }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol, e.g. BTC or BTCUSDT.", "example": "BTC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "exchange": "hyperliquid", "symbol": "BTC", "supported": true, "rate": 0.0001, "period_hours": 8 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/market/orderbook": { "get": { "operationId": "getMarketOrderbook", "tags": [ "Markets" ], "summary": "Order book snapshot", "description": "Returns a short-lived public order book snapshot.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string", "example": "hyperliquid" }, "description": "Venue code, e.g. binance_spot or hyperliquid.", "example": "hyperliquid" }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol, e.g. BTC or BTCUSDT.", "example": "BTC" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Depth per side (default 20)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "bids": [ [ "68450.0", "1.2" ] ], "asks": [ [ "68451.0", "0.8" ] ], "exchange": "hyperliquid", "symbol": "BTC" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/market/trades": { "get": { "operationId": "getMarketTrades", "tags": [ "Markets" ], "summary": "Public trades tape", "description": "Returns recent public trades for an exchange and symbol.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string", "example": "hyperliquid" }, "description": "Venue code, e.g. binance_spot or hyperliquid.", "example": "hyperliquid" }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol, e.g. BTC or BTCUSDT.", "example": "BTC" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Trade tape length (default 50)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "price": "68450.5", "quantity": 0.01, "side": "buy", "time": "2026-04-01T12:00:00Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/markets": { "get": { "operationId": "getMarkets", "tags": [ "Markets" ], "summary": "List markets", "description": "Lists markets, with optional filters and pagination.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "query", "schema": { "type": "integer" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "exchange_id", "in": "query", "schema": { "type": "integer" } }, { "name": "is_tradable", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_backtestable", "in": "query", "schema": { "type": "boolean" } }, { "name": "market_kind", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "schema": { "type": "string" }, "description": "volume (live 24h volume across all matches) or a market field." }, { "name": "sortDir", "in": "query", "schema": { "type": "string" }, "description": "asc or desc." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 1, "code": "BTC", "exchange_id": 1, "exchange_name": "hyperliquid", "is_tradable": true, "is_backtestable": true, "instrument_tags": [ "crypto" ], "logo_url": "https://s2.coinmarketcap.com/static/img/coins/64x64/1.png" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/markets/asset-profile": { "get": { "operationId": "getMarketsAssetprofile", "tags": [ "Markets" ], "summary": "Asset profile encyclopedia", "description": "Returns encyclopedia-style asset profile metadata for a base asset (name, description, links).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string", "example": "hyperliquid" }, "description": "Venue code, e.g. binance_spot or hyperliquid.", "example": "hyperliquid" }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol, e.g. BTC or BTCUSDT.", "example": "BTC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "base": "BTC", "name": "Bitcoin", "provider": "cmc", "description": "Bitcoin is a peer-to-peer digital currency.", "logo_url": "https://s2.coinmarketcap.com/static/img/coins/64x64/1.png", "tags": [ "mineable", "store-of-value" ], "links": { "website": "https://bitcoin.org/" }, "cmc_rank": 1, "market_cap_usd": 1500000000000 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchanges": { "get": { "operationId": "getExchanges", "tags": [ "Terminal" ], "summary": "List exchanges", "description": "Lists supported exchanges.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "code": "hyperliquid", "name": "Hyperliquid", "status": "active" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/market-types": { "get": { "operationId": "getMarkettypes", "tags": [ "Markets" ], "summary": "List market types", "description": "Lists market type labels used in filters (spot, perpetual, and similar).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 1, "name": "perpetual" }, { "id": 2, "name": "spot" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/marketplace/search": { "get": { "operationId": "getMarketplaceSearch", "tags": [ "Markets" ], "summary": "Search marketplace listings", "description": "Searches public marketplace listings.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Default 20, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": "lst_1", "title": "Desk BTC emitter", "handle": "desk" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/marketplace/sellers/{handle}": { "get": { "operationId": "getMarketplaceSellersByHandle", "tags": [ "Markets" ], "summary": "Marketplace seller by handle", "description": "Returns a public marketplace seller profile by handle.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string", "example": "desk" }, "example": "desk" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "handle": "desk", "display_name": "Desk", "listing_count": 3 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/datafeed/history": { "get": { "operationId": "getDatafeedHistory", "tags": [ "Markets" ], "summary": "OHLCV candles", "description": "Returns OHLCV candles for an exchange and symbol.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "schema": { "type": "string" }, "description": "Candle interval (e.g. 60, 1h)." }, { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Unix seconds." }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "Unix seconds." }, { "name": "countback", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "s": "ok", "t": [ 1711929600 ], "o": [ 67000.0 ], "h": [ 68500.0 ], "l": [ 66800.0 ], "c": [ 68450.5 ], "v": [ 120.5 ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/markets/symbol-correlation": { "post": { "operationId": "postMarketsSymbolcorrelation", "tags": [ "Markets" ], "summary": "Symbol return correlation", "description": "Returns Pearson correlation for daily buy-and-hold returns across symbols.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "symbols": [ "BTC", "ETH", "SOL" ], "matrix": [ [ 1.0, 0.72, 0.55 ], [ 0.72, 1.0, 0.61 ], [ 0.55, 0.61, 1.0 ] ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "symbols": [ "BTC", "ETH", "SOL" ], "exchange": "binance_usdm" } } } } } }, "/api/v1/markets/symbol-volatility": { "post": { "operationId": "postMarketsSymbolvolatility", "tags": [ "Markets" ], "summary": "Symbol return volatility", "description": "Returns sample std of daily simple returns for explicit markets over 7d/30d/90d/365d windows (plus annualized \u00d7\u221a365).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "items": [ { "key": "binance:BTCUSDT", "exchange": "binance", "symbol": "BTCUSDT", "windows": { "7d": { "daily_std": 0.021, "annualized_std": 0.401, "returns_used": 7, "start_timestamp": 1719792000, "end_timestamp": 1720396800 } } } ], "windows_requested": [ "7d", "30d", "90d", "365d" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "symbols": [ { "exchange": "binance", "symbol": "BTCUSDT" }, { "exchange": "binance", "symbol": "ETHUSDT" } ], "windows": [ "7d", "30d", "90d", "365d" ] } } } } } }, "/api/v1/markets/symbol-fee-breakeven": { "post": { "operationId": "postMarketsSymbolfeebreakeven", "tags": [ "Markets" ], "summary": "Symbol fee breakeven", "description": "Returns the minimum price move for a round-trip to break even after entry+exit trading fees. Always includes both maker and taker same-role scenarios.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "items": [ { "key": "binance_usdm:BTCUSDT", "exchange": "binance_usdm", "symbol": "BTCUSDT", "maker_fee": 0.0002, "taker_fee": 0.0005, "maker": { "fee_sum_frac": 0.0004, "min_move_frac": 0.00040008, "min_move_pct": 0.040008 }, "taker": { "fee_sum_frac": 0.001, "min_move_frac": 0.0010005, "min_move_pct": 0.10005 }, "assumptions": [ "public_market_fees", "no_spread", "no_funding", "no_vip", "round_trip_same_role" ] } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "symbols": [ { "exchange": "binance_usdm", "symbol": "BTCUSDT" } ] } } } } } }, "/api/v1/terminal/orders": { "get": { "operationId": "getTerminalOrders", "tags": [ "Terminal" ], "summary": "Terminal orders", "description": "Lists the key owner's terminal orders. Filter by venue, symbol, paper/live, or client_order_id.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "schema": { "type": "string" } }, { "name": "trading_mode", "in": "query", "schema": { "type": "string" }, "description": "live or paper." }, { "name": "client_order_id", "in": "query", "schema": { "type": "string" } }, { "name": "side", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string" } }, { "name": "sort_dir", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "client_order_id": "dogabot-t1a2b3c4", "exchange": "hyperliquid", "symbol": "BTC", "side": "buy", "quantity": 0.001, "status": "filled", "trading_mode": "paper" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/terminal/orders/by-client-order-id/{client_order_id}": { "get": { "operationId": "getTerminalOrdersByclientorderidByClient_order_id", "tags": [ "Terminal" ], "summary": "Terminal order by client_order_id", "description": "Returns one terminal order by the client_order_id from place-order.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "client_order_id", "in": "path", "required": true, "schema": { "type": "string", "example": "dogabot-t1a2b3c4" }, "example": "dogabot-t1a2b3c4" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "client_order_id": "dogabot-t1a2b3c4", "exchange": "hyperliquid", "symbol": "BTC", "side": "buy", "quantity": 0.001, "status": "filled", "trading_mode": "paper" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/terminal/positions": { "get": { "operationId": "getTerminalPositions", "tags": [ "Terminal" ], "summary": "Terminal positions", "description": "Lists the key owner's terminal positions (paper or live).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "trading_mode", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "symbol": "BTC", "exchange": "hyperliquid", "side": "Long", "quantity": 0.01, "unrealized_pnl": 12.5 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/terminal/symbol-rules": { "get": { "operationId": "getTerminalSymbolrules", "tags": [ "Terminal" ], "summary": "Min notional, lot size, and quantity rules", "description": "Returns lot size, min quantity, and min notional for a venue symbol. Use this before place-order.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string", "example": "hyperliquid" }, "description": "Venue code, e.g. binance_spot or hyperliquid.", "example": "hyperliquid" }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol, e.g. BTC or BTCUSDT.", "example": "BTC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "min_notional": 10, "lot_size": 0.001, "base_min_quantity": 0.001, "min_quantity": 0.001, "quantity_precision": 3, "tick_size": 0.1, "price_precision": 1 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/terminal/order-capabilities": { "get": { "operationId": "getTerminalOrdercapabilities", "tags": [ "Terminal" ], "summary": "Venue-native order capabilities", "description": "Returns venue-native order capabilities (stops, brackets, post-only) for a symbol.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:markets" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string", "example": "hyperliquid" }, "description": "Venue code, e.g. binance_spot or hyperliquid.", "example": "hyperliquid" }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol, e.g. BTC or BTCUSDT.", "example": "BTC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "exchange": "aster_dex", "symbol": "BTC", "supports_stop": true, "supports_bracket": true, "supports_post_only": true } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/balances": { "get": { "operationId": "getExchangeBalances", "tags": [ "Terminal" ], "summary": "Live exchange wallet snapshot", "description": "Returns a live wallet snapshot from the connected exchange. Not automation or terminal positions.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "include_zero", "in": "query", "schema": { "type": "string" }, "description": "1 or true to include zero balances." }, { "name": "asset", "in": "query", "schema": { "type": "string" }, "description": "Filter to one asset code, e.g. USDT." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "exchange": "hyperliquid", "assets": [ { "asset": "USDT", "free": 2500.0, "used": 0.0, "total": 2500.0 } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/positions": { "get": { "operationId": "getExchangePositions", "tags": [ "Terminal" ], "summary": "Live exchange positions", "description": "Lists live venue futures/perp contracts for a connected exchange (spot returns empty).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "symbol": "BTC", "exchange": "hyperliquid", "side": "Long", "quantity": 0.01, "unrealized_pnl": 12.5 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/margin-summary": { "get": { "operationId": "getExchangeMarginsummary", "tags": [ "Terminal" ], "summary": "Live futures margin summary", "description": "Returns a live futures margin summary and liquidation-distance aggregates.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "exchange": "binance_usdm", "equity": 2500.0, "available": 1800.0, "used_margin": 700.0 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/orders": { "get": { "operationId": "getExchangeOrders", "tags": [ "Terminal" ], "summary": "Live exchange orders", "description": "Lists live venue open plus recent filled/canceled orders.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "open, filled, canceled, or omit." }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "client_order_id": "dogabot-t1a2b3c4", "exchange": "hyperliquid", "symbol": "BTC", "side": "buy", "quantity": 0.001, "status": "filled", "trading_mode": "paper" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/trades": { "get": { "operationId": "getExchangeTrades", "tags": [ "Terminal" ], "summary": "Live exchange trades", "description": "Lists live venue fills (paginated).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": "t1", "symbol": "BTC", "side": "buy", "quantity": 0.001, "price": 68450.5 } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/income": { "get": { "operationId": "getExchangeIncome", "tags": [ "Terminal" ], "summary": "Live exchange income history", "description": "Lists live venue income/cashflow history.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "type": "realized_pnl", "asset": "USDT", "amount": 12.5, "time": "2026-04-01T12:00:00Z" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/openable-notional": { "get": { "operationId": "getExchangeOpenablenotional", "tags": [ "Terminal" ], "summary": "Remaining openable notional", "description": "Returns remaining openable notional (USDT) for a symbol at a leverage on Aster.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "leverage", "in": "query", "schema": { "type": "integer" }, "description": "1\u2013125; omit to use venue leverage from positionRisk." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "exchange": "aster_dex", "symbol": "BZUSDT", "leverage": 50, "remaining_openable_notional_value": 0 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/leverage-capabilities": { "get": { "operationId": "getExchangeLeveragecapabilities", "tags": [ "Terminal" ], "summary": "Leverage and margin-mode capabilities", "description": "Static per-venue matrix of set-leverage and set-margin-mode support (no venue call).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:orders" ], "x-dogabot-write": false, "parameters": [ { "name": "exchange", "in": "query", "schema": { "type": "string" }, "description": "Venue id (e.g. bybit_linear). Omit to list every supported perp venue." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "exchange": "bybit_linear", "set_leverage": true, "set_margin_mode": true, "margin_mode_scope": "account", "openable_notional": false, "notes": "UTA 2.0 account-wide margin mode (REGULAR_MARGIN / ISOLATED_MARGIN); applies to the whole account, not one symbol." } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/exchange/leverage": { "post": { "operationId": "postExchangeLeverage", "tags": [ "Terminal" ], "summary": "Set exchange leverage", "description": "Changes initial futures leverage for a symbol on supported perp venues; optional margin_mode (crossed|isolated). Requires confirm_live=true. Requires write:terminal on the key and feat:terminal on the account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:terminal" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "exchange": "aster_dex", "symbol": "BZUSDT", "leverage": 3, "max_notional_value": 5000, "margin_mode": "isolated" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "exchange", "symbol", "leverage", "confirm_live" ], "properties": { "exchange": { "type": "string" }, "symbol": { "type": "string" }, "leverage": { "type": "integer", "minimum": 1, "maximum": 125 }, "margin_mode": { "type": "string", "enum": [ "crossed", "cross", "isolated" ], "description": "Optional margin mode applied with the leverage change." }, "confirm_live": { "type": "boolean" } } }, "example": { "exchange": "aster_dex", "symbol": "BZUSDT", "leverage": 3, "margin_mode": "isolated", "confirm_live": true } } } } } }, "/api/v1/exchange/margin-mode": { "post": { "operationId": "postExchangeMarginmode", "tags": [ "Terminal" ], "summary": "Set exchange margin mode", "description": "Switches cross/isolated margin for a symbol. Response scope says whether the venue applied it per symbol, account-wide, or combined with leverage. Requires confirm_live=true. Requires write:terminal on the key and feat:terminal on the account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:terminal" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "exchange": "binance_usdm", "symbol": "BTCUSDT", "margin_mode": "isolated", "scope": "symbol" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "exchange", "symbol", "margin_mode", "confirm_live" ], "properties": { "exchange": { "type": "string" }, "symbol": { "type": "string" }, "margin_mode": { "type": "string", "enum": [ "crossed", "cross", "isolated" ] }, "leverage": { "type": "integer", "minimum": 1, "maximum": 125, "description": "Required on kraken_futures, hyperliquid and lighter when it cannot be resolved from the venue position." }, "confirm_live": { "type": "boolean" } } }, "example": { "exchange": "binance_usdm", "symbol": "BTCUSDT", "margin_mode": "isolated", "confirm_live": true } } } } } }, "/api/v1/exchange/cancel-order": { "post": { "operationId": "postExchangeCancelorder", "tags": [ "Terminal" ], "summary": "Cancel one live exchange order", "description": "Cancels one live venue resting order. Requires write:terminal on the key and feat:terminal on the account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:terminal" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "status": "accepted", "order_id": "123456" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "exchange": "binance_usdm", "symbol": "BTC", "trading_mode": "paper", "order_id": "123456" } } } } } }, "/api/v1/exchange/cancel-orders": { "post": { "operationId": "postExchangeCancelorders", "tags": [ "Terminal" ], "summary": "Bulk-cancel live exchange orders", "description": "Bulk-cancels live venue resting orders. Requires write:terminal on the key and feat:terminal on the account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:terminal" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "status": "accepted", "canceled": 3 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "exchange": "binance_usdm", "symbol": "BTC", "trading_mode": "paper", "cancel_open": true } } } } } }, "/api/v1/credentials": { "get": { "operationId": "getCredentials", "tags": [ "Credentials" ], "summary": "List exchange credentials (masked)", "description": "Lists exchange credentials (masked api_key only; secrets never returned).", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:credentials" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 7, "name": "Binance paper", "exchange": "binance_usdm", "api_key": "abcd\u2026wxyz", "is_default": true } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "post": { "operationId": "postCredentials", "tags": [ "Credentials" ], "summary": "Create an exchange credential", "description": "Creates an exchange credential. Secrets are write-only. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:credentials" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "data": { "id": 7, "name": "Binance paper", "exchange": "binance_usdm", "api_key": "abcd\u2026wxyz", "is_default": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "name": "Binance paper", "exchange": "binance_usdm", "api_key": "REPLACE_ME", "secret_key": "REPLACE_ME" } } } } } }, "/api/v1/tags": { "get": { "operationId": "getTags", "tags": [ "Automations" ], "summary": "List automation tags", "description": "Lists automation tags for the key owner.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:automations" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 3, "lookup_key": "high-conviction", "description": "Priority strategies" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "post": { "operationId": "postTags", "tags": [ "Automations" ], "summary": "Create an automation tag", "description": "Creates an automation tag. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "data": { "id": 3, "lookup_key": "high-conviction", "description": "Priority strategies" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "lookup_key": "high-conviction", "description": "Priority strategies" } } } } } }, "/api/v1/me/statistics/by-tag": { "get": { "operationId": "getMeStatisticsBytag", "tags": [ "Account" ], "summary": "Account statistics by tag", "description": "Returns aggregated statistics grouped by automation tag.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "read:account" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "tag": "high-conviction", "running_count": 1, "total_volume": 50000 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/followers/{id}/start": { "post": { "operationId": "postFollowersStartById", "tags": [ "Automations" ], "summary": "Start a follower", "description": "Starts an owned follower. REST-only; not available as an MCP tool. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "start-follower-42" }, "description": "Unique key per mutation so retries stay safe.", "example": "start-follower-42" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "follower 42 starting" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/followers/{id}/stop": { "post": { "operationId": "postFollowersStopById", "tags": [ "Automations" ], "summary": "Stop a follower", "description": "Stops an owned follower. REST-only; not available as an MCP tool. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "follower 42 stopping" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/bots/{id}/start": { "post": { "operationId": "postBotsStartById", "tags": [ "Automations" ], "summary": "Start a bot", "description": "Starts an owned bot. REST-only; not available as an MCP tool. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "bot 7 starting" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/bots/{id}/stop": { "post": { "operationId": "postBotsStopById", "tags": [ "Automations" ], "summary": "Stop a bot", "description": "Stops an owned bot. REST-only; not available as an MCP tool. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "bot 7 stopping" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/bots/{id}/books": { "post": { "operationId": "postBotsBooksById", "tags": [ "Automations" ], "summary": "Set a bot book leg", "description": "Sets one bot book leg (signed position). Default book-only; optional place_on_venue. Session or MCP OAuth only \u2014 API keys are rejected. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "book_updated": true, "bot_id": 259, "exchange": "aster_dex", "symbol": "ETHUSDT", "previous_position": 0.003, "position": 0, "avg_entry_price": 0, "reason": "accounting_correction", "parks_canceled": [ { "order_id": "18294257325", "client_order_id": "dogabot-ti\u2026", "role": "increase_limit" } ], "parks_failed": [], "resync_queued": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "exchange": "aster_dex", "symbol": "ETHUSDT", "position": 0, "reason": "accounting_correction", "place_on_venue": false } } } } } }, "/api/v1/followers/{id}/books": { "post": { "operationId": "postFollowersBooksById", "tags": [ "Automations" ], "summary": "Set a follower book leg", "description": "Sets one follower book leg (signed position). Default book-only; optional place_on_venue. Session or MCP OAuth only \u2014 API keys are rejected. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "book_updated": true, "follower_id": 100, "exchange": "binance_usdm", "symbol": "BTCUSDT", "previous_position": 0.01, "position": 0, "avg_entry_price": 0, "reason": "ops_manual_flatten", "parks_canceled": [], "parks_failed": [], "resync_queued": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "exchange": "binance_usdm", "symbol": "BTCUSDT", "position": 0, "reason": "ops_manual_flatten", "place_on_venue": false } } } } } }, "/api/v1/emitters/{id}/start": { "post": { "operationId": "postEmittersStartById", "tags": [ "Automations" ], "summary": "Start an emitter", "description": "Starts an owned emitter. REST-only; not available as an MCP tool. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "emitter 1001 starting" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/emitters/{id}/stop": { "post": { "operationId": "postEmittersStopById", "tags": [ "Automations" ], "summary": "Stop an emitter", "description": "Stops an owned emitter. REST-only; not available as an MCP tool. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "emitter 1001 stopping" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/portfolios/{id}/start": { "post": { "operationId": "postPortfoliosStartById", "tags": [ "Automations" ], "summary": "Start a portfolio", "description": "Starts an owned portfolio. REST-only; not available as an MCP tool. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "status": "running" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/portfolios/{id}/stop": { "post": { "operationId": "postPortfoliosStopById", "tags": [ "Automations" ], "summary": "Stop a portfolio", "description": "Stops an owned portfolio. REST-only; not available as an MCP tool. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:lifecycle" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "status": "stopped" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/followers/{id}/tags": { "put": { "operationId": "putFollowersTagsById", "tags": [ "Automations" ], "summary": "Replace follower tags", "description": "Replaces the tag set on an owned follower. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 42, "tag_ids": [ 3 ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "tag_ids": [ 3 ] } } } } } }, "/api/v1/bots/{id}/tags": { "put": { "operationId": "putBotsTagsById", "tags": [ "Automations" ], "summary": "Replace bot tags", "description": "Replaces the tag set on an owned bot. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 7, "tag_ids": [ 3 ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "tag_ids": [ 3 ] } } } } } }, "/api/v1/emitters/{id}/tags": { "put": { "operationId": "putEmittersTagsById", "tags": [ "Automations" ], "summary": "Replace emitter tags", "description": "Replaces the tag set on an owned emitter. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 1001, "tag_ids": [ 3 ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "tag_ids": [ 3 ] } } } } } }, "/api/v1/portfolios/{id}/tags": { "put": { "operationId": "putPortfoliosTagsById", "tags": [ "Automations" ], "summary": "Replace portfolio tags", "description": "Replaces the tag set on an owned portfolio. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 3, "tag_ids": [ 3 ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "tag_ids": [ 3 ] } } } } } }, "/api/v1/tags/{id}": { "patch": { "operationId": "patchTagsById", "tags": [ "Automations" ], "summary": "Update an automation tag", "description": "Updates a tag lookup_key and/or description. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 3, "lookup_key": "high-conviction", "description": "Updated description" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "description": "Updated description" } } } } }, "delete": { "operationId": "deleteTagsById", "tags": [ "Automations" ], "summary": "Delete an automation tag", "description": "Deletes a tag (requires confirm_delete). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:automation" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "tag deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "confirm_delete": true } } } } } }, "/api/v1/credentials/{id}": { "put": { "operationId": "putCredentialsById", "tags": [ "Credentials" ], "summary": "Update or rotate a credential", "description": "Updates credential name and/or rotates keys. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:credentials" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 7, "name": "Binance paper (rotated)", "exchange": "binance_usdm", "api_key": "abcd\u2026wxyz" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "name": "Binance paper (rotated)" } } } } }, "delete": { "operationId": "deleteCredentialsById", "tags": [ "Credentials" ], "summary": "Delete an exchange credential", "description": "Deletes an exchange credential (requires confirm_delete). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:credentials" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "credential deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "confirm_delete": true } } } } } }, "/api/v1/credentials/{id}/default": { "post": { "operationId": "postCredentialsDefaultById", "tags": [ "Credentials" ], "summary": "Set default credential for exchange", "description": "Marks a credential as default for its exchange. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:credentials" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 7, "is_default": true } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest": { "post": { "operationId": "postBacktest", "tags": [ "Backtests" ], "summary": "Create a backtest", "description": "Enqueues a backtest. Check quota first; a limited number may run at once. start_time and end_time are unix milliseconds; execution_interval is milliseconds. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:backtest" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "job_id": "bt-1a2b3c4d" }, "message": "backtest enqueued" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "symbol", "exchange", "candle_timeframe", "execution_interval", "start_time", "end_time" ], "properties": { "name": { "type": "string", "maxLength": 200, "example": "BTC 1h sample" }, "symbol": { "type": "string", "example": "BTC" }, "exchange": { "type": "string", "example": "hyperliquid" }, "candle_timeframe": { "type": "string", "description": "Candle size, e.g. 1h or 60.", "example": "1h" }, "execution_interval": { "type": "integer", "description": "Strategy tick in milliseconds (must be compatible with candle_timeframe).", "example": 3600000 }, "start_time": { "type": "integer", "description": "Range start, unix milliseconds.", "example": 1711929600000 }, "end_time": { "type": "integer", "description": "Range end, unix milliseconds. Must be after start_time.", "example": 1714521600000 }, "initial_capital": { "type": "number", "minimum": 0, "example": 10000 }, "markets": { "type": "array", "description": "Optional multi-leg markets. When omitted, a single primary leg is built from exchange/symbol.", "items": { "type": "object", "additionalProperties": true } }, "params": { "type": "object", "additionalProperties": true, "description": "Strategy params in the webapp / backtest save shape. Needs entry.rules (and usually exit/increase/reversal sections) for validation. Named-rule wire shapes: https://docs.dogabot.com/rules/ (JSON: /rule-examples.json). Ask AI / customLogic recipes: https://docs.dogabot.com/recipes/ (JSON: /recipe-examples.json)." } } }, "example": { "name": "BTC 1h sample", "symbol": "BTC", "exchange": "hyperliquid", "candle_timeframe": "1h", "execution_interval": 3600000, "start_time": 1711929600000, "end_time": 1714521600000, "initial_capital": 10000, "params": { "entry": { "combinationMode": "all_agree", "agreementThreshold": 1, "rules": { "rsi": { "enabled": true, "invert": false, "params": { "period": 14, "oversold": 30, "overbought": 70 } } } }, "exit": { "combinationMode": "all_agree", "rules": {} }, "increase": { "combinationMode": "all_agree", "rules": {} }, "reversal": { "combinationMode": "all_agree", "rules": {} } } } } } } } }, "/api/v1/backtest/bulk": { "post": { "operationId": "postBacktestBulk", "tags": [ "Backtests" ], "summary": "Create a bulk backtest batch", "description": "Creates a bulk backtest batch: one template expanded over sweep axes (symbols, timeframes, date ranges, param_ranges, \u2026). run=false saves a draft. Requires the bulk backtest feature; each job uses quota. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:backtest" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "batch_id": "cde2a214-8827-4651-9f98-52f0221ff666", "status": "draft", "total_jobs": 8, "queued_jobs": 0, "created": [], "failed": [] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Bulk backtest batch: one template expanded over Cartesian sweep axes. run=false saves a draft without enqueueing. Requires feat:backtest:bulk_create. When template.markets has multiple legs (pairs/hedges), symbols and exchanges axes do not apply.", "required": [ "name", "template" ], "properties": { "name": { "type": "string", "example": "BTC RSI sweep" }, "batch_id": { "type": "string", "description": "Optional client-supplied batch id (UUID)." }, "run": { "type": "boolean", "description": "When false (default in examples), save a draft. When true, enqueue jobs (uses quota per cell).", "example": false }, "template": { "type": "object", "description": "Shared job template (same fields as a single backtest without name/symbol).", "required": [ "exchange", "candle_timeframe", "execution_interval", "start_time", "end_time" ], "properties": { "exchange": { "type": "string", "example": "hyperliquid" }, "markets": { "type": "array", "description": "Optional fixed multi-leg markets for every cell. Multi-leg \u21d2 symbols/exchanges axes ignored.", "items": { "type": "object", "additionalProperties": true } }, "candle_timeframe": { "type": "string", "example": "1h" }, "execution_interval": { "type": "integer", "example": 3600000 }, "start_time": { "type": "integer", "example": 1711929600000 }, "end_time": { "type": "integer", "example": 1714521600000 }, "initial_capital": { "type": "number", "minimum": 0, "example": 10000 }, "params": { "type": "object", "additionalProperties": true, "description": "Strategy params in the webapp / backtest save shape. Needs entry.rules (and usually exit/increase/reversal sections) for validation. Named-rule wire shapes: https://docs.dogabot.com/rules/ (JSON: /rule-examples.json). Ask AI / customLogic recipes: https://docs.dogabot.com/recipes/ (JSON: /recipe-examples.json)." } } }, "symbols": { "type": "array", "items": { "type": "string" }, "description": "Symbol sweep axis (single-leg templates).", "example": [ "BTC", "ETH" ] }, "name_pattern": { "type": "string", "description": "Optional name template for each cell (supports placeholders used by the bulk expander)." }, "candle_timeframes": { "type": "array", "items": { "type": "string" }, "example": [ "1h", "4h" ] }, "execution_intervals": { "type": "array", "items": { "type": "integer" }, "description": "Milliseconds; must stay compatible with each candle_timeframe cell." }, "date_ranges": { "type": "array", "items": { "type": "object", "required": [ "start_time", "end_time" ], "properties": { "start_time": { "type": "integer", "description": "Unix milliseconds.", "example": 1711929600000 }, "end_time": { "type": "integer", "description": "Unix milliseconds.", "example": 1714521600000 } } } }, "param_ranges": { "type": "array", "items": { "type": "object", "required": [ "param_key" ], "properties": { "param_key": { "type": "string", "description": "Dot path inside params. Rule instances use a numeric segment, e.g. entry.rules.rsi.0.params.period.", "example": "entry.rules.rsi.0.params.period" }, "values": { "type": "array", "items": { "type": "number" }, "description": "Explicit sweep values (preferred for discrete sets)." }, "choices": { "type": "array", "items": {}, "description": "Non-numeric sweep choices when needed." }, "start": { "type": "number", "description": "Linear range start (with until + step)." }, "until": { "type": "number", "description": "Linear range end (inclusive-style until)." }, "step": { "type": "number", "description": "Linear range step." } } } }, "initial_capital_range": { "type": "object", "required": [ "start", "until", "step" ], "properties": { "start": { "type": "number", "example": 5000 }, "until": { "type": "number", "example": 15000 }, "step": { "type": "number", "example": 5000 } } }, "exchanges": { "type": "array", "items": { "type": "string" }, "description": "Exchange sweep for single-leg templates." }, "trade_directions": { "type": "array", "items": { "type": "string" }, "description": "e.g. long, short, both." }, "day_trade_modes": { "type": "array", "items": { "type": "boolean" } }, "day_trade_close_times_utc": { "type": "array", "items": { "type": "string" }, "description": "HH:MM UTC close times when sweeping day-trade mode." }, "periodic_close_days": { "type": "array", "items": { "type": "integer" }, "description": "0 = off; 2..90 = close + cancel every N UTC days." }, "periodic_close_times_utc": { "type": "array", "items": { "type": "string" }, "description": "HH:MM UTC for periodic close when enabled." } } }, "example": { "name": "BTC RSI sweep", "run": false, "template": { "exchange": "hyperliquid", "candle_timeframe": "1h", "execution_interval": 3600000, "start_time": 1711929600000, "end_time": 1714521600000, "initial_capital": 10000, "params": { "entry": { "combinationMode": "all_agree", "agreementThreshold": 1, "rules": { "rsi": { "enabled": true, "invert": false, "params": { "period": 14, "oversold": 30, "overbought": 70 } } } }, "exit": { "combinationMode": "all_agree", "rules": {} }, "increase": { "combinationMode": "all_agree", "rules": {} }, "reversal": { "combinationMode": "all_agree", "rules": {} } } }, "symbols": [ "BTC", "ETH" ], "candle_timeframes": [ "1h", "4h" ], "param_ranges": [ { "param_key": "entry.rules.rsi.0.params.period", "values": [ 14, 21 ] } ] } } } } } }, "/api/v1/backtest/bulk/batches/{batch_id}/rerun": { "post": { "operationId": "postBacktestBulkBatchesRerunByBatch_id", "tags": [ "Backtests" ], "summary": "Re-run a bulk backtest batch", "description": "Re-runs a finished bulk batch as a new batch (uses quota per job). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:backtest" ], "x-dogabot-write": true, "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "batch_id": "0b5c1e7a-4f3d-4a8e-9c2b-1d6e7f8a9b0c", "status": "running", "total_jobs": 8, "queued_jobs": 0 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/bulk/batches/{batch_id}/cancel": { "post": { "operationId": "postBacktestBulkBatchesCancelByBatch_id", "tags": [ "Backtests" ], "summary": "Cancel a bulk backtest batch", "description": "Cancels a running bulk batch; queued and running jobs become cancelled. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:backtest" ], "x-dogabot-write": true, "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "cde2a214-8827-4651-9f98-52f0221ff666", "name": "BTC RSI sweep", "status": "cancelled", "total_jobs": 8, "queued_jobs": 8, "completed_jobs": 3, "failed_jobs": 0 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/{job_id}/cancel": { "post": { "operationId": "postBacktestCancelByJob_id", "tags": [ "Backtests" ], "summary": "Cancel a backtest", "description": "Cancels a backtest that is queued or running. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:backtest" ], "x-dogabot-write": true, "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bt-1a2b3c4d" }, "example": "bt-1a2b3c4d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "job_id": "bt-1a2b3c4d", "batch_id": "cde2a214-8827-4651-9f98-52f0221ff666", "name": "BTC 1h sample", "symbol": "BTC", "exchange": "hyperliquid", "status": "cancelled", "candle_timeframe": "1h" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/backtest/{job_id}/community-example": { "post": { "operationId": "postBacktestCommunityexampleByJob_id", "tags": [ "Backtests" ], "summary": "Publish a Community example", "description": "Publishes or updates a Community example for a completed backtest you own (title, description, visibility). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:backtest" ], "x-dogabot-write": true, "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bt-1a2b3c4d" }, "example": "bt-1a2b3c4d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "ce-uuid", "job_id": "bt-1a2b3c4d", "title": "Shared RSI BTC", "description": "Simple RSI mean-reversion on BTCUSDT 1h", "visibility": "public", "is_active": true } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "title": "Shared RSI BTC", "description": "Simple RSI mean-reversion on BTCUSDT 1h", "visibility": "public" } } } } }, "patch": { "operationId": "patchBacktestCommunityexampleByJob_id", "tags": [ "Backtests" ], "summary": "Update a Community example", "description": "Updates Community example metadata or is_active for a backtest you own. Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:backtest" ], "x-dogabot-write": true, "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bt-1a2b3c4d" }, "example": "bt-1a2b3c4d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "ce-uuid", "job_id": "bt-1a2b3c4d", "title": "Shared RSI BTC (updated)", "visibility": "public", "is_active": true } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "title": "Shared RSI BTC (updated)", "is_active": true } } } } }, "delete": { "operationId": "deleteBacktestCommunityexampleByJob_id", "tags": [ "Backtests" ], "summary": "Unpublish a Community example", "description": "Unpublishes a Community example (soft: is_active=false). Requires the listed write scope and feat:api:write on an Institutional account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:backtest" ], "x-dogabot-write": true, "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bt-1a2b3c4d" }, "example": "bt-1a2b3c4d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "community example unpublished" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/terminal/place-order": { "post": { "operationId": "postTerminalPlaceorder", "tags": [ "Terminal" ], "summary": "Place a terminal order (async ack)", "description": "Places a terminal order and returns an async ack. Poll by client_order_id for fills. Prefer paper. Requires write:terminal on the key and feat:terminal on the account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:terminal" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "place-paper-btc-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "place-paper-btc-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "accepted", "broadcast_mode": "personal", "session_id": 9, "client_order_id": "dogabot-t1a2b3c4", "side": "buy", "quantity": 0.001, "symbol": "BTC", "exchange": "hyperliquid", "trading_mode": "paper" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "exchange", "symbol", "side", "quantity" ], "properties": { "exchange": { "type": "string", "example": "hyperliquid" }, "symbol": { "type": "string", "example": "BTC" }, "side": { "type": "string", "enum": [ "buy", "sell" ], "example": "buy" }, "quantity": { "type": "number", "example": 0.001 }, "price": { "type": "number", "description": "Required for limit; 0 for market.", "example": 0 }, "order_type": { "type": "string", "enum": [ "market", "limit" ], "example": "market" }, "trading_mode": { "type": "string", "enum": [ "live", "paper" ], "example": "paper" }, "broadcast_mode": { "type": "string", "enum": [ "personal", "leader" ], "example": "personal" }, "emitter_id": { "type": "integer", "description": "Required when broadcast_mode is leader." } }, "example": { "exchange": "hyperliquid", "symbol": "BTC", "side": "buy", "quantity": 0.001, "price": 0, "order_type": "market", "trading_mode": "paper", "broadcast_mode": "personal" } }, "example": { "exchange": "hyperliquid", "symbol": "BTC", "side": "buy", "quantity": 0.001, "price": 0, "order_type": "market", "trading_mode": "paper", "broadcast_mode": "personal" } } } } } }, "/api/v1/terminal/cancel-order": { "post": { "operationId": "postTerminalCancelorder", "tags": [ "Terminal" ], "summary": "Cancel a resting terminal order", "description": "Cancels a resting terminal limit order (GTC). Requires write:terminal on the key and feat:terminal on the account. Send Idempotency-Key.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:terminal" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "status": "accepted", "client_order_id": "dogabot-t1a2b3c4", "exchange": "hyperliquid", "symbol": "BTC", "trading_mode": "paper", "session_id": 9 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_order_id": { "type": "string", "example": "dogabot-t1a2b3c4" }, "order_id": { "type": "string" }, "exchange": { "type": "string", "example": "hyperliquid" }, "symbol": { "type": "string", "example": "BTC" }, "trading_mode": { "type": "string", "example": "paper" }, "session_id": { "type": "integer" } }, "example": { "client_order_id": "dogabot-t1a2b3c4" } }, "example": { "client_order_id": "dogabot-t1a2b3c4" } } } } } }, "/api/v1/ai/chat/quota": { "get": { "operationId": "getAiChatQuota", "tags": [ "Ask AI" ], "summary": "Ask AI daily quota", "description": "Returns daily Ask AI quota (used, limit, remaining). Requires write:ask_ai on the key (Pro soft-allow). Nested tool confirms still run as the key owner. Send Idempotency-Key on mutating calls.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:ask_ai" ], "x-dogabot-write": false, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "used": 2, "limit": 50, "remaining": 48 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/ai/chat/conversations": { "get": { "operationId": "getAiChatConversations", "tags": [ "Ask AI" ], "summary": "List Ask AI conversations", "description": "Lists recent Ask AI conversations. Requires write:ask_ai on the key (Pro soft-allow). Nested tool confirms still run as the key owner. Send Idempotency-Key on mutating calls.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:ask_ai" ], "x-dogabot-write": false, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search conversation titles and messages." }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "items": [ { "id": "conv_abc", "title": "Risk check" } ], "total": 1, "limit": 20, "offset": 0 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } }, "post": { "operationId": "postAiChatConversations", "tags": [ "Ask AI" ], "summary": "Create Ask AI conversation", "description": "Creates an Ask AI conversation thread. Requires write:ask_ai on the key (Pro soft-allow). Nested tool confirms still run as the key owner. Send Idempotency-Key on mutating calls.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:ask_ai" ], "x-dogabot-write": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "data": { "id": "conv_abc", "title": "Risk check" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "title": "Risk check" } } } } } }, "/api/v1/ai/chat/conversations/{id}": { "get": { "operationId": "getAiChatConversationsById", "tags": [ "Ask AI" ], "summary": "Get Ask AI conversation", "description": "Returns an Ask AI conversation with messages. Requires write:ask_ai on the key (Pro soft-allow). Nested tool confirms still run as the key owner. Send Idempotency-Key on mutating calls.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:ask_ai" ], "x-dogabot-write": false, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "conv_abc", "title": "Risk check", "messages": [ { "role": "user", "content": "Hello" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } } } }, "/api/v1/ai/chat/conversations/{id}/messages": { "post": { "operationId": "postAiChatConversationsMessagesById", "tags": [ "Ask AI" ], "summary": "Send Ask AI message", "description": "Sends a message to Ask AI and waits for the full turn. Requires write:ask_ai on the key (Pro soft-allow). Nested tool confirms still run as the key owner. Send Idempotency-Key on mutating calls.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:ask_ai" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "assistant": "Paper risk looks modest. Consider a small BTC buy.", "pending_tools": [] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "message": "Summarize my paper risk and suggest a small BTC buy." } } } } } }, "/api/v1/ai/chat/conversations/{id}/tools/{call_id}/confirm": { "post": { "operationId": "postAiChatConversationsToolsConfirmByIdCall_id", "tags": [ "Ask AI" ], "summary": "Confirm Ask AI tool call", "description": "Approves or rejects a pending Ask AI write tool. Requires write:ask_ai on the key (Pro soft-allow). Nested tool confirms still run as the key owner. Send Idempotency-Key on mutating calls.", "security": [ { "bearerAuth": [] } ], "x-dogabot-scopes": [ "write:ask_ai" ], "x-dogabot-write": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "example": 42 }, "example": 42 }, { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "example": "call_1" }, "example": "call_1" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "example": "retry-1" }, "description": "Unique key per mutation so retries stay safe.", "example": "retry-1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "status": "approved" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "unauthorized" } } } }, "403": { "description": "Forbidden \u2014 missing scope or feature gate" }, "404": { "description": "Not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "approve": true } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "dogabot API key starting with dbk_live_" } } } }