List ledger commands

curl --request GET \
  --url https://api.usenexio.com/api/v1/records/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Nexio-Acting-Principal: <x-nexio-acting-principal>'

import requests

url = "https://api.usenexio.com/api/v1/records/actions"

headers = {
    "X-Nexio-Acting-Principal": "<x-nexio-acting-principal>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Nexio-Acting-Principal': '<x-nexio-acting-principal>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.usenexio.com/api/v1/records/actions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "serving": {
    "overlay_rev": 1,
    "as_of": "2023-11-07T05:31:56Z",
    "batch_set_id": "<string>",
    "binding_id": "<string>",
    "read_pin": "2023-11-07T05:31:56Z",
    "source": {
      "mode": "<string>",
      "fetched_at": "2023-11-07T05:31:56Z",
      "current": true,
      "freshness": "current",
      "stale_since": "2023-11-07T05:31:56Z"
    },
    "lens": {
      "target": "<string>",
      "display_name": "<string>",
      "scope_kind": "<string>"
    }
  },
  "duration_ms": 123,
  "data": [
    {
      "seq": 123,
      "command_id": "<string>",
      "actor_principal": "<string>",
      "actor_type": "<string>",
      "entity_domain": "<string>",
      "command": "<string>",
      "schema_rev": 123,
      "payload": {},
      "recorded_at": "2023-11-07T05:31:56Z",
      "connection_id": "<string>",
      "client_key": "<string>",
      "ams360_datasource": "<string>",
      "policy_id": "<string>",
      "app_entity_type": "<string>",
      "app_entity_id": "<string>",
      "catalog_entity_type": "<string>",
      "catalog_id": "<string>",
      "issued_at": "2023-11-07T05:31:56Z"
    }
  ],
  "next_seq": 123,
  "action_seq": 123,
  "limit": 123
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "unauthorized",
  "message": "Missing or invalid API key"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded"
}

{
  "code": "client_closed_request",
  "message": "The client closed the request before the book read finished"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "request_timeout",
  "message": "Request timed out"
}

GET

api

records

actions

List ledger commands

curl --request GET \
  --url https://api.usenexio.com/api/v1/records/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Nexio-Acting-Principal: <x-nexio-acting-principal>'

import requests

url = "https://api.usenexio.com/api/v1/records/actions"

headers = {
    "X-Nexio-Acting-Principal": "<x-nexio-acting-principal>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Nexio-Acting-Principal': '<x-nexio-acting-principal>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.usenexio.com/api/v1/records/actions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "serving": {
    "overlay_rev": 1,
    "as_of": "2023-11-07T05:31:56Z",
    "batch_set_id": "<string>",
    "binding_id": "<string>",
    "read_pin": "2023-11-07T05:31:56Z",
    "source": {
      "mode": "<string>",
      "fetched_at": "2023-11-07T05:31:56Z",
      "current": true,
      "freshness": "current",
      "stale_since": "2023-11-07T05:31:56Z"
    },
    "lens": {
      "target": "<string>",
      "display_name": "<string>",
      "scope_kind": "<string>"
    }
  },
  "duration_ms": 123,
  "data": [
    {
      "seq": 123,
      "command_id": "<string>",
      "actor_principal": "<string>",
      "actor_type": "<string>",
      "entity_domain": "<string>",
      "command": "<string>",
      "schema_rev": 123,
      "payload": {},
      "recorded_at": "2023-11-07T05:31:56Z",
      "connection_id": "<string>",
      "client_key": "<string>",
      "ams360_datasource": "<string>",
      "policy_id": "<string>",
      "app_entity_type": "<string>",
      "app_entity_id": "<string>",
      "catalog_entity_type": "<string>",
      "catalog_id": "<string>",
      "issued_at": "2023-11-07T05:31:56Z"
    }
  ],
  "next_seq": 123,
  "action_seq": 123,
  "limit": 123
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "unauthorized",
  "message": "Missing or invalid API key"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded"
}

{
  "code": "client_closed_request",
  "message": "The client closed the request before the book read finished"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "request_timeout",
  "message": "Request timed out"
}

Behavior

Page with since_seq: pass each response’s next_seq back until it is null. See Writes and the action ledger.

Authorizations

Authorization

string

header

required

Send the key as Authorization: Bearer <key>. Two kinds of key exist.

Organization keys are issued in the portal (Settings, then API keys), each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry no capabilities and pass every capability check, with one exception: routes under /api/v1/records, /api/v1/engines/{id}/opportunities, /api/v1/graph and /api/v1/catalog/documents accept an organization key only when its environment is live, and refuse any other with 403 scoped_key_required. Revocation takes effect within 60 seconds.

Scoped keys are issued by Nexio on request, shaped nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one org, one environment, a set of engines and a set of capabilities. A malformed, unknown or revoked nxsk_ key fails with 401 and is never retried as an organization key. Revocation takes effect on the next request. A scoped key without a route's capability gets 403 insufficient_capability; a scoped key not bound to the engine gets 403 engine_binding_forbidden.

Key-grantable capabilities: engines:read, runs:write, runs:read, runs:defensibility:read, runs:test, catalog:read, catalog:documents:read, webhooks:manage, conversations:use, conversations:export, records:read, records:opportunities:run, actions:write, actions:read, graph:read, records:analyze.

Routes that accept organization keys only (every scoped key gets 403 insufficient_capability): environment management, engine create, update, configuration and publish, and conversation instance authoring. Each operation description names the capability a scoped key needs.

Headers

X-Nexio-Acting-Principal

string

required

The person the request is for, as your identity provider's stable user id. Required on this route; without it the request answers 403 identity_unmapped. Narrows what the key reaches.

X-Nexio-Acting-Email

string

The acting person's verified sign-in email. The seat is derived from it.

X-Nexio-Records-Assertion

string

Signed assertion v1.<unix seconds>.<hex HMAC-SHA256> over acting_principal|acting_email|reserved|timestamp (each part trimmed, the email lowercased). The third field is reserved: send an empty string. The timestamp must be within 5 minutes of the server clock, either way. Checked once Nexio enables assertion verification for your organization, when it provisions the signing secret; a missing or wrong assertion then answers 403 assertion_invalid and one outside the window 403 assertion_stale.

X-Nexio-Records-Lens

string

principal:<id>: a read-only view of another person's data, honored only for a caller whose own scope is All or Platform and ignored for anyone else. For such a caller, a value that is not principal:<id>, or names nobody, answers 400 lens_target_unknown.

Query Parameters

since_seq

integer<int64>

default:0

Return commands with seq greater than this. Defaults to 0.

Required range: x >= 0

limit

integer

default:100

Rows per page. Defaults to 100; values above 500 are treated as 500.

Required range: x >= 1

family

string

Command family: the part of the command name before the first dot, for example note, task or status. Exact match; an unknown family returns no rows.

connection_id

string<uuid>

The system-of-record connection to use. Optional when the organization has exactly one qualifying connection; required when it has several (otherwise 400 book_connection_ambiguous). A connection that does not exist in the organization answers 404 not_found.

Response

One page of ledger rows.

serving

object

required

Hide child attributes

serving.overlay_rev

integer

required

Always 0 today.

Required range: x >= 0

serving.as_of

string<date-time>

required

The request's read time. Every Records read is a current read, queried live at request time and not held to a fixed warehouse instant. An empty page may carry either the request time or the zero time 0001-01-01T00:00:00Z. The action, note, task, workflow-state and edit-intent routes carry the zero time, even when their account or policy scope check queries the warehouse.

serving.batch_set_id

string

Not sent on current reads; present only on reads served from a stored copy.

serving.binding_id

string

The connection the read was served from.

serving.read_pin

string<date-time>

Not sent on Records reads, because no read is held to a fixed warehouse instant.

serving.source

object

Hide child attributes

serving.source.mode

string

required

query_first: read live from the warehouse at request time.

serving.source.fetched_at

string<date-time>

required

The request's read time, the same instant as as_of.

serving.source.current

boolean

true: the read queried the current data at request time. Source changes can show between separate statements in one response and between pages.

serving.source.freshness

enum<string>

Not sent on Records reads.

Available options:

current,

pinned

serving.source.stale_since

string<date-time>

Not sent on Records reads.

serving.lens

object

Hide child attributes

serving.lens.target

string

required

serving.lens.display_name

string

required

serving.lens.scope_kind

string

required

duration_ms

integer

required

data

object[]

required

Hide child attributes

data.seq

integer

required

data.command_id

string

required

data.actor_principal

string

required

data.actor_type

string

required

data.entity_domain

string

required

data.command

string

required

data.schema_rev

integer

required

data.payload

object

required

data.recorded_at

string<date-time>

required

data.connection_id

string

data.client_key

string

data.ams360_datasource

string

The source system's tenant key for the record (a field of the source system).

data.policy_id

string

data.app_entity_type

string

data.app_entity_id

string

data.catalog_entity_type

string

data.catalog_id

string

data.issued_at

string<date-time>

next_seq

integer | null

required

Pass back as since_seq for the next page. Null when the page was not full; a full last page still carries a value, and the next call returns no rows.

action_seq

integer

required

limit

integer

required

Rows returned on this page.

Last modified on September 25, 2026

Overview

Engines

Environments

Conversations

Webhooks

Events

Records

Graph

Platform

List ledger commands

Behavior

Authorizations

Headers

Query Parameters

Response

​Behavior

Authorizations

Headers

Query Parameters

Response

Behavior