> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Append commands

> Record notes, tasks and status changes for a person in the action ledger.

## Behavior

Each command carries its own `idempotency_key`; resending an identical batch replays the original results with status 200. `actor_principal` must equal `X-Nexio-Acting-Principal` when that header is sent. Nothing is written to the system of record. See [Writes and the action ledger](/data-services/writes).


## OpenAPI

````yaml POST /api/v1/records/actions
openapi: 3.1.0
info:
  title: Nexio API
  version: '1.0'
  description: |
    The Nexio public API. Submit runs to configured engines and read their
    results, hold conversations with configured assistants, make authorized
    reads over the planes and families of a connected system of record, and
    manage webhooks and environments.

    Six engine types are registered: comparison, matching, entity_analysis,
    diligence, triage, and opportunity.

    Every route under /api/v1/ requires `Authorization: Bearer <key>`, except
    inbound event ingest (`POST /api/v1/events/ingest/{source_key}`), which
    authenticates each request against its ingest source instead: an
    HMAC-SHA256 signature for `nexio` and `github` sources, or a shared
    authentication code for an `ams360_ons` source. Error
    bodies share the `Error` schema. Call the API from servers only: it sends
    no CORS headers.
  contact:
    email: support@usenexio.com
    url: https://docs.usenexio.com
servers:
  - url: https://api.usenexio.com
    description: >-
      Nexio API. Sandbox or live is chosen by the API key's environment, not by
      the host.
security:
  - BearerAuth: []
tags:
  - name: EngineManagement
    description: >-
      Create, configure, version and manage engines. An engine is a
      configuration of one registered engine type.
  - name: Engines
    description: Engine-scoped endpoints for submitting runs and retrieving results.
  - name: Runs
    description: Retrieve and reconcile submitted runs.
  - name: Records
    description: >-
      Typed, authorized reads over the registered planes and families of a
      connected system of record, and governed writes to the action ledger. The
      generic family read is the core contract.
  - name: Graph
    description: >-
      The organization's data graph: a read-only map of connections and the
      derivations scheduled on them. Node kinds are a closed registry of 16; the
      API serves 14.
  - name: Environments
    description: >-
      The live environment and up to 5 sandbox environments in your org.
      Organization keys only.
  - name: Webhooks
    description: >-
      Manage webhook endpoints that receive terminal run events (run.completed,
      run.failed, run.cancelled) and run corrections (run.superseded).
  - name: Events
    description: >-
      Send inbound events to your organization's event log through an ingest
      source. Source kinds are nexio, github and ams360_ons; a nexio source
      sends event types from your own vocabulary.
  - name: Converse
    description: The raw stateless conversational model turn (caller-owned state).
  - name: Conversations
    description: >-
      Conversation instances (orchestrators over engines) and their managed
      conversations, turns, annotations, evals, and exports.
  - name: Platform
    description: Service health. No key needed.
paths:
  /api/v1/records/actions:
    post:
      tags:
        - Records
      summary: Append commands to the action ledger
      description: >-
        Records 1 to 20 commands for one person in one transaction: all are
        recorded or none. Each command addresses one system-of-record record the
        person may open (by `client_key` or `policy_key`), or (notes only) one
        Catalog entity. A Catalog target is not looked up or checked against the
        person's access, and a batch of only Catalog notes resolves no identity
        against the system of record. The command set is fixed in code: a batch
        that contains `source_activity.create` or `renewal_decision.set` is
        refused whole with 403 `overlay_read_only`, and the internal
        `book_edit_intent.*` commands answer 400 `action_schema_unknown`.
        Nothing is written to the connected system of record.


        Every command carries an `idempotency_key` (UUID). Resending a command
        with the same key, command, `schema_rev`, target, `payload`, `basis` and
        `actor_principal` returns its original `command_id` and `seq` with
        `idempotent_replay: true` and status 200 (`id` and `issued_at` are not
        compared). Reusing a key with any of those different answers 400
        `action_payload_invalid`. A session with `X-Nexio-Records-Lens` cannot
        write.


        Credential: the organization's live API key, or a scoped key with
        `actions:write`.
      operationId: appendRecordsActions
      parameters:
        - name: X-Nexio-Acting-Principal
          in: header
          required: false
          description: >-
            The person the request is for, as your identity provider's stable
            user id. Optional on this route; when absent, the body's
            `actor_principal` is used. When both are sent they must match, or
            the request answers 400 `invalid_request`. Narrows what the key
            reaches.
          schema:
            type: string
        - name: X-Nexio-Acting-Email
          in: header
          required: false
          description: >-
            The acting person's verified sign-in email. The seat is derived from
            it.
          schema:
            type: string
        - name: X-Nexio-Records-Assertion
          in: header
          required: false
          description: >-
            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`.
          schema:
            type: string
        - name: X-Nexio-Records-Lens
          in: header
          required: false
          description: >-
            Do not send on this route. Any non-empty value refuses the write
            with 403 `book_lens_read_only`.
          schema:
            type: string
        - name: connection_id
          in: query
          required: false
          description: >-
            The system-of-record connection to use when a command addresses a
            system-of-record record. Optional when the organization has exactly
            one qualifying connection; required when it has several (otherwise
            400 `book_connection_ambiguous`). Ignored for a batch of Catalog
            notes only. A connection that does not exist in the organization
            answers 404 `not_found`.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordsActionsAppendRequest'
      responses:
        '200':
          description: The recorded (or replayed) commands.
          headers:
            X-Nexio-Engine-Build:
              description: >-
                The engine commit that computed this response, when the build is
                stamped. Key caches on it.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordsActionsAppendResponse'
        '400':
          description: >-
            `invalid_request` (body is not one JSON value or is over 1 MiB,
            `actor_principal` missing, `actor_type` not `producer` or `agent`,
            no commands or more than 20, `X-Nexio-Acting-Principal` differs from
            `actor_principal`, a command that does not name exactly one target,
            a key that does not decode, or `connection_id` not a UUID),
            `action_schema_unknown` (unknown command or `schema_rev`),
            `action_payload_invalid` (payload, `id` or `idempotency_key`
            invalid, a target type the command does not accept, or an
            idempotency key reused for a different command), or
            `book_connection_ambiguous`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            `action_out_of_scope` (a target the person may not open),
            `overlay_read_only`, `book_lens_read_only`,
            `insufficient_capability`, `scoped_key_required`, `dataset_denied`,
            or an identity refusal (`identity_unmapped`,
            `identity_needs_review`, `identity_suspended`, `identity_stale`,
            `scope_unavailable`, `assertion_invalid`, `assertion_stale`,
            `service_identity_unknown`). Identity and policy checks run only
            when a command addresses an account or policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            `not_found`: the named connection does not exist in this
            organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `book_unavailable`: the connected data cannot be read now to check
            the addressed records. `details.reason` names the warehouse cause
            when there is one; no reason means no qualifying connection exists
            yet. Nothing was recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '499':
          $ref: '#/components/responses/ClientClosedRequest'
        '500':
          description: >-
            `audit_write_failed` (nothing was recorded), `book_key_ambiguous` (a
            key matched more than one record), or `internal_error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >
            `book_unavailable` with `details.reason: busy` when the warehouse
            statement queue is full, or `resolve_retry_exhausted`. Retry the
            same request; it is idempotent.


            Also `auth_unavailable`: API key authentication was briefly
            unavailable before the route ran. That cause is transient; retry it
            with backoff.
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Sent with `book_unavailable`
                reason `busy`.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          $ref: '#/components/responses/RequestTimeout'
      security:
        - BearerAuth: []
components:
  schemas:
    RecordsActionsAppendRequest:
      type: object
      properties:
        actor_principal:
          type: string
          description: >-
            The person the commands are for. Must equal
            `X-Nexio-Acting-Principal` when that header is sent.
        actor_type:
          type: string
          enum:
            - producer
            - agent
          description: >-
            `producer` for a person, `agent` for an AI agent acting for that
            person.
        commands:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/RecordsActionCommand'
      required:
        - actor_principal
        - actor_type
        - commands
    RecordsActionsAppendResponse:
      type: object
      properties:
        duration_ms:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/RecordsActionResult'
        action_seq:
          type: integer
          description: The ledger's latest sequence number.
        serving:
          allOf:
            - $ref: '#/components/schemas/RecordsServing'
          description: Absent when every command addresses a Catalog entity.
        scope:
          $ref: '#/components/schemas/RecordsScope'
      required:
        - duration_ms
        - results
        - action_seq
        - scope
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >
            Stable snake_case error identifier. Safe to match programmatically.

            New codes are added over time; treat an unknown code by its HTTP
            status.


            Known codes include:

            `invalid_request`, `invalid_input`, `unauthorized`,

            `auth_unavailable`, `rate_limited`, `missing_run_id`,

            `invalid_run_id`, `run_not_found`, `invalid_offerings`,

            `missing_input`, `queue_unreachable`, `engine_not_found`,

            `engine_slug_conflict`, `engine_archived`, `instance_not_found`,

            `instance_slug_conflict`, `instance_archived`,

            `instance_follows_canonical`, `instance_not_published`,

            `invalid_engine_type`, `validation_error`, `webhook_not_found`,

            `webhook_limit_exceeded`, `invalid_url`, `invalid_events`,

            `invalid_description`, `invalid_auth_token`,

            `missing_endpoint_id`, `invalid_endpoint_id`,

            `missing_delivery_id`, `invalid_delivery_id`,

            `delivery_not_found`, `delivery_not_resendable`,

            `insufficient_capability`, `engine_version_required`,

            `engine_version_exact_required`, `engine_version_not_found`,

            `engine_version_invalid_format`,

            `engine_version_draft_requires_sandbox_key`,

            `engine_version_none_released`, `test_scenario_sandbox_only`,

            `test_scenario_forbidden`, `test_scenario_exact_version_required`,

            `test_scenario_version_not_supported`, `invalid_test_scenario`,

            `request_bound_exceeded`, `run_cap_exceeded`,

            `scoped_key_required`, `engine_binding_forbidden`,

            `request_timeout`, `internal_error`, `idempotency_key_reused`,

            `invalid_idempotency_key`, `acting_principal_mismatch`,

            `run_requires_acting_principal`, `environment_slug_invalid`,

            `environment_slug_reserved`, `environment_slug_taken`,

            `environment_name_invalid`, `environment_limit_reached`,

            `environment_live_immutable`, `environment_not_found`,

            `environment_in_use`, `environment_operation_failed`,

            `list_environments_failed`, `engine_release_unservable`,

            `engine_config_hash_inconsistent`,

            `engine_config_hash_unavailable`,

            `engine_config_version_unavailable`,

            `engine_version_resolve_failed`,

            `engine_config_version_load_failed`,

            `engine_version_publish_mismatch`,

            `engine_version_schema_change_requires_major`,

            `engine_config_hash_missing`, `engine_config_changed`,

            `invalid_engine_config`, `cold_start_gate_not_met`,

            `cold_start_gate_failed`, `cold_start_gate_regressed`,

            `cancel_run_failed`, `event_id_reused`, `invalid_event_id`,

            `missing_event_id`, `invalid_event_type`, `invalid_payload`,

            `reason_text_too_long`, `reason_taxonomy_version_unknown`,

            `invalid_rating`, `missing_comment`, `invalid_target`,

            `invalid_time_on_task`, `scoped_annotation_required`,

            `missing_instance_slug`, `invalid_instance_config`,

            `invalid_eval_waiver`, `instance_config_hash_missing`,

            `config_changed_during_publish`,

            `scenario_set_changed_during_publish`,

            `conversation_eval_regressed`,

            `conversation_eval_execution_failed`,

            `conversation_eval_gate_unavailable`, `publish_failed`,

            `conversation_not_found`, `conversation_archived`,

            `invalid_cursor`, `message_not_found`, `invalid_turn_request`,

            `message_too_long`, `invalid_tool_result`, `invalid_confirmation`,

            `invalid_edit_target`, `turn_in_progress`, `pending_turn`,

            `turn_state_conflict`, `confirmation_environment_unpinned`,

            `instance_config_missing`, `instance_config_invalid`,

            `instance_model_unavailable`, `guardrail_evaluation_failed`,

            `guardrail_config_invalid`, `invalid_conversation_history`,

            `streaming_unsupported`, `converse_unavailable`, `provider_error`,

            `provider_unavailable`, `unknown_model`, `too_many_messages`,

            `too_many_tools`, `invalid_max_tokens`, `invalid_message_role`,

            `invalid_message`, `invalid_content_block`, `invalid_tool`,

            `attachments_not_enabled`, `attachments_unavailable`,

            `attachment_rejected`, `attachment_too_large`,

            `attachments_too_large`, `too_many_attachments`,

            `attachment_not_accepted`, `attachment_not_found`,

            `attachment_changed`, `attachment_read_failed`,

            `attachment_member_delete`, `attachment_not_reservable`,

            `invalid_offset`, `invalid_turn_id`, `invalid_comment`,

            `invalid_reason`, `invalid_feedback_key`, `turn_not_found`,

            `annotation_not_found`, `annotation_not_promotable`,

            `invalid_eval_scenario`, `conversation_eval_scenario_not_found`,

            `conversation_eval_scenario_cap`,

            `conversation_eval_run_not_found`,

            `conversation_eval_baseline_not_found`,

            `conversation_eval_unavailable`,

            `instance_version_invalid_format`, `instance_version_not_found`,

            `document_class_not_open`, `presign_failed`,

            `markets_directory_unavailable`, `book_unavailable`,

            `book_connection_ambiguous`, `identity_unmapped`,

            `identity_needs_review`, `identity_suspended`, `identity_stale`,

            `scope_unavailable`, `assertion_invalid`, `assertion_stale`,

            `cursor_filter_mismatch`, `cursor_expired`,

            `action_schema_unknown`, `action_payload_invalid`,

            `action_out_of_scope`, `action_list_too_large`,

            `overlay_read_only`, `unsupported_node_type`,

            `acting_principal_required`, `action_denied`,

            `appetite_read_denied`, `approval_required`,

            `catalog_access_denied`, `catalog_connection_ambiguous`,

            `create_webhook_failed`, `dataset_denied`, `delivery_id_reused`,

            `document_type_not_servable`, `document_unclassified`,

            `egress_manifest_version_mismatch`,

            `egress_manifest_version_required`, `event_type_not_allowed`,

            `event_type_reserved`, `execution_confirm_required`,

            `execution_prohibited`, `ingest_source_disabled`,

            `ingest_source_misconfigured`, `ingest_source_not_found`,

            `invalid_acting_assertion`, `invalid_active`,

            `invalid_credentials`, `invalid_payload_mode`,

            `invalid_signature`, `load_run_failed`, `load_solutions_failed`,

            `load_work_items_failed`, `missing_engine_slug`, `not_found`,

            `object_store_unconfigured`, `provider_not_approved`,

            `resolve_retry_exhausted`, `run_lookup_failed`,

            `service_identity_unknown`, `stale_timestamp`, `surface_denied`,

            `unresolved_market_question`, `unsupported_market_filter`.


            The full list with causes and fixes is at

            https://docs.usenexio.com/reference/errors.
        message:
          type: string
          description: Human-readable error message. May change between versions.
        details:
          description: |
            Optional request-specific details. Request-bound failures use the
            `RequestBoundDetails` object. Validation failures may use an array
            of field issues or another documented object.

            `409 environment_in_use` is the one exception to this envelope: it
            carries a top-level `blockers` object (see `EnvironmentInUseError`)
            instead of `details`.
    RecordsActionCommand:
      type: object
      properties:
        id:
          type: string
          description: >-
            Optional command id (UUID). Generated when omitted; becomes the note
            or task id on a create.
        command:
          type: string
          enum:
            - note.create
            - note.edit
            - note.delete
            - task.create
            - task.edit
            - task.assign
            - task.complete
            - task.reopen
            - task.delete
            - status.set
            - source_activity.create
            - renewal_decision.set
          description: >-
            `source_activity.create` and `renewal_decision.set` always refuse
            the batch with 403 `overlay_read_only`.
        schema_rev:
          type: integer
          enum:
            - 1
          description: Always 1. Any other value answers 400 `action_schema_unknown`.
        client_key:
          type: string
          description: >-
            Target record by client key (a top-level record of the system of
            record). Send exactly one of `client_key`, `policy_key`, or
            `catalog_entity_type` with `catalog_id` (400 `invalid_request`
            otherwise).
        policy_key:
          type: string
          description: Target record by policy key.
        catalog_entity_type:
          type: string
          description: Target Catalog entity type (notes only), with `catalog_id`.
        catalog_id:
          type: string
        payload:
          type: object
          additionalProperties: true
          description: >-
            Command payload, validated strictly, at most 32 KiB. See the writes
            guide for each command's fields.
        basis:
          $ref: '#/components/schemas/RecordsActionBasis'
        idempotency_key:
          type: string
          description: >-
            A UUID unique across the organization's ledger. Resending it with
            the identical command replays the original result.
        issued_at:
          type: string
          format: date-time
      required:
        - command
        - schema_rev
        - payload
        - idempotency_key
    RecordsActionResult:
      type: object
      properties:
        command_id:
          type: string
        seq:
          type: integer
        idempotent_replay:
          type: boolean
          description: >-
            Present and true only when this command was a replay of an earlier
            identical command; absent otherwise.
      required:
        - command_id
        - seq
    RecordsServing:
      type: object
      additionalProperties: false
      required:
        - overlay_rev
        - as_of
      properties:
        batch_set_id:
          type: string
          description: >-
            Not sent on current reads; present only on reads served from a
            stored copy.
        binding_id:
          type: string
          description: The connection the read was served from.
        overlay_rev:
          type: integer
          minimum: 0
          description: Always 0 today.
        as_of:
          type: string
          format: date-time
          description: >-
            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.
        read_pin:
          type: string
          format: date-time
          description: >-
            Not sent on Records reads, because no read is held to a fixed
            warehouse instant.
        source:
          type: object
          additionalProperties: false
          required:
            - mode
            - fetched_at
          properties:
            mode:
              type: string
              description: 'query_first: read live from the warehouse at request time.'
            current:
              type: boolean
              description: >-
                `true`: the read queried the current data at request time.
                Source changes can show between separate statements in one
                response and between pages.
            freshness:
              type: string
              enum:
                - current
                - pinned
              description: Not sent on Records reads.
            fetched_at:
              type: string
              format: date-time
              description: The request's read time, the same instant as `as_of`.
            stale_since:
              type: string
              format: date-time
              description: Not sent on Records reads.
        lens:
          type: object
          additionalProperties: false
          required:
            - target
            - display_name
            - scope_kind
          properties:
            target:
              type: string
            display_name:
              type: string
            scope_kind:
              type: string
    RecordsScope:
      type: object
      properties:
        kind:
          type: string
          enum:
            - Self
            - Office
            - All
            - Platform
          description: The resolved row scope.
        selection:
          type: string
          enum:
            - own
            - client_manager
            - code
            - boundary
            - whole
            - account
            - office
          description: The selection the rows were served under.
        selection_source:
          type: string
          enum:
            - request
            - rls
            - none
          description: Who chose the selection.
      required:
        - kind
        - selection
        - selection_source
      description: >-
        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.
    RecordsActionBasis:
      type: object
      properties:
        batch_set_id:
          type: string
        overlay_rev:
          type: integer
        seq:
          type: integer
          description: >-
            The ledger position the person was looking at (a previous
            `action_seq`).
      description: >-
        What the person was looking at when the command was issued. Recorded and
        compared on replay; never a reason to refuse. Missing numbers are
        recorded as 0.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: Missing or invalid API key
    RateLimited:
      description: Rate limit exceeded. Retry after the window resets.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limited
            message: Rate limit exceeded
    ClientClosedRequest:
      description: |
        `client_closed_request`: the caller closed the connection before the
        read finished. Nothing reads this body; it exists so the abandoned
        read is recorded as 499 rather than as a server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: client_closed_request
            message: The client closed the request before the book read finished
    RequestTimeout:
      description: >-
        `request_timeout`: the 30 second route timeout expired before the
        handler answered.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: request_timeout
            message: Request timed out
  headers:
    RetryAfter:
      description: Whole seconds to wait before retrying, at least 1.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >
        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.

````