Profile is a label these docs use for one configured instance of these primitives; it is not an API object.
How the primitives connect
- Nexio connects to a system you own and reads from it. It does not write changes back to that system. The one caution is an HTTP API connection’s validation probe, which sends the test request you configure with the method you choose, so configure one that changes nothing (Connections).
- Documents are indexed and their facts extracted with a quote from the source. Uncertain facts go to human review.
- Your server submits a run to an engine, or reads and writes records through Records, with an API key.
- The run finishes. You poll it or receive a signed webhook.
- People review results in the portal, and your systems report what happened next. Evaluations use both to gate new engine versions.
Organizations and environments
An organization (org) is the tenant. Everything you create in Nexio belongs to one org, and every authenticated request belongs to the org its API key proves. You never send an org ID in a request body. An environment separates live traffic from test traffic inside an org. There are two kinds:live (exactly one per org, created by Nexio) and sandbox (up to 5 per org, created by you). Runs, webhook endpoints and conversations belong to the environment of the key that created them.
Status: the two environment kinds are fixed. You create and delete sandboxes. See Environments.
Credentials and capabilities
A credential proves which org and environment a request belongs to. There are two kinds of API key: an organization key you create in the portal, and a scoped key Nexio issues, bound to a set of engines and a set of capabilities. A capability names one thing a scoped key may do, such asruns:write or graph:read.
A request can also act for a person in your org, the acting principal, sent in X-Nexio-Acting-Principal. It can only narrow what the key allows.
Status: Nexio ships a fixed set of capabilities that a key can carry, and each public route names the one it needs. Three of them, records:read, records:opportunities:run and records:analyze, share the /api/v1/records route prefix. See Authentication and access.
Engines and engine types
An engine is a configured capability. It takes a typed input and returns a typed output. Each engine has a stable slug, an engine type, a draft configuration, and released, immutable versions. An engine type defines how an engine of that type runs: how its configuration is validated, its default configuration, and the schemas of its input and output. When you create an engine, Nexio checks the type and seeds the type’s default configuration. The output schema is declared by the type and completed from the engine’s configuration, so an engine’s contract is known before it runs. A declared-contract engine goes one step further: its configuration states the input schema and the output contract itself. Status: engine types are a fixed set Nexio ships, and adding a type is a Nexio release. Six types exist today:comparison, matching, entity_analysis, diligence, triage and opportunity. Engines are configuration: you create, configure and version them. See Engines and Declared-contract engines.
Runs
A run is one execution of one engine version on one input. You submit it, it moves fromqueued to processing, and it ends as completed, degraded, failed or cancelled. A run records the engine version and the configuration hash it used. A retried submission with the same Idempotency-Key and the same body returns the same run instead of creating a second one.
After a run, your systems report outcomes (what happened next, such as a person viewing, accepting or overriding the answer) and people leave annotations (ratings and comments). Where an engine provides one, a defensibility packet records how the answer was sourced.
Status: the run lifecycle is the same for every engine type. The outcome payload field names and override reasons are a fixed set; see Outcomes and annotations. See Runs and Defensibility and trace.
Evaluation and release gates
An eval set is a fixed set of reference cases. Publishing a new engine version runs the release gate on the candidate. An engine with no eval set publishes without a gate. With eval sets, a first release needs a pass on every set that declares a threshold, or a clean evaluation when none does, and a later release is blocked only by sets that declare a threshold. Publishing a conversation instance version runs its own evaluation gate. Nexio can also draft an improvement to an engine’s configuration as a proposal, which a person approves or rejects. Status: the same mechanism for every engine type and every conversation instance. See Evaluation and Versions and releases.Conversations
A conversation instance is a configured assistant: its instructions, the model it uses, the tools and engines it may call, the data it may read, its guardrails and its retention. Its configuration is validated and released as immutable versions. A conversation is one end user’s exchange with a released version, made of turns that stream back as server-sent events. Status: you configure instances; each org has its own. See Conversations.Connections
A connection binds the platform to one of your systems: a document library such as SharePoint, a warehouse such as Snowflake, a PostgreSQL database, an HTTP API or an MCP server. You supply credentials and scope. Nexio configures, validates and monitors the connection for you. Status: connection types are a fixed set Nexio ships, and adding a type is a Nexio release. Connections themselves are configuration. See Connections and Connectors.Document indexing and extraction
Indexing reads a connection’s documents, classifies each one into a document class, and routes each class to an extraction pass. An extraction pass reads typed facts, each with a quote from its source. An indexing profile decides the routing. A connection with no profile of its own uses the built-in profile. Status: one instance today. The routing is the mechanism. The document classes and extraction passes a profile can use are fixed, and adding one is a Nexio release. See Indexing and extraction.Served data
Served data is the platform’s model for records extracted from documents. A served record is effective-dated: a change closes the current version and writes a new one. A citation points an extracted value back to the document, and where known the page and region, it came from. A read can pin one connection, and on the reads that apply field removal, values the acting person may not see are withheld. Status: the served-record model is the same for every record. See Served data.Records: planes and families
Records is the platform’s typed, authorized read and write layer over a connected system of record, the system your org treats as the source of truth for its records. A plane is one source schema. A family is one named dataset on a plane, with a serve grain and a declared column set.GET /api/v1/records/families/{plane}/{family} reads any registered family with the same request and a columnar response. An unregistered pair answers 404 not_found.
Status: planes and families are a registry Nexio ships, and a registered family serves through the same read with no new route. The planes are defined per connected system type. See Records and Families.
Completeness
Every Records read, and every family inside a composite read, ends in one outcome: complete, a bounded page, partial, unavailable with a reason, never supplied, or refused. Each outcome has its own signal on the wire, so an empty result can be told apart from an unavailable or refused one. Status: one contract for every family. See Completeness and errors.Writes and the action ledger
A governed write is a command, appended to your org’s action ledger with an idempotency key. Current state is read back from the ledger. Nothing is written to the system of record: routes and commands that would change it answer403 overlay_read_only.
Status: the ledger, idempotency and batching are the same for every command. Commands are a fixed set Nexio ships. You send notes, tasks and status commands; the others are internal. See Writes and the action ledger.
Access plane
The access plane applies your own access rules to every Records read and write under thelit posture. Who is signing in comes from your identity provider, who the person is from your HR directory, what they may do and see from their security groups in your system of record, and which records they may open from its business-unit access. Nexio holds the mapping from those to the platform’s roles, field classes and row scopes, and reads your sources at the moment the person asks. The result is the person’s seat, their authority in your org. An org’s posture (dark, shadow or lit) decides whether reads are served from the seat or from the earlier identity mapping.
Status: the mechanism is the same for every org. The platform’s roles, field classes and workflows are a fixed set Nexio ships. Exceptions, assignments and added grants are set with your organization’s own live key or by a person your organization has delegated as an access administrator; Nexio sets them only when you ask. Every access change is audited. See Access plane and Authority and scope.
Events, automations and webhooks
A platform event is a fact recorded in your org’s event log, such as a sync finishing or a document changing. A subscription matches an event type exactly, or a family of types with a trailing wildcard (sync.*), or fires on a schedule, and runs an effect. An ingest source lets your systems append events through POST /api/v1/events/ingest/{source_key}. The event types a source accepts are set when it is registered, and must not be one of the types Nexio reserves for its own events.
A webhook is a signed HTTP call Nexio sends to your endpoint when a run finishes or a finished result is corrected.
Status: effects are a fixed set of four (run_engine, deliver_webhook, emit_event, run_eval_set). Webhook event types are a fixed set of four run events. Ingest source kinds are a fixed set of three: nexio, github, and ams360_ons, for AMS360, a supported system type. Subscriptions, schedules and ingest sources are configuration, set up by Nexio for your org. See Events and webhooks.
Data graph and application records
The data graph is a read-only map of your org’s data, served under/api/v1/graph. Today it shows your connections and the derivations (datasets published on a schedule) that run on them. Application records are a generic row store for applications Nexio hosts.
Status: graph node kinds are a fixed set Nexio ships. Application records serve a fixed list of Nexio-hosted applications and are not an integration surface. See Graph and Application records.
Security and data handling
Where your data goes, how it is encrypted, which model providers receive it and how long it is kept are on Security and compliance. The list of processors is on Data use.Realtime is not a public contract
The portal updates live through Pusher messages on a private channel per organization. A client that is not connected when a message is sent does not receive it later, and the message names and payloads change with the portal’s needs. They are not versioned and not part of the API. Build integrations on webhooks and polling. PollGET /api/v1/runs/{run_id} for run state, and use webhooks to learn when to poll.
Next
Quickstart
Submit your first run.
Authentication and access
Which credential each part of the platform accepts.
Glossary
Every platform term, defined once.
Engines
The engine model, engine types and configuration.