API docs by Redocly

AI Assistant (1.0.0)

Download OpenAPI specification:

License: License Agreement

Inference

Stateless, single-shot inference (redaction, Q&A, change analysis, chat completions).

Server info

Returns version and feature-flag information about the AIAv2 API server.

Authorizations:
ApiAuthToken

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "langgraph_js_version": "string",
  • "context": "string",
  • "flags": {
    }
}

Analyze documents for redaction

Analyzes the given documents and suggests redaction annotations based on the redaction criteria. Works with or without a database. Accepts JSON or, for the database-less configuration, multipart/form-data (a file blob plus a data field).

Authorizations:
ApiAuthToken
Request Body schema:
required
model
string

Optional model id (e.g. "gpt4").

required
Array of objects (DocumentInput) non-empty
criteria
required
string

The redaction criteria, e.g. "PII" or "the word SECRET".

object

Responses

Request samples

Content type
{
  • "model": "string",
  • "documents": [
    ],
  • "criteria": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "stagedActions": [
    ]
}

Question-answering over documents

Performs single-shot question-answering across one or more documents, retrieving relevant context to generate an answer. Works with or without a database. Accepts JSON or, for the database-less configuration, multipart/form-data.

Authorizations:
ApiAuthToken
Request Body schema:
required
required
Array of objects (DocumentInput) non-empty
input
required
string

The question to ask about the document(s).

model
string

Optional model id (e.g. "gpt4").

Responses

Request samples

Content type
{
  • "documents": [
    ],
  • "input": "string",
  • "model": "string"
}

Response samples

Content type
application/json
{
  • "content": "string",
  • "references": [
    ]
}

Summarize and categorize document changes

Provides an LLM-based summary of what changed plus up to five suggested categories, intended for use as user preferences in a follow-up tagging request. Stateless; no changes are stored.

Authorizations:
ApiAuthToken
Request Body schema: application/json
required
required
Array of objects (DocumentChange)
model
string

Optional LLM model id (e.g. "gpt4o").

Responses

Request samples

Content type
application/json
{
  • "changes": [
    ],
  • "model": "string"
}

Response samples

Content type
application/json
{
  • "summary": "string",
  • "categories": [
    ]
}

Tag document changes

Categorizes document changes against a list of user-defined labels and returns each change with its matching categories. Stateless; no changes are stored.

Authorizations:
ApiAuthToken
Request Body schema: application/json
required
required
Array of objects (DocumentChange)
tags
required
Array of strings

Categories to tag the changes with.

model
string

Responses

Request samples

Content type
application/json
{
  • "changes": [
    ],
  • "tags": [
    ],
  • "model": "string"
}

Response samples

Content type
application/json
{
  • "references": [
    ]
}

Chat completions

OpenAI-compatible chat completions. Supports both simple chat and document-grounded responses. Provide documents to ground the answer on ingested document content.

Authorizations:
ApiAuthToken
Request Body schema: application/json
required
model
string

Optional model id (e.g. "gpt4").

required
Array of objects
Array of objects
temperature
number

Controls randomness (0-1, default 0.7).

nutrient_dont_send_defaults
boolean

Skip sending default parameters to the model (some deployments hang otherwise).

Responses

Request samples

Content type
application/json
{
  • "model": "string",
  • "messages": [
    ],
  • "documents": [
    ],
  • "temperature": 0,
  • "nutrient_dont_send_defaults": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "chat.completion",
  • "created": 0,
  • "model": "string",
  • "choices": [
    ],
  • "usage": {
    }
}

Runs

Agent execution (stateless and threaded) on the AIAv2 API.

Stream a run within a thread (SSE)

Stream a run within an existing thread context via Server-Sent Events. State is persisted to the thread, and the run supports interrupts. See the stateless /runs/stream endpoint for the event format.

Authorizations:
ApiAuthToken
path Parameters
thread_id
required
string
Request Body schema: application/json
required
Any of
assistant_id
required
string

LangGraph-compatible assistant ID of the agent to execute. Provide at least one of assistant_id / agent_id; both identify the same agent, so if both are supplied they must refer to the same agent.

agent_id
string

Product-facing agent ID of the agent to execute. Provide at least one of assistant_id / agent_id; both identify the same agent, so if both are supplied they must refer to the same agent.

input
any

Input for the agent. For the default agent this is { messages: [...] } (each message { role, content }), optionally with documents.

object (RecordStringUnknown)
object (RecordStringUnknown)
object

Per-run context fields, e.g. modelServices (gated by JWT claims).

object (RecordStringUnknown)
StreamMode (string) or Array of StreamMode (strings)

Which events to emit. A single mode or an array of modes.

string or Array of strings
string or Array of strings
feedback_keys
Array of strings
stream_subgraphs
boolean
checkpoint_id
string
object (RecordStringUnknown)

Responses

Request samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "input": {
    },
  • "command": { },
  • "config": { },
  • "context": { },
  • "metadata": { },
  • "stream_mode": [
    ],
  • "interrupt_before": "*",
  • "interrupt_after": "*",
  • "feedback_keys": [
    ],
  • "stream_subgraphs": true,
  • "checkpoint_id": "string",
  • "checkpoint": { }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": [
    ]
}

Execute a stateless run and stream results (SSE)

Execute an agent and stream results via Server-Sent Events. Stateless: no conversation state is persisted. The first event is metadata ({ run_id, attempt }); subsequent events depend on stream_mode (values, messages/partial, messages/complete, updates, debug), ending on completion or an error event. Maximum stream duration is 5 minutes.

Note: JWTs with session_ids claims are not compatible with this endpoint.

Authorizations:
ApiAuthToken
Request Body schema: application/json
required
Any of
assistant_id
required
string

LangGraph-compatible assistant ID of the agent to execute. Provide at least one of assistant_id / agent_id; both identify the same agent, so if both are supplied they must refer to the same agent.

agent_id
string

Product-facing agent ID of the agent to execute. Provide at least one of assistant_id / agent_id; both identify the same agent, so if both are supplied they must refer to the same agent.

input
any

Input for the agent. For the default agent this is { messages: [...] } (each message { role, content }), optionally with documents.

object (RecordStringUnknown)
object (RecordStringUnknown)
object

Per-run context fields, e.g. modelServices (gated by JWT claims).

object (RecordStringUnknown)
StreamMode (string) or Array of StreamMode (strings)

Which events to emit. A single mode or an array of modes.

string or Array of strings
string or Array of strings
feedback_keys
Array of strings
stream_subgraphs
boolean
checkpoint_id
string
object (RecordStringUnknown)

Responses

Request samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "input": {
    },
  • "command": { },
  • "config": { },
  • "context": { },
  • "metadata": { },
  • "stream_mode": [
    ],
  • "interrupt_before": "*",
  • "interrupt_after": "*",
  • "feedback_keys": [
    ],
  • "stream_subgraphs": true,
  • "checkpoint_id": "string",
  • "checkpoint": { }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": [
    ]
}

Execute a stateless run and wait for result

Execute an agent to completion and return the final graph state as JSON.

This endpoint runs in stateless mode: an ephemeral thread is created for the execution and deleted after completion. No conversation state is persisted.

Response modes:

  • Keep-alive (default): Uses chunked transfer encoding. Newline characters (\n) are sent every second to prevent proxy/load balancer timeouts. The final JSON result is appended after execution completes. The response is transparent to JSON.parse() since leading whitespace is ignored.

  • Pure JSON: Send Accept: application/json header. Returns a standard JSON response with no newline padding. Simpler but may timeout on long-running agents behind proxies.

Error handling:

  • Pre-execution errors (validation, auth, not found) return standard JSON error responses (400/401/404).
  • Execution errors in keep-alive mode return { "__error__": { "error": "...", "message": "..." } } in the response body.
  • Execution errors in pure JSON mode return standard JSON error responses.

Headers:

  • Content-Location: /runs/{run_id} is set before execution begins.

Maximum execution time is 5 minutes.

Note: JWTs with session_ids claims are not compatible with this endpoint.

Authorizations:
ApiAuthToken
Request Body schema: application/json
required

Request body for creating a stateless run.

Any of
assistant_id
required
string

LangGraph-compatible assistant ID of the agent to execute. Provide at least one of assistant_id / agent_id; both identify the same agent, so if both are supplied they must refer to the same agent.

agent_id
string

Product-facing agent ID of the agent to execute. Provide at least one of assistant_id / agent_id; both identify the same agent, so if both are supplied they must refer to the same agent.

input
any

Input data for the agent. Structure depends on the agent's input schema.

For the default Nutrient assistant agent, the input object supports:

  • messages — Array of chat messages. Each message has role ("user" or "assistant") and content (string).
  • documents — Optional array of document context objects that scope which documents the agent can access. Each entry has a fingerprint (document ID string or "*" for all JWT-permitted documents) and a role ("active" for primary documents or "available" for secondary reference).
object

Runtime configuration overrides merged into the agent's default configuration.

object

Arbitrary metadata attached to the run. Not processed by the server.

Responses

Request samples

Content type
application/json
{
  • "assistant_id": "nutrient-assistant",
  • "agent_id": "contract-review",
  • "input": {
    },
  • "config": { },
  • "metadata": { }
}

Response samples

Content type
application/json
Example
{
  • "__error__": {
    }
}

Threads

Conversation threads and their persisted state (AIAv2 API).

Create a thread

Create a new conversation thread.

Authorizations:
ApiAuthToken
Request Body schema: application/json
optional
thread_id
string

Optional client-supplied thread id. Generated if omitted.

object (RecordStringUnknown)
if_exists
string
Enum: "raise" "do_nothing"

Behaviour when a thread with the given id already exists.

Responses

Request samples

Content type
application/json
{
  • "thread_id": "string",
  • "metadata": { },
  • "if_exists": "raise"
}

Response samples

Content type
application/json
{
  • "thread_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "status": "idle"
}

Search threads

Search threads with filtering and pagination.

Authorizations:
ApiAuthToken
Request Body schema: application/json
optional
object (RecordStringUnknown)
ids
Array of strings
status
string
Enum: "idle" "busy" "interrupted" "error"
object (RecordStringUnknown)
limit
integer [ 1 .. 1000 ]
offset
integer >= 0
sort_by
string
Enum: "thread_id" "status" "created_at" "updated_at"
sort_order
string
Enum: "asc" "desc"

Responses

Request samples

Content type
application/json
{
  • "metadata": { },
  • "ids": [
    ],
  • "status": "idle",
  • "values": { },
  • "limit": 1,
  • "offset": 0,
  • "sort_by": "thread_id",
  • "sort_order": "asc"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get a thread

Get thread details.

Authorizations:
ApiAuthToken
path Parameters
thread_id
required
string

Responses

Response samples

Content type
application/json
{
  • "thread_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "status": "idle"
}

Delete a thread

Delete a thread and its persisted state.

Authorizations:
ApiAuthToken
path Parameters
thread_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": [
    ]
}

Get thread state

Get the current state of a thread.

Authorizations:
ApiAuthToken
path Parameters
thread_id
required
string
query Parameters
subgraphs
boolean

Include subgraph states.

Responses

Response samples

Content type
application/json
{
  • "values": { },
  • "next": [
    ],
  • "checkpoint": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "parent_checkpoint": { },
  • "tasks": [
    ]
}

Get thread state history

Get thread state history with filtering.

Authorizations:
ApiAuthToken
path Parameters
thread_id
required
string
Request Body schema: application/json
optional
limit
integer [ 1 .. 100 ]
string or RecordStringUnknown (object)

Return states before this checkpoint id (string) or checkpoint object.

object (RecordStringUnknown)
object (RecordStringUnknown)

Responses

Request samples

Content type
application/json
{
  • "limit": 1,
  • "before": "string",
  • "metadata": { },
  • "checkpoint": { }
}

Response samples

Content type
application/json
[
  • {
    }
]

Assistants

Available agents (assistants) on the AIAv2 API.

Every agent has two identifiers:

  • agent_id — a stable, product-facing slug (e.g. contract-review). Use this to manage an agent (create/patch/delete/list versions) via the /agents/{agent_id} routes.
  • assistant_id — a LangGraph-compatible identifier. For built-in agents this equals agent_id; for saved/custom agents it's a server-generated UUID. Use this only with LangGraph SDK clients or the mirrored /assistants/{assistant_id} routes, which (matching LangGraph's own API) require the UUID and do not accept agent_id as a fallback.

You don't need to look the UUID up separately: every response that represents an agent (POST /agents, GET /agents/{agent_id}, GET /agents, POST /agents/search, and each version snapshot) includes both agent_id and assistant_id.

Run creation is the one place the two are interchangeable: POST /runs/* and POST /threads/{id}/runs/* accept either agent_id or assistant_id in the request body.

List assistants

List all available assistants with pagination.

Authorizations:
ApiAuthToken
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of results (1-100).

offset
integer >= 0
Default: 0

Pagination offset.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a saved assistant

Create a persisted custom agent configuration and expose it through the LangGraph-compatible assistant API.

Authorizations:
ApiAuthToken
Request Body schema: application/json
required
agent_id
required
string <= 255 characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

Immutable product-facing identifier: lower-case letters, numbers, and single dashes. Must not collide with an existing agent or a reserved built-in agent id.

graph_id
string
Default: "react"
name
string

Human-readable display name.

description
string
object

Legacy alias for context: the LangGraph-SDK configurable contents, sent flat. Merged into context (context wins on overlap) to form the agent definition, which responses echo back as config.configurable.

object

The agent definition applied to every run of this agent. Responses echo it back as both config.configurable and context.

object

Responses

Request samples

Content type
application/json
{
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": { },
  • "context": { },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": {
    },
  • "context": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 1
}

Search assistants

Search assistants with advanced filtering.

Authorizations:
ApiAuthToken
Request Body schema: application/json
optional
object (RecordStringUnknown)
graph_id
string
limit
integer [ 1 .. 100 ]
Default: 10
offset
integer >= 0
Default: 0
sort_by
string
Enum: "assistant_id" "agent_id" "graph_id" "name" "created_at" "updated_at"
sort_order
string
Enum: "asc" "desc"

Responses

Request samples

Content type
application/json
{
  • "metadata": { },
  • "graph_id": "string",
  • "limit": 10,
  • "offset": 0,
  • "sort_by": "assistant_id",
  • "sort_order": "asc"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get an assistant

Fetch a single assistant (built-in or saved) by its LangGraph-compatible id.

Authorizations:
ApiAuthToken
path Parameters
assistant_id
required
string
Example: chat

LangGraph-compatible assistant id.

Responses

Response samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": {
    },
  • "context": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 1
}

Create a new saved assistant version

Create a new immutable version of a saved assistant and make it the latest. This is a partial update: supplied top-level fields replace the current value and omitted fields are carried over, but the agent definition (config/context) and metadata are each replaced as a whole object (not deep-merged). Every successful call increments version. Built-in agents are read-only.

Authorizations:
ApiAuthToken
path Parameters
assistant_id
required
string
Example: chat

LangGraph-compatible assistant id.

Request Body schema: application/json
required
agent_id
string <= 255 characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

Immutable identifier. Optional; if supplied it must match the existing agent_id (agent ids cannot be changed).

graph_id
string
name
string

Human-readable display name.

description
string
object

Legacy alias for context: the LangGraph-SDK configurable contents, sent flat. Merged into context (context wins on overlap).

object

The agent definition applied to every run. Replaces the previous definition as a whole object; responses echo it as both config.configurable and context.

object

Responses

Request samples

Content type
application/json
{
  • "agent_id": "string",
  • "graph_id": "string",
  • "name": "Contract Review",
  • "description": "string",
  • "config": { },
  • "context": { },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": {
    },
  • "context": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 1
}

Delete a saved assistant

Delete a saved assistant and its version history. Built-in assistants are read-only and cannot be deleted.

Authorizations:
ApiAuthToken
path Parameters
assistant_id
required
string
Example: chat

LangGraph-compatible assistant id.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": [
    ]
}

Get assistant schemas

Get the input, output, state, and context schemas for a specific assistant.

Authorizations:
ApiAuthToken
path Parameters
assistant_id
required
string
Example: chat

ID of the assistant.

Responses

Response samples

Content type
application/json
{
  • "graph_id": "string",
  • "input_schema": { },
  • "output_schema": { },
  • "state_schema": { },
  • "context_schema": { },
  • "config_schema": { }
}

List assistant versions

Lists immutable version snapshots for a saved assistant. Built-in assistants return their single built-in version.

Authorizations:
ApiAuthToken
path Parameters
assistant_id
required
string
Example: chat

LangGraph-compatible assistant id.

Request Body schema: application/json
optional
object

Metadata filter (subset match) applied to version snapshots. Ignored for built-in agents, which expose a single built-in version.

limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of versions to return (1-100).

offset
integer >= 0
Default: 0

Pagination offset.

Responses

Request samples

Content type
application/json
{
  • "metadata": { },
  • "limit": 10,
  • "offset": 0
}

Response samples

Content type
application/json
[
  • {
    }
]

Promote an assistant version

Makes an existing saved assistant version the active version.

Authorizations:
ApiAuthToken
path Parameters
assistant_id
required
string
Example: chat

LangGraph-compatible assistant id.

Request Body schema: application/json
required
version
required
integer >= 1

The existing version number to promote to the active (latest) version.

Responses

Request samples

Content type
application/json
{
  • "version": 3
}

Response samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": {
    },
  • "context": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 1
}

List agents

List all available agents (built-in and saved) with pagination.

Authorizations:
ApiAuthToken
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of results (1-100).

offset
integer >= 0
Default: 0

Pagination offset.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a saved agent

Create a persisted custom agent configuration as version 1. Returns the canonical agent object (see the Assistants tag for the identifier model).

Authorizations:
ApiAuthToken
Request Body schema: application/json
required
agent_id
required
string <= 255 characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

Immutable product-facing identifier: lower-case letters, numbers, and single dashes. Must not collide with an existing agent or a reserved built-in agent id.

graph_id
string
Default: "react"
name
string

Human-readable display name.

description
string
object

Legacy alias for context: the LangGraph-SDK configurable contents, sent flat. Merged into context (context wins on overlap) to form the agent definition, which responses echo back as config.configurable.

object

The agent definition applied to every run of this agent. Responses echo it back as both config.configurable and context.

object

Responses

Request samples

Content type
application/json
{
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": { },
  • "context": { },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": {
    },
  • "context": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 1
}

Search agents

Search agents with metadata and graph filters.

Authorizations:
ApiAuthToken
Request Body schema: application/json
optional
object (RecordStringUnknown)
graph_id
string
limit
integer [ 1 .. 100 ]
Default: 10
offset
integer >= 0
Default: 0
sort_by
string
Enum: "assistant_id" "agent_id" "graph_id" "name" "created_at" "updated_at"
sort_order
string
Enum: "asc" "desc"

Responses

Request samples

Content type
application/json
{
  • "metadata": { },
  • "graph_id": "string",
  • "limit": 10,
  • "offset": 0,
  • "sort_by": "assistant_id",
  • "sort_order": "asc"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get an agent

Fetch a single agent (built-in or saved) by its product-facing agent_id.

Authorizations:
ApiAuthToken
path Parameters
agent_id
required
string
Example: contract-review

Product-facing agent id.

Responses

Response samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": {
    },
  • "context": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 1
}

Create a new saved agent version

Create a new immutable version of a saved agent and make it the latest. This is a partial update: supplied top-level fields replace the current value and omitted fields are carried over, but the agent definition (config/context) and metadata are each replaced as a whole object (not deep-merged). Every successful call increments version. Built-in agents are read-only.

Authorizations:
ApiAuthToken
path Parameters
agent_id
required
string
Example: contract-review

Product-facing agent id.

Request Body schema: application/json
required
agent_id
string <= 255 characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

Immutable identifier. Optional; if supplied it must match the existing agent_id (agent ids cannot be changed).

graph_id
string
name
string

Human-readable display name.

description
string
object

Legacy alias for context: the LangGraph-SDK configurable contents, sent flat. Merged into context (context wins on overlap).

object

The agent definition applied to every run. Replaces the previous definition as a whole object; responses echo it as both config.configurable and context.

object

Responses

Request samples

Content type
application/json
{
  • "agent_id": "string",
  • "graph_id": "string",
  • "name": "Contract Review",
  • "description": "string",
  • "config": { },
  • "context": { },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": {
    },
  • "context": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 1
}

Delete a saved agent

Delete a saved agent and its version history. Built-in agents are read-only and cannot be deleted.

Authorizations:
ApiAuthToken
path Parameters
agent_id
required
string
Example: contract-review

Product-facing agent id.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": [
    ]
}

Get schemas for an agent

Get the input, output, state, and context schemas for an agent.

Authorizations:
ApiAuthToken
path Parameters
agent_id
required
string
Example: contract-review

Product-facing agent id.

Responses

Response samples

Content type
application/json
{
  • "graph_id": "string",
  • "input_schema": { },
  • "output_schema": { },
  • "state_schema": { },
  • "context_schema": { },
  • "config_schema": { }
}

List agent versions

List a saved agent's immutable version snapshots (newest first). Built-in agents return their single built-in version.

Authorizations:
ApiAuthToken
path Parameters
agent_id
required
string
Example: contract-review

Product-facing agent id.

Request Body schema: application/json
optional
object

Metadata filter (subset match) applied to version snapshots. Ignored for built-in agents, which expose a single built-in version.

limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of versions to return (1-100).

offset
integer >= 0
Default: 0

Pagination offset.

Responses

Request samples

Content type
application/json
{
  • "metadata": { },
  • "limit": 10,
  • "offset": 0
}

Response samples

Content type
application/json
[
  • {
    }
]

Promote an agent version

Promote an existing saved-agent version to be the active (latest) version. Built-in agents are read-only.

Authorizations:
ApiAuthToken
path Parameters
agent_id
required
string
Example: contract-review

Product-facing agent id.

Request Body schema: application/json
required
version
required
integer >= 1

The existing version number to promote to the active (latest) version.

Responses

Request samples

Content type
application/json
{
  • "version": 3
}

Response samples

Content type
application/json
{
  • "assistant_id": "chat",
  • "agent_id": "contract-review",
  • "graph_id": "react",
  • "name": "Contract Review",
  • "description": "string",
  • "config": {
    },
  • "context": { },
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 1
}

Documents

Document ingestion and management (server API).

Get Documents

Returns the identifiers of all the documents ingested into the Nutrient AI Assistant database.

If the identifier is listed in the response, the database contains contextual information such document metadata, and document contents, as well as AI synthesized information such as classifications, and summaries.

Authorizations:
ApiAuthToken

Responses

Response samples

Content type
application/json
{
  • "documents": [
    ]
}

Delete Document

Deletes the data associated with each layer of the given document, as well as the document default layer (no layer name) itself.

All data including contextual data such as document metadata, and document contents, as well as AI synthesized information such as classifications, and summaries will be deleted.

Authorizations:
ApiAuthToken
path Parameters
documentId
required
string
Example: 123456789abc

The ID of the document to delete. This ID is given when creating the document on the Document Engine.

Responses

Response samples

Content type
application/json
{ }

Delete Document Layer

Deletes the data associated with the given document layer.

All data including contextual data such as document metadata, and document contents, as well as AI synthesized information such as classifications, and summaries will be deleted.

Authorizations:
ApiAuthToken
path Parameters
documentId
required
string
Example: 123456789abc

The ID of the document to delete the layer from. This ID is given when creating the document on the Document Engine.

layerName
required
string
Example: 123456789abc

The name of the layer to delete. This layer name is given when creating a layer on the Document Engine.

Responses

Response samples

Content type
application/json
{ }

Check Document Ingestion Status

Checks if a document with the given ID and file hash has already been ingested into the Nutrient AI Assistant database.

Authorizations:
ApiAuthToken
path Parameters
documentId
required
string

The permanent ID of the document to check if it is ingested. This ID uniquely identifies a document and won't change if the document is modified.

fileHash
required
string

The hash of the file in its current state.

Responses

Response samples

Content type
application/json
{ }

Ingest PDF Document

Ingests a PDF document directly into the Nutrient AI Assistant database. The document will be processed, analyzed, and stored for future retrieval and analysis.

The endpoint expects a raw PDF file in the request body with content-type application/pdf.

Returns permanent and changing IDs for the document.

Authorizations:
ApiAuthToken
Request Body schema: application/pdf
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "permanentId": "string",
  • "changingId": "string",
  • "token": "string"
}

Ingest PDF Document originating from Nutrient Document Engine

Ingests a PDF document stored in Nutrient Document Engine into the Nutrient AI Assistant database. The document will be processed, analyzed, and stored for future retrieval and analysis.

Authorizations:
ApiAuthToken
path Parameters
documentId
required
string
Example: 123456789abc

The ID of the document to ingest. This ID is given when creating the document on the Document Engine.

fileHash
required
string
Example: 123456789abc

The hash of the file in its current state. This will be used to check if the file has changed since the last ingest and whether to trigger a new ingest.

Responses

Response samples

Content type
application/json
{ }

Ingest PDF Document of the given layer name originating from Nutrient Document Engine

Ingests a PDF document stored in Nutrient Document Engine into the Nutrient AI Assistant database. The document will be processed, analyzed, and stored for future retrieval and analysis.

Authorizations:
ApiAuthToken
path Parameters
documentId
required
string
Example: 123456789abc

The ID of the document to ingest. This ID is given when creating the document on the Document Engine.

layerName
required
string
Example: myLayer

The name of the layer to ingest. This layer name is given when creating a layer on the Document Engine.

fileHash
required
string
Example: 123456789abc

The hash of the file in its current state. This will be used to check if the file has changed since the last ingest and whether to trigger a new ingest.

Responses

Response samples

Content type
application/json
{ }

Sessions

Chat session management (server API).

Get Sessions

Returns all the session information held in the AI Assistant database.

This includes the session ID, the user ID (if present), and the timestamp of the last message sent.

Authorizations:
ApiAuthToken

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ]
}

Delete Session

Deletes all session data for the given Session ID.

This includes all messages and metadata associated with the session. Meaning the chat history will no longer be available.

Authorizations:
ApiAuthToken
path Parameters
sessionId
required
string
Example: 123456789abc

The unique identifier for the session. This value is given as part of the AI Assistant configuration when initializing the Nutrient Web SDK.

Responses

Response samples

Content type
application/json
{ }

Get User Sessions

Returns all the session information for all sessions tagged with a given user ID.

Sessions are tagged with a user ID when the AI Assistant configuration in the Nutrient Web SDK is initialized with a user ID.

Authorizations:
ApiAuthToken
path Parameters
userId
required
string
Example: 123456789abc

The unique identifier for the user. This value is optionally given in the AI Assistant configuration when initializing the Nutrient Web SDK.

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ]
}

Client

Endpoints consumed by the Web / iOS / Android SDKs.

Ingest a PDF document (standalone)

Ingests a PDF document without relying on Document Engine. The request body is the raw PDF (application/pdf). Returns the permanent and changing ids and, for client requests, a new JWT scoped to the ingested document.

Authorizations:
ApiAuthToken
Request Body schema: application/pdf
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "permanentId": "string",
  • "changingId": "string",
  • "token": "string"
}

Ingest a Document Engine document

Ingests a document stored in Nutrient Document Engine. Requires Document Engine.

Authorizations:
ApiAuthToken
path Parameters
documentId
required
string
Example: 123456789abc
fileHash
required
string

A hash of the file content to detect changes.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Ingest a Document Engine document layer

Ingests a specific layer of a document stored in Nutrient Document Engine. Requires Document Engine.

Authorizations:
ApiAuthToken
path Parameters
documentId
required
string
Example: 123456789abc
layerName
required
string
Example: myLayer
fileHash
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Check whether a document is ingested

Checks if a document with the given file hash has already been ingested.

Authorizations:
ApiAuthToken
path Parameters
documentId
required
string
fileHash
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get chat history for a session

Retrieves the chat history for a specific session.

Authorizations:
ApiAuthToken
path Parameters
sessionId
required
string
Example: 123456789abc

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Health

Service health.

Health check

Responds with the health status of the server.

Responses

Response samples

Content type
application/json
{
  • "uptime": 123,
  • "message": "OK",
  • "timestamp": 1620000000000,
  • "degraded": false,
  • "services": [
    ]
}

Dashboard

Operator/admin actions exposed on the dashboard (basic auth).

Refresh License

Forces an immediate licensor re-activation on the running instance without a restart: it pings the licensor, validates the returned key, persists it when a database is configured, and hot-swaps the live license.

Requires an activation-key deployment (ACTIVATION_KEY). Only the replica that handled the request updates immediately; other replicas converge within the periodic license check interval (~2 hours) or on restart. Repeated calls are rate-limited for a short cooldown after a successful refresh.

Authorizations:
DashboardBasicAuth

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}