Plugins & Actions
Actions
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
Plugins
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.
MCP
MCP
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
Agents
Agents are AI assistants with custom instructions, Actions, and data access that extend the base LLM’s capabilities.The API still uses the older name: Agent endpoints live under
Older Onyx versions and some API fields call Agents Assistants or Personas. They are the same concept.
/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 /personato list the Agents you can access, orGET /agentsfor a paginated list - In the Onyx UI, open the Agent. The number in the URL is its ID
Chat
Streamed Chat Responses
Streamed Chat Responses
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:placementtells you where the packet belongs.turn_indexincreases with each reasoning or tool-call round,tab_indexseparates parallel tool calls in one round,sub_turn_indexis set for a tool that calls other tools, andmodel_indexidentifies the model when several models answer side by side.objis the content. Itstypefield tells you how to read the rest of the object.
placement form one block in the UI.Message Packets
Message Packets
These packets carry the answer itself:
message_start: Starts the answer. Carriesfinal_documents, the documents the answer can cite, if anymessage_delta: Delivers incremental text incontentas it is generated
Control Packets
Control Packets
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 itselfsection_end: Marks the completion of one block (reasoning, a tool call, the answer, etc.)chat_heartbeat: Keepalive during silent stretches. It carries no stateerror: Reports a failure. The stream ends after it
Tool Packets
Tool Packets
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, andsearch_tool_documents_deltashow the queries, filters, and documents the search found
open_url_start,open_url_urls, andopen_url_documentsshow the pages Onyx opened
image_generation_start,image_generation_heartbeat, andimage_generation_final
python_tool_startandpython_tool_delta
file_reader_start,file_reader_result,memory_tool_start,memory_tool_delta, andmemory_tool_no_access
custom_tool_start,custom_tool_args, andcustom_tool_delta
deep_research_plan_start,deep_research_plan_delta,research_agent_start,intermediate_report_start,intermediate_report_delta, andintermediate_report_cited_docscoding_agent_start,coding_agent_thinking_delta,coding_agent_final,bash_tool_start, andbash_tool_delta
type you do not recognize.Reasoning Packets
Reasoning Packets
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 sectionreasoning_delta: Streams the model’s reasoning textreasoning_done: Ends the reasoning section
Citation Packets
Citation Packets
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
Connectors
Connectors
Connectors in Onyx define the data you would like to indexname: Internal name. The Admin Panel shows theConnectorCredentialPairMetadataname insteadsource: Which system to connect to (seeDocumentSourceaccordion below)input_type: How theConnectorretrieves data (seeInputTypeaccordion 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.nullindexes once with no refreshprune_freq: How often to remove deleted content from Onyx, in secondscheck_freq: How often to run connector health checks, in seconds.nullruns them only on requestindexing_start: Optional datetime. Only content changed after this time is indexed
Python
Credentials
Credentials
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.ConnectorCredentialPairs
ConnectorCredentialPairs
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.ConnectorCredentialPairMetadata
ConnectorCredentialPairMetadata
ConnectorCredentialPairMetadata defines the configuration and access settings for a CC-pair.Configuration options:name: Display name for the CC-pair, shown in the Admin Panelaccess_type: Who can access data from this CC-pair (seeAccessTypeaccordion below)auto_sync_options: Optional settings for permission syncingmanage_access: Groups that manage the CC-pair, each with a rolegroups: Older form ofmanage_access. Group IDs that manage the CC-pair as Editors. Set at most one ofgroupsandmanage_accessdata_access: Group IDs whose members can read aPRIVATECC-pair’s documents.nullmeans the managing groupsprocessing_mode:REGULARindexes documents for search.RAW_BINARYstores the raw files without text extraction
Python
Documents
DocumentBase
DocumentBase
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 sameidagain updates the existing documentsections: List of content sections (seeTextSectionandImageSection)source: The system this document originated from (seeDocumentSource)semantic_identifier: Displayed in the UI as the name of the Documentmetadata: Arbitrarystringorlist[string]values that are saved as tags for this Documentdoc_updated_at: UTC timestamp when the document was last updateddoc_created_at: UTC timestamp when the document was createdchunk_count: Number of chunks the document is split into for processingprimary_owners: Metadata about people associated with the Documentsecondary_owners: Metadata about people associated with the Documenttitle: Used for search (defaults tosemantic_identifierif not specified)from_ingestion_api: Whether this document came from the Ingestion APIadditional_info: Connector-specific information that other parts of Onyx may needexternal_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
DocumentSource
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
TextSection
TextSection is a portion of a Document in Onyx.text: The actual text content of the sectionlink: Optional URL that this text section relates to or was sourced fromheading: Optional heading for the section
Python
ImageSection
ImageSection
ImageSection is an image extracted from a Document in Onyx.image_file_id: ID of the image file stored in Onyx’s file storetext: Optional text description or caption for the imagelink: 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
AccessType
AccessType defines who can access data from a Connector in Onyx.PUBLIC: All Onyx users may access data from thisConnectorPRIVATE: Only the groups indata_access(or the managing groups) may access data from thisConnectorSYNC: TheConnectorsyncs access permissions from the source system. OnlyConnectorswith permission-sync support can use itSYNC_RESTRICTED: LikeSYNC, narrowed to the members of theConnector’sdata_accessgroups
SYNC and SYNC_RESTRICTED require the Enterprise Edition.Python
InputType
InputType
InputType defines how a Connector retrieves data from its source system.LOAD_STATE: Single load of data from the sourcePOLL: Continuous polling for new data from the source (starts with a full load)EVENT: Not implemented for mostConnectorsSLIM_RETRIEVAL: For permission-syncingConnectors
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