Connected sources

Connected sources bring external knowledge into a workspace without copying it by hand. A workspace administrator connects a provider, picks what should be indexed, and Orcha syncs the selected documents as read-only, cited context. Orcha never writes back to a provider.

Providers

Connectors appear on the Connectors page in the app. Each card says what that provider can index, and a card whose credentials are not configured in your environment says so instead of offering a connect button.

Administrators connect providers from the app. Most use a shared OAuth flow with S256 PKCE; access and refresh tokens are encrypted at rest, and sync workers obtain current tokens through the auth layer rather than storing secrets themselves. GitHub uses a read-only GitHub App installation, and Granola takes an API key. Each provider declares its own scopes and a daily call budget.

Selective indexing

Orcha catalogs a source before it indexes anything. The catalog is a metadata inventory of what exists upstream: names, paths, sizes, and revisions, without the bodies. You then decide which parts of that inventory are worth indexing, and the sync engine fetches only those bodies.

Every resource (a repository, a drive, a Notion workspace, a Linear team) and every path inside it takes one of four policies:

Rules inherit down a subtree and the deepest matching rule wins; on a tie, exclusion wins. You can catalog a whole drive, index one folder in full, and exclude a subfolder inside it. Before you save, the app estimates how many objects the change would index, how many bytes that is, and roughly how many provider API calls it costs.

Defaults differ by provider because the cost profiles differ. GitHub and Granola default to essentials. Document and issue providers default to discover-only, so connecting one is cheap and you opt into the parts you want. Gmail is excluded by default and needs both an added OAuth scope and an explicit rule.

In the catalog view each object carries its state: Indexed (body retained and searchable), Queued (selected, not yet fetched), Catalog only (metadata retained), or Skipped (a type Orcha cannot index, with the reason).

Retrieval across retained and catalog-only content

Retained content is searched like any other document. Catalog-only content is reachable too, through the freshness modes on search_context: balanced (the default) also searches the catalog and fetches a small number of decisively matching bodies live from the provider, and fresh additionally dispatches to providers that answer queries live, such as issue trackers. Live results are cited with syncMode: "live" and are not persisted. Every live call is metered against the connection's daily provider budget. See Retrieval.

How synced documents behave

Synced documents are not files. They do not appear in list_files and cannot be edited or deleted through the file APIs. Instead:

• They are indexed and returned by search_context like any other document.
• Citations pin to the exact upstream version that was indexed (for example a commit-pinned deep link into a GitHub repository).
• list_source_documents lists them per source with indexStatus and lastSyncedAt. This requires a workspace-wide token; folder-scoped tokens cannot see sources.
• get_workspace_overview names each connected source with its document count and sync status.
• query_source and fetch_source_document address one source directly. See the API reference and the MCP reference.

Freshness and lifecycle

Sources resync on a schedule set by your plan, from once a day on Free down to every 15 minutes on the highest tiers. Paid plans also accept provider webhooks, so a push to a connected repository updates the index without waiting for the next scheduled run. Providers with change feeds (Google Drive, OneDrive, Dropbox, Notion) keep a durable delta cursor, so a resync fetches what changed instead of redownloading the corpus, and upstream deletions are reconciled out of the index.

A connection can be paused, revoked, or disconnected from the Manage view:

• Pause stops syncing and keeps the indexed content searchable.
• Revoke deactivates the source and retains its content until you decide what to do with it.
• Disconnect removes the index and cache state and reverses the billed bytes.

Pushing content in yourself

If a connector does not exist for your system, push content through the ingestion API: a token-authenticated endpoint that accepts documents with your own citations and provenance, and indexes them for retrieval. Re-sending the same idempotency key with identical content is deduplicated, so sync jobs can replay safely.