Connected sources

Connected sources bring external knowledge into a workspace. You do not copy the content manually. A workspace administrator connects a provider and selects what Orcha indexes. Orcha then syncs the selected documents as read-only, cited context. Orcha never writes back to a provider.

Providers

Connectors are on the Connectors page in the app. Each card shows what the provider can index. If your environment has no credentials for a provider, its card shows this and has no connect button.

Administrators connect providers from the app. Most providers use a shared OAuth flow with S256 PKCE. Orcha encrypts access tokens and refresh tokens at rest. Sync workers do not store secrets. They get current tokens through the auth layer. GitHub uses a read-only GitHub App installation. Granola uses an API key. Each provider declares its own scopes and a daily call budget.

Selective indexing

Orcha makes a catalog of a source before it indexes content. The catalog is a metadata inventory of the upstream items: names, paths, sizes, and revisions. The catalog does not contain the bodies. You select the parts of the inventory that Orcha indexes. The sync engine then gets only those bodies.

Each resource (a repository, a drive, a Notion workspace, a Linear team) has one of four policies. Each path in a resource can also have one of these policies:

A rule applies to all items below it in the subtree. The deepest rule that matches an item applies. If two rules are at the same depth, the exclusion applies. For example, you can catalog a full drive, index all of one folder, and exclude a subfolder in that folder. Before you save, the app shows an estimate for the change. The estimate shows the number of objects, the number of bytes, and the approximate number of provider API calls.

The defaults are different for each provider, because the costs are different. GitHub and Granola use essentials as the default. Document providers and issue providers use names-only as the default. Thus, a new connection costs little, and you select the parts that you want. Gmail is excluded by default. To index Gmail, you must add an OAuth scope and an explicit rule.

In the catalog view, each object shows its state:

• Indexed: Orcha keeps the body, and search can find it.
• Queued: The object is selected, but Orcha did not get it yet.
• Discovered: The object is listed by name. Orcha does not store the body.
• Excluded: A rule excludes the object.
• Unsupported: Orcha cannot index this type. The view shows the reason.

Retrieval across retained and catalog-only content

Search finds retained content in the same way as other documents. Search can also find catalog-only content through the freshness modes of search_context:

• balanced (the default) also searches the catalog. It gets a small number of bodies that match clearly, live from the provider.
• fresh also sends the query to providers that answer queries live, such as issue trackers.

Live results have the citation value syncMode: "live". Orcha does not store live results. Orcha counts each live call against the daily provider budget of the connection. See Retrieval.

How synced documents behave

Synced documents are not files. They do not show in list_files. You cannot edit or delete them through the file APIs. Synced documents have these properties:

• search_context indexes and returns them in the same way as other documents.
• Citations point to the exact upstream version that Orcha indexed. An example is a commit-pinned deep link into a GitHub repository.
• list_source_documents lists them for each source, with indexStatus and lastSyncedAt. This tool needs a workspace-wide token. Folder-scoped tokens cannot see sources.
• get_workspace_overview shows the name, document count, and sync status of each connected source.
• query_source and fetch_source_document go directly to one source. See the API reference and the MCP reference.

Freshness and lifecycle

Orcha syncs sources again each hour on all plans. Paid plans also accept provider webhooks from GitHub, Dropbox, and Linear. Thus, a push to a connected repository updates the index before the next scheduled sync. Some providers have change feeds: Google Drive, OneDrive, Dropbox, and Notion. For these providers, Orcha keeps a durable delta cursor. A new sync gets only the changes and does not download all content again. Orcha also removes upstream deletions from the index.

You can pause, revoke, or disconnect a connection from the Manage view:

• Pause stops the sync. Search can still find the indexed content.
• Revoke destroys the stored credential, deactivates the source, and removes the synced content. Orcha keeps the catalog inventory. Thus, a new connection can make the same selection again.
• Disconnect removes all items that the connection made, including the catalog. It also reverses the billed bytes.

Pushing content in yourself

If no connector exists for your system, send content through the ingestion API. This endpoint uses token authentication. It accepts documents with your own citations and provenance and indexes them for retrieval. If you send the same idempotency key with identical content again, Orcha ignores the duplicate. Thus, sync jobs can send the same content again safely.