Add, update or remove a position

Everything the editor does: { "op": "add" | "update" | "remove", "position": {...} }. A refusal says what to fix, in words.

POST/api/positions

Plan ORDERSKey scope ordersLimit 20,000 calls a day on Orders API, 100,000 on Orders Team, per accountVersion 1.0.0Since 2026-10-04

This endpoint serves

Plan: ORDERS. Free on every finished session. Today's ledger, live, and the live POSITIONS check are the ORDERS plan. Pricing.

Body

Field	Meaning	Unit
opadd \| update \| remove	`add`, `update` or `remove`.
positionobject	A short options position: `kind` (`condor`, `strangle`, `put_spread`, `call_spread`), `legs` (`lp`, `sp`, `sc`, `lc`, rising), `entry` (`HH:MM` ET) and optionally `conditions`, `label`, `alert` (`{ channel: telegram \| email \| webhook \| off, url, before }`) and `session`.
position.idstring	`p_...`, given by `add`.
position.kindcondor \| strangle \| put_spread \| call_spread	`condor`, `strangle`, `put_spread` or `call_spread`.
position.legsobject	The strikes, rising, as the kind needs them.
position.legs.lpnumber	Long put.
position.legs.spnumber	Short put.
position.legs.scnumber	Short call.
position.legs.lcnumber	Long call.
position.entrystring	Entry minute, `HH:MM` ET.
position.conditionsarray	`[{ id, on, threshold }]`: which conditions count, and where they switch on.
position.labelobject	`{ caution, skip }`: how many conditions on make each label.
position.alertobject	`{ channel: telegram \| email \| webhook \| off, url, before }`: where the alerts go and how many minutes before entry they start.
position.sessionstring	`YYYY-MM-DD`: the session the strikes were set against.

Response

{ ok: true, ... }; add answers the new id.

Field	Meaning	Unit
okboolean	Done.

Errors

Status	Code	What to do
400	`bad_json`, `bad_op`, `invalid`	The body cannot be used; `message` says why. Send `Content-Type: application/json` and a JSON object.
401	`no_key`	No key, or a revoked one. Send `Authorization: Bearer <key>` with a key of the product's scope.
403	`plan`	The account is not on the Orders API or Team plan. Move to the Orders API or Team plan.
404	`not_found`	No position with this id. Check the path or the id.
405	`method`	GET or POST only. Send a GET or a POST.
429	`rate`	The day's calls are spent. Wait for midnight ET, when the count resets.

Every code: Errors.

Changes

2026-10-04 Added.

OpenAPI operation positionsChange in /docs/developers/openapi.json.

Request

curlPythonNode

curl -X POST \
  -H "Authorization: Bearer $FIRMTAPE_ORDERS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"add","position":{"kind":"condor","legs":{"lp":7690,"sp":7700,"sc":7745,"lc":7755},"entry":"13:45","alert":{"channel":"webhook","url":"https://your.server/hook","before":10}}}' \
  "https://firmtape.com/api/positions"

import os, requests

H = {"Authorization": f"Bearer {os.environ['FIRMTAPE_ORDERS_KEY']}"}
r = requests.post("https://firmtape.com/api/positions", headers=H, json={"op":"add","position":{"kind":"condor","legs":{"lp":7690,"sp":7700,"sc":7745,"lc":7755},"entry":"13:45","alert":{"channel":"webhook","url":"https://your.server/hook","before":10}}})
print(r.status_code, r.text[:500])

const r = await fetch("https://firmtape.com/api/positions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FIRMTAPE_ORDERS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({"op":"add","position":{"kind":"condor","legs":{"lp":7690,"sp":7700,"sc":7745,"lc":7755},"entry":"13:45","alert":{"channel":"webhook","url":"https://your.server/hook","before":10}}}),
});
console.log(r.status, await r.text());

Response

400401403404405

{
  "error": {
    "code": "bad_json",
    "message": "The body is not JSON."
  }
}

{
  "error": {
    "code": "no_key",
    "message": "No key was sent (Orders: no key, or one that is unknown or revoked)."
  }
}

{
  "error": {
    "code": "plan",
    "message": "The key is real; the account is not on the Orders API or Team plan."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "No such endpoint (levels API), or no position with this id on this account (POSITIONS)."
  }
}

{
  "error": {
    "code": "method",
    "message": "The POSITIONS API takes GET or POST."
  }
}

Measurements of dealer positioning, never a forecast or a trade call. This page is built from FirmTape's public contract, the same files the OpenAPI document is built from; the tests hold them against the route code. Markdown: /docs/developers/orders/positions-change.md.