Skip to navigation

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idintegerRequired

The instance’s id — a positive 32-bit integer the platform minted; the value an algo’s orders carry as algoInstanceId.

Headers

Idempotency-KeystringRequired

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.

X-Request-IdstringOptional

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

minGlobalSequencestringOptionalformat: "^[0-9]{1,19}$"

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

This endpoint expects an object.
upgradePolicyenumRequired

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

Allowed values:
instanceIdintegerOptional
The instance whose upgrade policy is set.
remarkstringOptional

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.

algoVersionIdinteger

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.

appliedConfigSeqinteger

The document in force; 0 while none has been applied.

configSeqinteger

The latest staged document’s sequence number — the ETag, and what If-Match takes on a config write.

createdAtNsstringformat: "^-?[0-9]+$"

When it was created — epoch nanoseconds as a decimal string.

displayNamestring
The instance's display name, as created.
globalSequencestringformat: "^[0-9]+$"

The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.

healthobject or null

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.

instanceIdinteger

The instance’s id — the value its orders carry as algoInstanceId.

lastCauseenum

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.

lastCommandKindenum

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.

lastDetailstring

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.

lastUpdatedAtNsstringformat: "^-?[0-9]+$"

When it last moved — epoch nanoseconds as a decimal string.

orgIdinteger
The organisation that owns the instance.
poolstring
The engine pool the instance runs on, fixed at creation.
statusenum

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.

transitionSeqinteger

The instance’s transition number: 1 at creation, one more on every move.

upgradePolicyenum

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.

Allowed values:
createdByobjectOptional

Who created the instance — a member or an API key.

lastUpdatedByobject or nullOptional

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.

pendingByUserIdinteger or nullOptional

Reserved; always null.

Errors

400
Set Upgrade Policy Algos Request Bad Request Error
401
Set Upgrade Policy Algos Request Unauthorized Error
403
Set Upgrade Policy Algos Request Forbidden Error
404
Set Upgrade Policy Algos Request Not Found Error
409
Set Upgrade Policy Algos Request Conflict Error
413
Set Upgrade Policy Algos Request Content Too Large Error
422
Set Upgrade Policy Algos Request Unprocessable Entity Error
429
Set Upgrade Policy Algos Request Too Many Requests Error
500
Set Upgrade Policy Algos Request Internal Server Error
503
Set Upgrade Policy Algos Request Service Unavailable Error