cortexdb-connectors

Managed data connectors for CortexDB. Run them yourself, or let CortexDB host them for you on the Starter tier.

Each connector pulls from a third-party system (Slack, GitHub, Jira, …) and writes every event into CortexDB as a v1 experience.

Plan availability (audit BLK-3)

The free self-hosted path is always available; the managed dashboard path is what the pricing page calls "Starter+". The badge below appears on each connector's setup page for the same reason.

Install

# core only — no third-party SDK dependencies
pip install cortexdb-connectors

# with one source's SDK
pip install 'cortexdb-connectors[slack]'

# everything
pip install 'cortexdb-connectors[all]'

Requires Python 3.10+.

Auth

The connectors talk to the CortexDB v1 API. Two things you need:

• A PASETO bearer token (Authorization: Bearer …)
• An actor id that matches the token's sub claim (X-Cortex-Actor: …)

The fastest way to get both is to install cortexdb-cli and run cortexdb init — anonymous signup, no email or card, 7-day free-tier token. The connectors read ~/.cortexdb/state.json automatically.

Or set env vars:

export CORTEXDB_URL=https://api-v1.cortexdb.ai
export CORTEXDB_API_KEY=v4.public...
export CORTEXDB_ACTOR=user:u_019e...
export CORTEXDB_SCOPE_TEMPLATE='org:acme/source:{source}'   # optional

{source} (and {scope}, {namespace}, {actor}, {entity.<type>}) get filled in per event. ({tenant} is still accepted as a legacy alias of {scope}.)

Run

# one shot
cortexdb-sync sync slack

# poll loop, 60s between cycles
cortexdb-sync watch slack --interval 60

# resume from a specific point
cortexdb-sync sync github --since 2026-05-01T00:00:00Z

# see what's available
cortexdb-sync list

# check resolved CortexDB creds
cortexdb-sync auth

# cursor state across every connector
cortexdb-sync status

Available connectors

All 18 connectors are 🟢 Free to self-host and 🔒 Starter+ ($29/mo) to use via the managed dashboard.

slack            SLACK_BOT_TOKEN
github           GITHUB_TOKEN
gitlab           GITLAB_TOKEN
jira             JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN   (incl. attachments → /v1/blobs multimodal extraction, 0.2.10+)
freshdesk        FRESHDESK_DOMAIN, FRESHDESK_API_KEY    (incl. attachments → /v1/blobs multimodal extraction, 0.2.20+)
tldv             TLDV_API_KEY
linear           LINEAR_API_KEY
confluence       CONFLUENCE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN
notion           NOTION_TOKEN
pagerduty        PAGERDUTY_API_KEY
discord          DISCORD_BOT_TOKEN
teams            TEAMS_TENANT_ID, TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET
google-workspace GW_SERVICE_ACCOUNT_KEY, GW_DELEGATED_USER
salesforce       SF_INSTANCE_URL, SF_CLIENT_ID, SF_CLIENT_SECRET, SF_USERNAME, SF_PASSWORD
hubspot          HUBSPOT_TOKEN
zendesk          ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_TOKEN
intercom         INTERCOM_TOKEN
servicenow       SNOW_INSTANCE, SNOW_USERNAME, SNOW_PASSWORD

Per-connector setup pages live at https://cortexdb.ai/docs/connectors/ (e.g. Slack). The "Add Connector" button on those pages is the managed (Starter+) path — the CLI on this page is the free path.

For deep self-hosted operation — auth lifetimes, cursor state, retries, OAuth setup for Salesforce/Teams/Google Workspace — see SELF_HOSTING.md in this directory.

YAML config

If env vars get unwieldy, drop a cortexdb-connectors.yaml next to your sync invocation:

slack:
  slack_bot_token: xoxb-...
  channels: [C01ABCDEF, C02GHIJKL]

github:
  github_token: ghp_...
  repos: [acme/api, acme/web]
  events: [pull_request, issue_comment]

Programmatic use

Skip the CLI entirely:

import asyncio
from cortexdb_connectors.slack import SlackConnector

connector = SlackConnector(
    cortex_url="https://api-v1.cortexdb.ai",
    cortex_api_key="v4.public...",
    scope="org:acme/source:slack",
    slack_bot_token="xoxb-...",
    channels=["C01ABC", "C02DEF"],
)
# actor + a richer scope_template are set after construction:
connector.bind(
    actor="user:u_019e...",
    scope_template="org:acme/source:slack/channel:{entity.channel}",
)

result = asyncio.run(connector.sync())
print(result.episodes_ingested, "ingested,", len(result.errors), "errors")

Webhooks

The cortexdb-connectors[webhooks] extra ships a Starlette-based webhook receiver for sources that push (Slack Events API, GitHub Apps, Jira webhooks, …) instead of polling. See cortexdb_connectors/webhooks.py.

License

Apache-2.0