Core Concepts

Actions

(Advanced) Custom Built-in Actions

Assistants

Connectors

When you see the term Connector in Onyx or elsewhere in this documentation, we’re generally referring to ConnectorCredentialPairs

Connectors

Connectors in Onyx define the data you would like to index

name: Not actually displayed in the UI if ConnectorCredentialPairMetadata:name is set
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. You will need to see /backend/onyx/connectors for the expected Connector-specific Configurations.
refresh_freq: How often to check for new or updated content in seconds
prune_freq: How often to remove old content from Onyx in seconds
indexing_start: Optional datetime to specify when indexing should begin

Python

class ConnectorBase(BaseModel):
    name: str
    source: DocumentSource
    input_type: InputType
    connector_specific_config: dict[str, Any]
    refresh_freq: int | None = None
    prune_freq: int | None = None
    indexing_start: datetime | None = None

Credentials

ConnectorCredentialPairs

ConnectorCredentialPairMetadata

ConnectorCredentialPairMetadata defines the configuration and access settings for a CC-pair.Configuration options:

name: Optional display name for the CC-pair (overrides the Connector name)
access_type: Who can access data from this CC-pair (see AccessType accordion below)
auto_sync_options: Optional configuration for automatic synchronization settings
groups: List of group IDs that have access to this CC-pair

Python

class ConnectorCredentialPairMetadata(BaseModel):
    name: str | None = None
    access_type: AccessType
    auto_sync_options: dict[str, Any] | None = None
    groups: list[int] = Field(default_factory=list)

Documents

DocumentBase

DocumentBase is a core structure used throughout Onyx for storing and managing document data. Note that the embeddings are stored in Vespa separately.

id: Unique identifier. Generated by Onyx if not provided
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] that will be saved as tags for this Document
doc_updated_at: UTC timestamp when the document was last updated
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 the code may need
external_access: Permission sync data (Enterprise Edition only)

The Ingestion API extends the DocumentBase definition to include cc_pair_id to automatically associate a document with a CC-pair.

Python

class DocumentBase(BaseModel):
    """Used for Onyx ingestion api, the ID is inferred before use if not provided"""

    id: str | None = None
    sections: list[TextSection | ImageSection]
    source: DocumentSource | None = None
    semantic_identifier: str
    metadata: dict[str, str | list[str]]

    doc_updated_at: datetime | None = None
    chunk_count: int | None = None

    primary_owners: list[BasicExpertInfo] | None = None
    secondary_owners: list[BasicExpertInfo] | None = None
    title: str | None = None
    from_ingestion_api: bool = False
    additional_info: Any = None

    external_access: ExternalAccess | None = None

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

class DocumentSource(str, Enum):
  INGESTION_API = "ingestion_api"     # Special case, document passed in via Onyx APIs without specifying a source type
  SLACK = "slack"
  WEB = "web"
  GOOGLE_DRIVE = "google_drive"
  GMAIL = "gmail"
  REQUESTTRACKER = "requesttracker"
  GITHUB = "github"
  GITBOOK = "gitbook"
  GITLAB = "gitlab"
  GURU = "guru"
  BOOKSTACK = "bookstack"
  CONFLUENCE = "confluence"
  JIRA = "jira"
  SLAB = "slab"
  PRODUCTBOARD = "productboard"
  FILE = "file"
  NOTION = "notion"
  ZULIP = "zulip"
  LINEAR = "linear"
  HUBSPOT = "hubspot"
  DOCUMENT360 = "document360"
  GONG = "gong"
  GOOGLE_SITES = "google_sites"
  ZENDESK = "zendesk"
  LOOPIO = "loopio"
  DROPBOX = "dropbox"
  SHAREPOINT = "sharepoint"
  TEAMS = "teams"
  SALESFORCE = "salesforce"
  DISCOURSE = "discourse"
  AXERO = "axero"
  CLICKUP = "clickup"
  MEDIAWIKI = "mediawiki"
  WIKIPEDIA = "wikipedia"
  ASANA = "asana"
  S3 = "s3"
  R2 = "r2"
  GOOGLE_CLOUD_STORAGE = "google_cloud_storage"
  OCI_STORAGE = "oci_storage"
  XENFORO = "xenforo"
  NOT_APPLICABLE = "not_applicable"
  DISCORD = "discord"
  FRESHDESK = "freshdesk"
  FIREFLIES = "fireflies"
  EGNYTE = "egnyte"
  AIRTABLE = "airtable"
  HIGHSPOT = "highspot"

  IMAP = "imap"

  # Special case just for integration tests
  MOCK_CONNECTOR = "mock_connector"

TextSection

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

Python

class TextSection(Section):
    text: str
    link: str | None = None

ImageSection

ImageSection is an image extracted from a Document in Onyx.

image_file_id: UUID 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

class ImageSection(Section):
    image_file_id: str
    text: str | None = None
    link: str | None = None

AccessType

AccessType defines who can access data from a Connector in Onyx.

PUBLIC: All Onyx users may access data from this Connector
PRIVATE: Only the user who created the Connector and specified Groups may access data from this Connector
SYNC: Only Connectors with permission-sync support can be set to SYNC. The Connector will sync access permissions with the source system.

Python

class AccessType(str, Enum):
  PUBLIC = "public"
  PRIVATE = "private"
  SYNC = "sync"

InputType

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

class InputType(str, Enum):
  LOAD_STATE = "load_state"
  POLL = "poll"
  EVENT = "event"
  SLIM_RETRIEVAL = "slim_retrieval"

Getting Started

Guides & Examples

API Reference

Actions

Assistants

Connectors

Documents

Next Steps

Guide: Index files with the Ingestion API

Guide: Send a Chat Message

Getting Started

Guides & Examples

API Reference

​Actions

​Assistants

​Connectors

​Documents

​Next Steps

Guide: Index files with the Ingestion API

Guide: Send a Chat Message

Actions

Assistants

Connectors

Documents

Next Steps