Connectors

Refine can scan more than local files. Use connectors to pull knowledge from the tools your team already uses.

ody-refine connect <source>

Available Connectors

Notion

ody-refine connect notion

Env var	Description
NOTION_API_KEY	Integration token from notion.so/my-integrations

Share at least one page or database with the integration. Refine fetches all shared pages and converts blocks to markdown.

Slack

ody-refine connect slack

Env var	Description
SLACK_BOT_TOKEN	Bot token (xoxb-...) from api.slack.com/apps

Required scopes: channels:history, channels:read, chat:write, users:read. Invite the bot to the channels you want scanned. Threads are expanded automatically.

Confluence

ody-refine connect confluence

Env var	Description
CONFLUENCE_URL	Your Atlassian site URL (e.g., https://yoursite.atlassian.net)
CONFLUENCE_EMAIL	Your Atlassian email
CONFLUENCE_API_TOKEN	API token from id.atlassian.com

Fetches pages and converts Confluence storage format to markdown.

Linear

ody-refine connect linear

Env var	Description
LINEAR_API_KEY	Personal API key from linear.app/settings/api

Pulls issues, comments, and project descriptions from your workspace.

Jira

ody-refine connect jira

Env var	Description
JIRA_URL	Your Atlassian site URL (e.g., https://yoursite.atlassian.net)
JIRA_EMAIL	Your Atlassian email
JIRA_API_TOKEN	API token from id.atlassian.com

Fetches issues and converts Atlassian Document Format (ADF) to markdown.

Microsoft Teams

ody-refine connect teams

Env var	Description
TEAMS_ACCESS_TOKEN	OAuth token with Microsoft Graph permissions

Required permissions: Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All. Messages are converted from HTML to markdown.

Gmail

ody-refine connect gmail

Uses OAuth2 for authentication. Follow the interactive flow to authorize access to your Gmail account.

Integration Testing

All connectors can be tested against live APIs:

# Single connector
NOTION_API_KEY=ntn_xxx pnpm --filter ody-refine test -- integration/

# Multiple connectors
NOTION_API_KEY=ntn_xxx \
LINEAR_API_KEY=lin_api_xxx \
SLACK_BOT_TOKEN=xoxb-xxx \
  pnpm --filter ody-refine test -- integration/

When env vars are missing, tests skip automatically -- no failures, no overhead.

Required Env Vars per Connector

Connector	Env vars
Notion	NOTION_API_KEY
Linear	LINEAR_API_KEY
Slack	SLACK_BOT_TOKEN
Confluence	CONFLUENCE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN
Jira	JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN
Teams	TEAMS_ACCESS_TOKEN
Gmail	OAuth2 (interactive flow)