Update an algo instance's upgrade policy
Sets what a new version of the instance’s algo does to it (algos:manage): RESUME, RESTART or STOP (the row’s upgradePolicy says what each does). Legal in every state but DELETED (409 ILLEGAL_TRANSITION) and not a move: only upgradePolicy changes. Takes no If-Match (one refuses 400): no version stamp can refuse it. Answers the row; set it before a roll.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
The instance’s id — a positive 32-bit integer the platform minted; the value an algo’s orders carry as algoInstanceId.
Headers
Required on every write: a URL-safe string of 1 to 64 characters from [A-Za-z0-9._~-] (a UUID fits), scoped to you. It names one operation on one record, ever: a retry replays the stored outcome (Idempotent-Replay: true) or attaches to the live one, and reuse on another record refuses 409 IDEMPOTENCY_KEY_REUSED. Missing or malformed, 400.
Your own id for the request: 8 to 128 of [A-Za-z0-9._-]. It becomes the request’s id and is echoed on the response. A value off that grammar is replaced with a fresh id, never refused.
Query parameters
A position you hold — an X-Immix-Global-Sequence you read, or a 202’s commandGlobalSequence: this member answers only once it has folded the platform’s stream through it, waiting up to its deadline, then 503 PROJECTION_BEHIND with Retry-After. Within that stream a read is never older than what you have seen; drop your positions after an announced stream cut. A retry stating its 202’s position attaches to or replays that operation while the journal holds its key, never publishing twice. Stated once: one to nineteen digits, at most 9223372036854775807; else 400 MALFORMED_REQUEST.
Request
What a new version of the instance’s algo on its pool does to it: RESUME keeps its orders and resumes its state, or lands it ERROR with its orders cancelled when that state cannot be resumed, RESTART cancels its orders and starts afresh, STOP cancels its orders and stops it. UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
Why — at most 256 bytes of UTF-8; empty when none is given. Optional in this body: absent or null reads as "" — no remark.
Response
The instance as the platform now holds it after the write — the same row the read serves, with the answering change’s position, the row’s ETag and, on a replayed key, Idempotent-Replay.
The catalog version the instance runs (GET /algos/versions). When its pool’s engines load a new version of the instance’s algo, the instance moves to it: lastCause then names what the new version did to it.
The document in force; 0 while none has been applied.
The latest staged document’s sequence number — the ETag, and what If-Match takes on a config write.
When it was created — epoch nanoseconds as a decimal string.
The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.
While the instance is STARTED: whether its orders are reaching the book, as its engine last stated it. null in every other status, and cleared by every change of status, so each run begins OK.
The instance’s id — the value its orders carry as algoInstanceId.
Why it last moved: a command, the organisation’s halt, its first document applied, the engine’s fault trip or divergence check, a new version of its algo on its pool — VERSION_RESUMED, VERSION_RESTARTED or VERSION_STOPPED, the owner’s record of its upgradePolicy, or SCHEMA_MISMATCH when the new version’s params schema refused its document (then ERROR, or still CREATED) — or STRATEGY when its own algo stopped it: STOPPED, its state kept, so a start resumes it. The value set is append-only: read an unknown name as UNKNOWN.
The command behind the last move — a desk’s, or the engine’s report that moved it. The value set is append-only: read an unknown name as UNKNOWN.
What the change behind lastCause said of itself, at most 256 bytes: an algo’s reason for stopping itself, the engine’s description of a fault or of a divergence, the schema’s refusal at a version move. Empty when it said nothing, as a command’s change does.
When it last moved — epoch nanoseconds as a decimal string.
Where the instance stands: CREATED until its first document is applied, STOPPED or STARTED under the desk, ERROR after the engine’s fault trip (left only by a stop), DELETED terminal. PENDING_APPROVAL and DISABLED are reserved and never served today. The value set is append-only: read an unknown name as UNKNOWN.
The instance’s transition number: 1 at creation, one more on every move.
What a new version of the instance’s algo on its pool does to it: RESUME keeps its orders and resumes its state, or lands it ERROR with its orders cancelled when that state cannot be resumed, RESTART cancels its orders and starts afresh, STOP cancels its orders and stops it. Set at creation (RESUME when not stated) and changed by POST /algos/instances/{id}/upgrade-policy. UNKNOWN is never served. The value set is append-only: read an unknown name as UNKNOWN.
Who created the instance — a member or an API key.
Whose command last moved the instance — a member or an API key; null when the engine or the platform’s own rule did — lastCause says which.
Reserved; always null.