User API: Creating, Changing and Switching Bots

This article is the reference for changing bots through the User API: building a settings object from the dictionary, checking it, creating a bot, editing an idle or a live bot, previewing the strikes a bot would choose, and turning a bot on or off. Every bot the API creates is saved switched off.

Every path is under https://api.tradesteward.com/rest/v1, every request carries Authorization: Bearer <token> and, for a body, Content-Type: application/json. Every answer is the JSON envelope from Your First Request; the examples show only data.

The plan you need is in Use the tradeSteward API From Your Own Code. Every Trader plan can check and create bots, edit a bot that is not live and preview strikes. Turning a bot on or off and editing a live bot need Trader Unlimited: on a lower Trader plan those requests, and a check of a live bot's edit, answer 403 entitlement_required. Its message says to upgrade at https://www.tradesteward.com/useracct/subs and then turn the permission on for the client in Connected Apps, and its error.data carries product bots, access write, requiredPlan Trader Unlimited, upgradeUrl (the upgrade page) and apiAccessUrl (the Connected Apps page).

Each section names the permission it needs: bots.create (Create bots (always saved disabled)), bots.edit.idle (Edit idle bots), bots.edit.live (Edit live bots), bots.preview (Preview strikes (live quotes)), bots.enable (Enable bots) and bots.disable (Disable bots). Create, edit idle, preview and disable are on by default; edit live and enable are off by default, and each such request waits for your approval unless you turned approval off for an API client; a connected AI app's request always waits. See Permissions and Limits for the others and Safeguards for edit live and enable.

Rules that apply to every write

Idempotency keys

Creating a bot, editing a bot, turning a bot on and resuming trading each need an Idempotency-Key header: a unique value you choose, 1 to 128 letters, digits, dots, underscores or hyphens. Generate a fresh one per intended change and reuse it only when you retry that same change. The same key with the same request returns the first answer and never builds a second bot or enables one twice; the same key with a different request answers 409 idempotency_conflict. Keys are kept for 2 days. A request refused before anything was saved frees its key, so the corrected request can reuse it. A request that died while saving keeps its key in progress: the same request sent again answers 409 idempotency_in_progress, first with a Retry-After as a request still running and after two minutes as one that did not finish. Read the bot before you send a new request with a new key. Checking settings, previewing strikes, turning a bot off and pausing trading ignore the header and always run.

Limits on changes

A create or an edit counts toward the limit on changes and toward a separate limit on bot changes; turning a bot on and resuming trading count toward both of those and toward a third, tighter limit on turn-on, resume and live edit requests. A Multi-Entry bot's create or edit spends more of the limit on changes than a single bot's. Turning a bot off and pausing trading are stop actions with their own limit, and they stay available while changes are switched off (503 writes_disabled refuses the other writes then). X-RateLimit-Remaining on the limit on changes counts units of work, not calls. Writes are also refused while the account already has as many requests running at once as it may.

Connection limits

A client limited to certain broker accounts can create bots only on those accounts (accountNum on another account answers 422 validation_failed with the reason not_found, exactly as an account you do not have) and sees, edits and switches only the bots on them. A client limited to the bots it created sees and changes only those; every other bot answers 404 not_found. A setting that names another bot (launchOnStop and the six depBots-* lists) may name only a bot the client may see.

What you see before a bot trades

A bot the API creates is always saved switched off, and an edit never turns a bot on or off. When you later turn a bot on from the Bots page, its settings page or a portfolio, tradeSteward first shows you what the connection created or changed since the bot was last enabled: its key settings, each setting the API changed, and for a live edit waiting for approval the exact changes asked for. The same review is on the approval page for a request that waits for your approval. The API never skips it.

Building a settings object

Settings travel as one flat JSON object keyed by the dictionary's key values. The dictionary comes from GET /schema/bot-settings, described in Account, Trading and Schema Endpoints. The surest way to build one is to read a bot you already have with GET /bots/{botId}, change what you need and check the result; a read sent back unchanged is always accepted. Building from nothing, follow these rules, all of which the dictionary states per setting:

• Use only keys whose appliesTo includes bots. An unknown key answers validation_failed with the reason unknown.
• Send a text value as text and a number as a number. Enumerated settings of type char or varchar take their values in quotes: "botsize-type": "Q", "stop-type": "P", "opt1-optionSide": "P". A bare Q is not JSON, and a number where text is expected answers validation_failed with the reason invalid_type. An on or off setting (type toggle, or an enum of 0 and 1) takes 0, 1, "0", "1", true or false.
• Numbers are written plainly: no exponent, at most 15 significant digits, and no more decimals than the setting's scale. A number that breaks the first two rules is refused with the reason invalid_number. One with too many decimals is refused with too_precise, and its item carries decimals, the number of decimals the setting keeps. out_of_range means a number outside the setting's allowed range, and wrong_type a value of the wrong kind.
• Times are US Eastern. The entry window is three two-digit parts for its start (entryHour-start, entryMinute-start, entrySecond-start, from 09:30:50) and three for its end; a timed exit is exit-hour and exit-min with exit-enabledTime 1. Entry days are entryDOW-M, entryDOW-T, entryDOW-W, entryDOW-R and entryDOW-F, each sent as its own letter to select the day; on a create a day left out is skipped.
• Pair a type with its value in the same request: stop-type P with stop-creditMultiple, V with stop-dollar, D or R with stop-delta, U with stop-underlying-points, C with stop-underlying-percent, S with stop-shortlong-ratio; exit-profitTargetType P with exit-premiumTargetPercent, V with exit-premiumTargetDollar, D with exit-premiumTargetFixedDollar; botsize-type Q with botsize-Qty, P with botsize-percentNLV, L with botsize-leverage, D with botsize-dollarTarget. On an edit that changes the type, the old number is never converted, so send the new value too.
• Legs are opt1- to opt4-, up to numLegs, and botTradeType names the template that matches that count. Each leg has optionSide (P or C), shortLong (S or L), strikeTargetType, strikeTarget (read as that type says: a delta of 10 is 10), targetDTE with minDTE and maxDTE around it, and sizeRatio (1 for a normal trade).
• A Multi-Entry bot's settings carry multiEntryLength (HH:MM:SS, 00:00:30 to 06:00:00), not the six entry window parts (the entries set every window), and enterByTimeOrTrigger only as time; botName is then at most 30 characters, 40 otherwise. An ordinary bot that carries multiEntryLength is refused with the reason multi_entry_only.

Always check the object with POST /bots/validate first: it runs the same checks as the save and refuses the same things, without writing. The reason words a validation_failed answer uses in fieldErrors are required, unknown, invalid_type, wrong_type, invalid_number, too_precise (with decimals), out_of_range, invalid, not_applicable, too_many, not_found, disabled (the bot's strategy is turned off on tradeSteward), bot_not_found (a setting names a bot the client may not use), read_only, use_enable_or_disable, restate_required (a value that must be sent again with the setting that changed), stale, multi_entry_only; for an account, broker_not_supported, restricted, trading_disabled and no_options; and for a Multi-Entry bot and its entries, set_by_entries, too_long, invalid_time, duplicate_time, duplicate, send_bot_id, not_allowed_on_create, time_change_not_supported, names_removed_entry, invalid_size, no_size_type and invalid_length.

Checking and creating a bot

POST /bots/validate Check settings without saving

Checks settings for a new bot, or a change to an existing bot, exactly as the create or the edit would, and saves nothing. Send the create body to check a new bot, or {"botId": ..., "settings": ...} to check an edit: the settings are laid over the stored bot as an edit would lay them. With entries, a new bot is checked as a new Multi-Entry bot and an existing one as a change of its entries. Operation id: validateBotSettings.

Permission: bots.create (Create bots) to check a new bot; bots.edit.idle (Edit idle bots) to check an edit of a bot that is not live; bots.edit.live (Edit live bots) to check an edit of a live bot. Validation has its own limit, and one validation runs at a time per account. A second one sent while the first runs answers 429 rate_limited with Retry-After: 2.

What it returns: {"valid": true}. Anything the save would refuse is answered as the save would answer it, most often 422 validation_failed with fieldErrors, one item per setting with field and reason.

{
  "ok": false, "data": null,
  "error": {"code": "validation_failed", "message": "Some settings are not valid. See fieldErrors.",
            "requestId": "6a0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
            "fieldErrors": [{"field": "botsize-type", "reason": "invalid_type"},
                            {"field": "opt1-targetDTE", "reason": "required"}]},
  "apiVersion": "rest-v1", "requestId": "6a0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e"
}

Refusals: 422 validation_failed; 403 permission_denied for the permission the body's form needs; 403 entitlement_required for a live bot's edit below Trader Unlimited; 404 not_found for a bot the client may not see; 409 bot_archived; 409 family_live_edit_unsupported for a Multi-Entry bot that is not idle; 422 family_edit_unsupported when botId is an entry (with error.data.parentBotId when the client can see its bot); 429 rate_limited.

POST /bots Create a bot

Creates a bot and saves it switched off. Only you can turn it on, on tradeSteward, or your code can ask with POST /bots/{botId}/enable. With entries the new bot is a Multi-Entry bot that enters at each listed time. Operation id: createBot.

Permission: bots.create (Create bots (always saved disabled)).

A full create, built from the dictionary: a put credit spread on SPX, entered at 9:31 on weekdays, 10 delta short with a 20-point wide long, one contract, a 50% profit target and a 200% stop.

POST /rest/v1/bots
Authorization: Bearer tsa_9f1c...
Content-Type: application/json
Idempotency-Key: create-spx-pcs-2026-11-03-01

{
  "accountNum": "12344821",
  "stratCode": "SPXPCS",
  "settings": {
    "botName": "SPX 10 Delta Put Spread 9:31a",
    "symbol": "$SPX.X",
    "botTradeType": "vertical",
    "enterByTimeOrTrigger": "time",
    "entryHour-start": "09", "entryMinute-start": "31", "entrySecond-start": "00",
    "entryHour-end": "09", "entryMinute-end": "45", "entrySecond-end": "00",
    "entryDOW-M": "M", "entryDOW-T": "T", "entryDOW-W": "W", "entryDOW-R": "R", "entryDOW-F": "F",
    "entryDayToggle": 0,
    "fillSpeed": "normal",
    "botsize-type": "Q", "botsize-Qty": 1,
    "numLegs": 2,
    "opt1-optionSide": "P", "opt1-shortLong": "S", "opt1-strikeTargetType": "delta",
    "opt1-strikeTarget": 10, "opt1-targetDTE": 0, "opt1-minDTE": 0, "opt1-maxDTE": 0, "opt1-sizeRatio": 1,
    "opt2-optionSide": "P", "opt2-shortLong": "L", "opt2-strikeTargetType": "distance",
    "opt2-strikeTarget": 20, "opt2-targetDTE": 0, "opt2-minDTE": 0, "opt2-maxDTE": 0, "opt2-sizeRatio": 1,
    "exit-profitTargetType": "P", "exit-premiumTargetPercent": 50,
    "exit-enabledTime": 1, "exit-hour": "15", "exit-min": "55",
    "exit-DTE": 0, "exit-days-DTEorDIT": "dte",
    "stop-controller": "T", "stop-type": "P", "stop-creditMultiple": 200,
    "stop-grouping": "net", "stop-speed": "normal"
  }
}

This object passes POST /bots/validate as written. The settings a new bot always needs, beyond the ones that describe your trade, are botTradeType (it must agree with numLegs: single 1 leg, vertical 2, condor 4, custom 2 to 4), fillSpeed, each leg's minDTE and maxDTE around its targetDTE, exit-DTE with exit-days-DTEorDIT, and stop-controller with stop-grouping. Leave one out and the validator names it with the reason invalid.

What it returns: 201 with the bot summary as GET /bots lists it (enabled false, live false, createdByThisConnection true). A Multi-Entry bot's answer also lists its entries.

{
  "botId": "hJ7bP3sR6u", "botName": "SPX 10 Delta Put Spread 9:31a", "enabled": false, "live": false,
  "inTrade": false, "archived": false, "accountNum": "12344821", "stratCode": "SPXPCS",
  "symbol": "$SPX.X", "botType": "N", "parentBotId": null, "settingsVersion": 0, "version": "0",
  "createdByThisConnection": true
}

Then call POST /bots/hJ7bP3sR6u/preview to see the strikes it would pick right now, and turn it on yourself on the Bots page when you are satisfied. A problem only the broker can report, such as an order the broker refuses, shows at the preview or when the bot trades, not at the create.

Refusals: 428 idempotency_key_required; 409 idempotency_conflict; 422 validation_failed (a missing accountNum, stratCode or settings, an unknown account or strategy, a strategy that is turned off, an account that is restricted, turned off for bots or not approved for options, a bot named in a setting that the client may not use, or any invalid setting); 403 permission_denied; 403 entitlement_required on a plan without API access to bots; 429 rate_limited; 503 writes_disabled; 503 service_unavailable when the save could not be confirmed (read GET /bots before you try again with a new key).

Editing a bot

PATCH /bots/{botId} Change a bot's settings

Changes some settings of a bot. Send only the settings to change; everything else keeps its stored value. An edit never turns a bot on or off and never moves it to another account or strategy. Operation id: updateBot.

Permission: bots.edit.idle (Edit idle bots) for a bot that is not live; bots.edit.live (Edit live bots, which needs Trader Unlimited) for a live one. A bot is live while it is enabled, holds or is opening a trade, has an exit order placed in the last 24 hours still on record, has a launch pending, or for ten minutes after it was turned off; live on GET /bots/{botId} tells you which rule applies. A client that holds only the live permission is told nothing about an idle bot beyond permission_denied, and one that holds only the idle permission gets permission_denied for a live bot.

Versions and conflicts. Every bot carries a version. The edit is applied only when the If-Match value is the bot's current version; if the website, another client or an approved request changed the bot in between, the edit answers 412 version_mismatch with the current version in error.data.current, and nothing is saved. Read the bot again, decide whether your change still makes sense, and retry with the new version and a new key. A missing header answers 428 precondition_required.

Idle edits. An edit of a bot that is not live is saved at once and answers 200 with the bot summary plus changed (false when the request matched the stored settings and nothing was saved; the version does not move then) and adhocCleared, a list of what the save cleared on the bot's open trades because its stop or profit target changed, each item one of stop, profitTarget, both or trail; it is an empty list when nothing was cleared. An edit through the API never lifts a bot's "no more trades today" state.

Live edits. An edit of a live bot is a request that starts or changes trading, so by default it waits for your approval: the answer is 202 with status pending_confirmation, actionId and expiresAt, nothing has changed yet, and the outcome is read from GET /pending-actions/{actionId}. You approve or reject it on the tradeSteward website, or in the tradeSteward app where app approval is available; the approval page shows the bot's settings and the exact changes asked for. A request you do not answer expires after 1 hour. If the bot changes between the request and your approval, the approval is not carried out and the outcome is bot_changed_since_request. With approval turned off for the client, a live edit is saved at once and answers 200 like an idle edit, and the website's work on open trades runs as it does for a save on the website. Details: Approving Requests That Start Trading. While a request for a bot is waiting, any other edit of that bot answers 409 pending_action_exists with the waiting request's actionId.

Multi-Entry bots. A Multi-Entry bot is changed through the API only while it is idle: switched off for more than ten minutes, with no entry working a trade or an order. Otherwise the answer is 409 family_live_edit_unsupported, whatever the client may do, and nothing waits for approval. Send entries to add or remove entry times: the complete list after the change, where an item with botId keeps that entry (send it as the read lists it; its entryStart and enabled must be its own, its size may change, inTrade is ignored), an item with only entryStart adds one, and an entry left out is removed. A removal is refused with 409 invalid_state and the reason entry_referenced while another bot launches or depends on that entry; error.data.botIds lists the ones the client may see and error.data.otherBots counts the rest. A setting of this bot that still names the removed entry is refused with 422 validation_failed and the reason names_removed_entry. An entry that holds an open trade cannot be removed: 409 invalid_state with the reason entry_in_trade. Leave entries out to keep them as they are. A change of botsize-type clears every entry's own size the request leaves out; to keep one, send it in the new unit. An entry is changed through its bot: a request aimed at an entry answers 422 family_edit_unsupported, with error.data.parentBotId when the client can see that bot.

PATCH /rest/v1/bots/hJ7bP3sR6u
If-Match: 0
Idempotency-Key: widen-stop-2026-11-03-01
Content-Type: application/json

{"settings": {"stop-type": "P", "stop-creditMultiple": 250, "exit-premiumTargetPercent": 60}}

200
{"botId": "hJ7bP3sR6u", "botName": "SPX 10 Delta Put Spread 9:31a", "enabled": false, "live": false,
 "inTrade": false, "archived": false, "accountNum": "12344821", "stratCode": "SPXPCS", "symbol": "$SPX.X",
 "botType": "N", "parentBotId": null, "settingsVersion": 1, "version": "1",
 "createdByThisConnection": true, "changed": true, "adhocCleared": []}

Refusals: 428 precondition_required; 412 version_mismatch; 428 idempotency_key_required; 409 idempotency_conflict; 422 validation_failed (including accountNum or stratCode in the body, reason read_only, and enabled in the body, reason use_enable_or_disable); 404 not_found; 403 permission_denied; 403 entitlement_required for a live bot below Trader Unlimited; 409 bot_archived (restore it on the website first); 409 pending_action_exists; 409 family_live_edit_unsupported; 422 family_edit_unsupported; 429 rate_limited (the limit on changes, the bot changes limit, the live edit limit, or the limits on requests waiting for approval); 503 writes_disabled; 503 service_unavailable with error.data.botId when the change was saved but the bot could not be read back: read it before trying again.

Previewing strikes

POST /bots/{botId}/preview The strikes a bot would choose right now

Runs the saved bot's strike selection against live quotes and reports what it would trade, without saving anything or placing an order. The bot must already exist: create it, preview it, adjust it. It takes no body and works on every Trader plan. Operation id: previewBotStrikes.

Permission: bots.preview (Preview strikes (live quotes)).

Limits: a preview calls your broker with your own quota, which the live engine shares, so previews are paced hard: a few a minute for the account, one at a time, and spaced apart. A preview that comes too soon answers 429 rate_limited with Retry-After; one that arrives while another is running spends none of the preview limits, though like every read it still counts toward the reads limit. The same limits cover previews made by a connected AI assistant. A Test Run on the website is paced separately, but one you ran moments ago makes a preview answer the tooFast token (see below).

What it returns: botId; strikes, the option symbol each leg would trade right now, keyed by leg name (opt1, opt2, ...); errors, reasons the bot would not open right now as tokens (for example marketClosed; tooFast means a preview or a website Test Run by you ran moments ago and nothing was checked, so wait a few seconds and ask again); invalidSettings, the names of stored settings that failed validation; legErrors, by leg name; and failedFilters, the entry filters that would block an entry right now.

{"botId": "hJ7bP3sR6u",
 "strikes": {"opt1": "SPXW 261103P06640", "opt2": "SPXW 261103P06620"},
 "errors": [], "invalidSettings": [], "legErrors": {}, "failedFilters": {}}

Refusals: 404 not_found; 403 permission_denied; 429 rate_limited; 503 service_unavailable when the pacing could not be checked (a preview is never run unpaced).

Turning a bot on or off

POST /bots/{botId}/enable Turn a bot on

Sets an ordinary bot's switch to on. Because it starts trading, it is one of the requests that waits for your approval by default. The answer is then 202 with status pending_confirmation, actionId and expiresAt; nothing has changed yet; the request appears on the Connected Apps page and in your notifications, and you approve or reject it on the tradeSteward website, or in the tradeSteward app where app approval is available. The approval page shows the bot's key settings and everything the API changed since it was last enabled. Your code reads the outcome from GET /pending-actions/{actionId}; an unanswered request expires after 1 hour. Everything that can be checked without writing (the account, the plan's bot limit, the settings) is checked before the request is stored, so you are never asked to approve a request that could not succeed. With approval turned off for the client, the bot is turned on at once and answers 200. It takes no body. Operation id: enableBot.

A Multi-Entry bot is never turned on through the API, and neither is one of its entries: the answer is 422 family_edit_unsupported, with error.data.parentBotId for an entry when the client can see its bot. You turn those on yourself on tradeSteward.

Permission: bots.enable (Enable bots). Off by default, needs Trader Unlimited.

What it returns: on 200, the bot summary with enabled true plus alreadyEnabled (true when the bot was already on and nothing changed; such a request never waits for approval). On 202, the pending answer.

202
{"status": "pending_confirmation", "actionId": "a_3f9c1b7e2a4d6058c1e7b2", "expiresAt": "2026-11-03T15:12:40Z"}

Refusals: 428 idempotency_key_required; 409 idempotency_conflict; 404 not_found; 403 permission_denied; 403 entitlement_required below Trader Unlimited; 422 family_edit_unsupported; 409 bot_archived; 403 account_disabled (the bot's broker account is not enabled for trading); 403 subscription_limit (one more enabled bot would exceed your plan); 422 validation_failed (the stored settings, or the bot's account, need attention: review the bot on tradeSteward; this answer carries no fieldErrors); 409 pending_action_exists; 409 bot_changed_since_request (the bot changed while the request ran: read it and retry); 429 rate_limited (the limit on turn-on, resume and live edit requests, or the limits on requests waiting for approval); 503 writes_disabled (changes through the API are switched off for a moment; turning a bot off still works); 503 lock_busy with Retry-After: 2; 503 service_unavailable when the enable could not be confirmed: read the bot before trying again.

POST /bots/{botId}/disable Turn a bot off

A stop action: it takes no body and no Idempotency-Key, every call runs, and it stays available while changes are switched off. The bot opens no new trades. The trading engine can take a short time to observe the change, an order already at the broker may still fill, and open trades keep being managed until they close. Turning a Multi-Entry bot off stops all of its entries; send an entry's own botId to turn that one entry off. Disabling a bot that is already off changes nothing. Operation id: disableBot.

Permission: bots.disable (Disable bots). Needs Trader Unlimited. Stop actions have their own limit.

What it returns: the bot summary with enabled false, plus openingOrderPending, true when an opening order was already at the broker when the bot was disabled (for a Multi-Entry bot, on any of its entries). When the disable landed but the entries of a Multi-Entry bot could not be read back, inTrade, version, familyVersion, live and openingOrderPending are null rather than guessed.

{"botId": "aB3xK9mN2q", "botName": "SPX 10 Delta Put Spread 9:31a", "enabled": false, "live": true,
 "inTrade": true, "archived": false, "accountNum": "12344821", "stratCode": "SPXPCS", "symbol": "$SPX.X",
 "botType": "N", "parentBotId": null, "settingsVersion": 15, "version": "15",
 "createdByThisConnection": false, "openingOrderPending": false}

live stays true for ten minutes after a disable, so an edit right after it still needs the live edit permission.

Refusals: 404 not_found; 403 permission_denied; 403 entitlement_required below Trader Unlimited; 429 rate_limited; 503 service_unavailable when the disable could not be confirmed: try again, or turn the bot off on tradeSteward.