IMMIX Operations API

openapi: 3.2.0
info:
  title: REST Operations API
  version: 1.0.0
  description: The outcome of a write that answered `202`.
servers:
- url: https://api.immix.xyz/v1
  description: prod
tags:
- name: Operations
  description: The outcome of a write that answered `202`.
paths:
  /operations/{key}:
    get:
      operationId: operations_get
      summary: Get an operation
      description: 'Serves one of your own operations by its `Idempotency-Key` — the `202` response''s `Location` — with its phase and, once concluded, the outcome a synchronous caller would have read. Another caller''s key, an unknown one, or a member restarted since is 404 `UNKNOWN_OPERATION`: poll the member that carried the request.'
      tags:
      - Operations
      parameters:
      - name: key
        in: path
        description: The operation's `Idempotency-Key`, as sent.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: '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.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The journaled operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationRecord'
        '400':
          description: 'The key is off the `Idempotency-Key` grammar (`INVALID_IDEMPOTENCY_KEY`), or the request carries a query parameter: this read takes none (`MALFORMED_REQUEST`). No position rides a refusal that consulted no state.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No bearer token, or one that does not verify.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Authenticated, but not admitted. `NOT_REGISTERED`: no row and no open invitation at your verified address (ask to be invited), an unknown organisation, or a row nobody has claimed (an administrator admits it; no invitation binds a held subject). `EMAIL_UNVERIFIED`: verify your address, then sign in again. `INVITATION_EXPIRED`: an administrator re-invites. `FORBIDDEN_PRINCIPAL`: no `org_id`, a non-ASCII ref, a disabled user, a binding with no user. `ORG_NOT_ACTIVE`: suspended, pending or retired. The record owners'' 403s carry the position header and replay with `Idempotent-Replay`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No such operation for you on this member (`UNKNOWN_OPERATION`): a key never used here, another caller''s, or one evicted from the journal.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: This member is still catching up; retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
components:
  schemas:
    OperationRecordOutcomeFamily:
      type: string
      enum:
      - orgs
      - users
      - credentials
      - accounts
      - account-addresses
      - portfolios
      - asset-policies
      - chain-policies
      - trading-policies
      - orders
      - algos
      description: The resource the operation targeted — where its `entityId` (for orders, `orderId`; for algos, `instanceId` and `configSeq`) reads; a refused address declaration names the account it referred to, under `accounts`.
      title: OperationRecordOutcomeFamily
    OperationRecord:
      type: object
      properties:
        key:
          type: string
          description: The `Idempotency-Key` as you sent it.
        phase:
          $ref: '#/components/schemas/OperationRecordPhase'
        commandGlobalSequence:
          type: string
          pattern: ^-?[0-9]+$
          description: The command's position once committed; absent while pending.
        origin:
          $ref: '#/components/schemas/OperationRecordOrigin'
          description: The gateway member and instance that carried the request — the journal is member-local.
        createdTimestampNs:
          type: string
          pattern: ^-?[0-9]+$
          description: When the operation was journaled, epoch nanoseconds.
        concludedTimestampNs:
          type: string
          pattern: ^-?[0-9]+$
          description: When the answer landed, epoch nanoseconds; absent until concluded.
        outcome:
          $ref: '#/components/schemas/OperationRecordOutcome'
          description: The stored outcome — what a retry of the key replays; absent until concluded.
      required:
      - key
      - phase
      - origin
      - createdTimestampNs
      description: 'One of your operations, by its key: its phase — `PENDING` until this member sees its own command on the stream, `COMMITTED` from then, `CONCLUDED` once the owner''s answer lands — and the stored outcome.'
      title: OperationRecord
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
        currentVersion:
          type: string
          pattern: ^-?[0-9]+$
          description: 'On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance''s config write: the row''s current version (the `ETag` carries the same token) — re-read, reapply, retry.'
      required:
      - error
      description: 'The one error envelope, on every refusal: error.code is the machine surface, error.message display text, error.requestId the request''s id and error.retryable whether a plain retry can succeed. A 412 adds currentVersion.'
      title: Error
    OperationRecordOutcome:
      type: object
      properties:
        httpStatus:
          type: integer
        code:
          type: string
          description: '`OK` on an accepted write; otherwise the `Error.code` the refusal carried.'
        message:
          type: string
          description: The detail the refusal itself stated (an order refusal's observed value against its limit, and the governing policy); absent when it stated none, where a synchronous caller read the code's standing sentence as `error.message`. For humans; never parse it.
        family:
          $ref: '#/components/schemas/OperationRecordOutcomeFamily'
          description: The resource the operation targeted — where its `entityId` (for orders, `orderId`; for algos, `instanceId` and `configSeq`) reads; a refused address declaration names the account it referred to, under `accounts`.
        entityId:
          type: integer
          description: 'The record the outcome names: the id minted on an accepted create, the path''s id otherwise, the referred account on a refused address declaration; absent when none. An orders operation names its order in `orderId` instead, an algos one its instance in `instanceId`.'
        instanceId:
          type: integer
          description: On an algos operation, the instance the outcome names — minted on an accepted create, the path's otherwise; absent on a halt and when none.
        configSeq:
          type: integer
          description: On an algos operation that staged a document — a create, or a config write — the document's sequence number; absent otherwise.
        globalSequence:
          type: string
          pattern: ^-?[0-9]+$
          description: The answer's position; `0` when the outcome came from no change (a refusal at the door or in transit).
        orderId:
          type: string
          pattern: ^-?[0-9]+$
          description: On an orders operation, the order the outcome names — minted on an accepted submit, the path's on a cancel; absent when none. A 64-bit integer, so a decimal string.
      required:
      - httpStatus
      - code
      - globalSequence
      description: The stored outcome — what a retry of the key replays; absent until concluded.
      title: OperationRecordOutcome
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          description: 'The code to branch on — stable and append-only: treat one you do not know by its HTTP status. The gateway''s:


            - 400: `MALFORMED_REQUEST`, `MISSING_IDEMPOTENCY_KEY`, `INVALID_IDEMPOTENCY_KEY`, `INVALID_IF_MATCH`, `INVALID_CURSOR`

            - 401: `UNAUTHENTICATED`

            - 403: `FORBIDDEN_PRINCIPAL`, `NOT_REGISTERED`, `INVITATION_EXPIRED`, `EMAIL_UNVERIFIED`, `ORG_NOT_ACTIVE`, `CAPABILITY_DENIED`, `AWAITING_ADMISSION`

            - 404: `NOT_FOUND`, `UNKNOWN_OPERATION`, `ROUTE_NOT_FOUND` (no route answers the path)

            - 405: `METHOD_NOT_ALLOWED`

            - 409: `IDEMPOTENCY_KEY_REUSED`, `INTAKE_KEY_REUSED`

            - 413: `TOO_LARGE`, `PAYLOAD_TOO_LARGE`, `DOCUMENT_TOO_LARGE`

            - 422: a reference this member will not send: `INSTRUMENT_NOT_LIVE`, `ACCOUNT_NOT_ACTIVE` (`POST /orders`), `REFERENCE_UNKNOWN_INSTRUMENT`, `REFERENCE_INSTRUMENT_NOT_LIVE`, `REFERENCE_UNKNOWN_ACCOUNT` (an algo document); `VENUE_UNSUPPORTED`; `SCALE_UNKNOWN` (retired at `0.3.4`)

            - 428: `PRECONDITION_REQUIRED`

            - 429: `INBOX_FULL`, `IN_FLIGHT_FULL`, `RATE_LIMITED`

            - 500: `INTERRUPTED`, `INTERNAL_ERROR`, `PROJECTION_MISS`

            - 503: `NOT_PRIMED`, `NOT_SERVING`, `OWNER_ABSENT`, `INTAKE_UNAVAILABLE`, `BALANCES_UNAVAILABLE`, `ALGOS_UNAVAILABLE`, `TICKETS_UNAVAILABLE`, `INVITATIONS_UNAVAILABLE`, `REGISTRATION_PENDING`, `LOST`, `REJECTED_NOT_REGISTERED`, `REJECTED_NOT_ACTIVE`


            The record owners'' refusals ride verbatim — `OrgRegisterRejected.reason`, `OrderRejected.reason` and `AlgoRejected.reason` list them; the guide maps each to its status.'
        message:
          type: string
          description: For display only; its wording may change at any time.
        requestId:
          type: string
          description: The request's id, also sent as X-Request-Id; quote it to support.
        retryable:
          type: boolean
          description: 'Whether sending the identical request again, its `Idempotency-Key` included, after `Retry-After` or a short pause, can succeed with nothing else changed. `false` where something must change first: the request, its key, its precondition, the caller''s standing, or the platform''s own records or deployment. A refusal the record owner judged is always `false`: it is the recorded answer to its key, which replays it.'
      required:
      - code
      - message
      - requestId
      - retryable
      description: What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
      title: ErrorBody
    OperationRecordOrigin:
      type: object
      properties:
        memberId:
          type: integer
        instanceId:
          type: string
          pattern: ^-?[0-9]+$
      required:
      - memberId
      - instanceId
      description: The gateway member and instance that carried the request — the journal is member-local.
      title: OperationRecordOrigin
    OperationRecordPhase:
      type: string
      enum:
      - PENDING
      - COMMITTED
      - CONCLUDED
      title: OperationRecordPhase
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer