Skip to main content

Plugins & Actions

Actions (called Tools in the API) are the functions that your Agents can call to interact with external systems and services.Built-in Actions:Custom Actions let an agent call your own systems. Admins add custom Actions in Admin Panel > Plugins from an MCP server or an OpenAPI schema. Each MCP tool or OpenAPI operation becomes one Action. The Actions endpoints list and manage them.
Plugins are everything an admin connects to Onyx under Admin Panel > Plugins:
  • MCP servers: Each tool the server exposes becomes an Action.
  • OpenAPI Actions: Each operation in the schema becomes an Action.
  • Apps: External apps that Craft sessions can use.
See the Plugins overview for setup and permissions.
Model Context Protocol (MCP) is an open standard that lets AI assistants access external data sources and tools. Onyx works in both directions:
  • Onyx as an MCP client: Admins connect external MCP servers as Plugins. Their tools become Actions your Agents can call. OAuth, API key, and no-auth servers are supported.
  • Onyx as an MCP server: External clients such as Claude, ChatGPT, or Codex connect to https://your-onyx-domain.com/mcp/ with OAuth, a Personal Access Token, or an API Key, and search your Onyx knowledge. See Onyx MCP server.

Agents

Agents are AI assistants with custom instructions, Actions, and data access that extend the base LLM’s capabilities.
Older Onyx versions and some API fields call Agents Assistants or Personas. They are the same concept.
The API still uses the older name: Agent endpoints live under /persona, and an Agent ID is a persona_id.The default AgentEvery Onyx instance has one built-in Agent with id: 0. Every chat session that does not name an Agent uses it. Admins can edit its instructions and Actions in the Admin Panel, but cannot delete it.You can create your own Agents in the Onyx UI or with the Agents endpoints.Most Chat endpoints accept an Agent IDTo find an Agent ID, you can:
  • Call GET /persona to list the Agents you can access, or GET /agents for a paginated list
  • In the Onyx UI, open the Agent. The number in the URL is its ID

Chat

POST /chat/send-chat-message streams its response as server-sent events (SSE). Each event is one JSON packet. Set stream: false in the request to receive one complete JSON response instead.Every packet has the same two fields:
  • placement tells you where the packet belongs. turn_index increases with each reasoning or tool-call round, tab_index separates parallel tool calls in one round, sub_turn_index is set for a tool that calls other tools, and model_index identifies the model when several models answer side by side.
  • obj is the content. Its type field tells you how to read the rest of the object.
Packets with the same placement form one block in the UI.
These packets carry the answer itself:
  • message_start: Starts the answer. Carries final_documents, the documents the answer can cite, if any
  • message_delta: Delivers incremental text in content as it is generated
Control packets manage the flow and lifecycle of the stream:
  • stop: Signals the end of the entire stream. There is no end packet for the answer itself
  • section_end: Marks the completion of one block (reasoning, a tool call, the answer, etc.)
  • chat_heartbeat: Keepalive during silent stretches. It carries no state
  • error: Reports a failure. The stream ends after it
Tool activity streams in the same way as the answer. Each tool has a start packet and one or more delta packets.Internal Search
  • search_tool_start, search_tool_queries_delta, search_tool_filter_delta, and search_tool_documents_delta show the queries, filters, and documents the search found
Web Search
  • open_url_start, open_url_urls, and open_url_documents show the pages Onyx opened
Image Generation
  • image_generation_start, image_generation_heartbeat, and image_generation_final
Code Execution
  • python_tool_start and python_tool_delta
File Reading and Memory
  • file_reader_start, file_reader_result, memory_tool_start, memory_tool_delta, and memory_tool_no_access
Custom Actions (MCP and OpenAPI)
  • custom_tool_start, custom_tool_args, and custom_tool_delta
Deep Research and Coding Agent
  • deep_research_plan_start, deep_research_plan_delta, research_agent_start, intermediate_report_start, intermediate_report_delta, and intermediate_report_cited_docs
  • coding_agent_start, coding_agent_thinking_delta, coding_agent_final, bash_tool_start, and bash_tool_delta
New tools add new packet types. Ignore any type you do not recognize.
Reasoning steps stream so a client can render them while the model is working. Reasoning packets are generally the first ones sent.
  • reasoning_start: Begins a reasoning section
  • reasoning_delta: Streams the model’s reasoning text
  • reasoning_done: Ends the reasoning section
Citation packets map the citation numbers in the answer text to documents.
  • citation_info: One packet per citation. Carries the citation number and the document it points to

Connectors

When you see the term Connector in Onyx or elsewhere in this documentation, we’re generally referring to ConnectorCredentialPairs
Connectors in Onyx define the data you would like to index
  • name: Internal name. The Admin Panel shows the ConnectorCredentialPairMetadata name instead
  • source: Which system to connect to (see DocumentSource accordion below)
  • input_type: How the Connector retrieves data (see InputType accordion below)
  • connector_specific_config: Source-specific settings like folder paths or channels. The Create Connectors guide shows how to find the expected keys for each source.
  • refresh_freq: How often to check for new or updated content, in seconds. null indexes once with no refresh
  • prune_freq: How often to remove deleted content from Onyx, in seconds
  • check_freq: How often to run connector health checks, in seconds. null runs them only on request
  • indexing_start: Optional datetime. Only content changed after this time is indexed
Python
Credentials contain the authentication details needed to access data sources. These include API keys, OAuth tokens, personal access tokens (PATs), or service account credentials that allow Onyx to securely connect to your external systems. Onyx stores them encrypted.
Behind the scenes, Connectors and Credentials are combined into a ConnectorCredentialPair (CC-pair). A CC-pair is an active connection that can sync data from your external sources into Onyx. CC-pairs are what you see and manage on the Admin Panel Connectors page.
If you’re creating Connectors through the API, you must associate them with a Credential (CC-pair) to make them active!
ConnectorCredentialPairMetadata defines the configuration and access settings for a CC-pair.Configuration options:
  • name: Display name for the CC-pair, shown in the Admin Panel
  • access_type: Who can access data from this CC-pair (see AccessType accordion below)
  • auto_sync_options: Optional settings for permission syncing
  • manage_access: Groups that manage the CC-pair, each with a role
  • groups: Older form of manage_access. Group IDs that manage the CC-pair as Editors. Set at most one of groups and manage_access
  • data_access: Group IDs whose members can read a PRIVATE CC-pair’s documents. null means the managing groups
  • processing_mode: REGULAR indexes documents for search. RAW_BINARY stores the raw files without text extraction
Python

Documents

DocumentBase is a core structure used throughout Onyx for storing and managing document data. Note that the embeddings are stored in OpenSearch separately.
  • id: Unique identifier. Generated by Onyx if not provided. Pushing the same id again updates the existing document
  • sections: List of content sections (see TextSection and ImageSection)
  • source: The system this document originated from (see DocumentSource)
  • semantic_identifier: Displayed in the UI as the name of the Document
  • metadata: Arbitrary string or list[string] values that are saved as tags for this Document
  • doc_updated_at: UTC timestamp when the document was last updated
  • doc_created_at: UTC timestamp when the document was created
  • chunk_count: Number of chunks the document is split into for processing
  • primary_owners: Metadata about people associated with the Document
  • secondary_owners: Metadata about people associated with the Document
  • title: Used for search (defaults to semantic_identifier if not specified)
  • from_ingestion_api: Whether this document came from the Ingestion API
  • additional_info: Connector-specific information that other parts of Onyx may need
  • external_access: Permission sync data (Enterprise Edition only)
The Ingestion API wraps DocumentBase in an IngestionDocument with an optional cc_pair_id that associates the document with a CC-pair. Documents pushed through the Ingestion API can only contain TextSection and ImageSection entries.
Python
DocumentSource is an enum that defines the valid sources for a document. Uploading files to the Ingestion API and creating Connectors programmatically require specifying a DocumentSource.
Python
TextSection is a portion of a Document in Onyx.
  • text: The actual text content of the section
  • link: Optional URL that this text section relates to or was sourced from
  • heading: Optional heading for the section
Python
ImageSection is an image extracted from a Document in Onyx.
  • image_file_id: ID of the image file stored in Onyx’s file store
  • text: Optional text description or caption for the image
  • link: Optional URL that this image section relates to or was sourced from
Python
TabularSection is a third section type. Connectors use it for CSV and spreadsheet content that Onyx stages in its file store. The Ingestion API does not accept it.
AccessType defines who can access data from a Connector in Onyx.
  • PUBLIC: All Onyx users may access data from this Connector
  • PRIVATE: Only the groups in data_access (or the managing groups) may access data from this Connector
  • SYNC: The Connector syncs access permissions from the source system. Only Connectors with permission-sync support can use it
  • SYNC_RESTRICTED: Like SYNC, narrowed to the members of the Connector’s data_access groups
SYNC and SYNC_RESTRICTED require the Enterprise Edition.
Python
InputType defines how a Connector retrieves data from its source system.
  • LOAD_STATE: Single load of data from the source
  • POLL: Continuous polling for new data from the source (starts with a full load)
  • EVENT: Not implemented for most Connectors
  • SLIM_RETRIEVAL: For permission-syncing Connectors
Python

Next Steps

Guide: Create Connectors

Learn how to create a Connector through the API

Guide: Index files with the Ingestion API

Learn how to index files with the Ingestion API

Guide: Send a Chat Message

Simple example of sending a message programmatically

Guide: Search with the API

Query the Onyx index and get ranked documents back