List notes

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

import requests

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

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/notes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "duration_ms": 123,
  "data": [
    {
      "id": "<string>",
      "entity_type": "client",
      "author_principal": "<string>",
      "body": "<string>",
      "attach_status": "attached",
      "applied_seq": 123,
      "client_key": "<string>",
      "ams360_datasource": "<string>",
      "policy_id": "<string>",
      "applied_over_concurrent": true,
      "issued_at": "2023-11-07T05:31:56Z"
    }
  ],
  "action_seq": 123,
  "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>"
    }
  },
  "scope": {
    "kind": "Self",
    "selection": "own",
    "selection_source": "request"
  }
}

{
  "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

notes

List notes

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

import requests

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

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/notes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "duration_ms": 123,
  "data": [
    {
      "id": "<string>",
      "entity_type": "client",
      "author_principal": "<string>",
      "body": "<string>",
      "attach_status": "attached",
      "applied_seq": 123,
      "client_key": "<string>",
      "ams360_datasource": "<string>",
      "policy_id": "<string>",
      "applied_over_concurrent": true,
      "issued_at": "2023-11-07T05:31:56Z"
    }
  ],
  "action_seq": 123,
  "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>"
    }
  },
  "scope": {
    "kind": "Self",
    "selection": "own",
    "selection_source": "request"
  }
}

{
  "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"
}

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

connection_id

string

The system-of-record connection to read. Optional when the organization has exactly one qualifying connection; required when it has several (otherwise 400 book_connection_ambiguous).

client_key

string

One record by client key. Send this or policy_key, not both.

policy_key

string

One record by policy key.

Response

The current rows.

duration_ms

integer

required

data

object[]

required

Hide child attributes

data.id

string

required

data.entity_type

enum<string>

required

Available options:

client,

policy

data.author_principal

string

required

data.body

string

required

data.attach_status

enum<string>

required

Available options:

attached,

detached

data.applied_seq

integer

required

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.applied_over_concurrent

boolean

True when a later command already changed the same target.

data.issued_at

string<date-time>

action_seq

integer

required

serving

object

required

The connection the rows were read from (binding_id). On this route as_of and source.fetched_at are not a read time and are sent as 0001-01-01T00:00:00Z.

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

scope

object

required

Appended to Records read envelopes, except GET /records/actions, the /records/analyses routes and GET /records/status, which carries its own scope block. States the scope the rows were served at.

Hide child attributes

scope.kind

enum<string>

required

The resolved row scope.

Available options:

Self,

Office,

All,

Platform

scope.selection

enum<string>

required

The selection the rows were served under.

Available options:

own,

client_manager,

code,

boundary,

whole,

account,

office

scope.selection_source

enum<string>

required

Who chose the selection.

Available options:

request,

rls,

none

Last modified on September 25, 2026

Overview

Engines

Environments

Conversations

Webhooks

Events

Records

Graph

Platform

List notes

Authorizations

Headers

Query Parameters

Response