Knowledge

A Knowledge Base is a set of connectors that index your data for retrieval. Connectors pull from tools such as Jira, Confluence, GitHub, Notion, SharePoint, Google Drive, Salesforce, and M-Files. An agent assigned a Knowledge Base can query that data to answer questions.

Enterprise feature (team-scoped access control) — see the Pricing Model.

How Retrieval Works

The whole pipeline runs inside Archestra on PostgreSQL with pgvector. There is no external vector database and no separate retrieval service to operate.

Indexing

Connectors run on a cron schedule. Each document goes through the same four steps.

1. Extract. Text is pulled from the source. Office documents and PDFs are read through format-specific extractors; PDF text comes from the document's text layer. A PDF without a text layer — a scan, for example — is skipped and counted in the sync run details. With a multimodal embedding model configured, images are embedded directly rather than described.
2. Chunk. The document is split into passages of roughly 512 tokens, on paragraph and sentence boundaries. Each chunk carries its document title and the document's metadata, so it can be matched on its own.
3. Add context. Optionally, the document is summarized once and that summary is indexed with every one of its chunks. See Contextual Retrieval.
4. Embed. Each chunk is vectorized with the configured embedding model and stored alongside a keyword index of the same text.

A document whose content has not changed since the last sync is skipped, so a re-sync only pays for what actually changed.

Querying

A search runs both a semantic and a keyword pass, then narrows the results.

1. Expand the query. The reranking model rewrites the question into a semantic phrasing and a set of keyword queries. This catches documents that use different words than the asker did. Identifiers, ticket numbers, and error codes are preserved verbatim.
2. Search both ways. Every query variant runs against the vector index and the keyword index in parallel.
3. Fuse. Results are merged with Reciprocal Rank Fusion, which favors chunks that rank well across several variants rather than one.
4. Rerank. The reranking model scores each surviving chunk against the original question and drops the irrelevant ones.
5. Filter by access. Chunks the asking user cannot read are removed. This applies to every result, at every stage.
6. Widen. The chunks either side of each hit are stitched back on, so a passage that starts mid-sentence arrives with its surroundings. See Context Expansion.

Citations

Every result carries the document title, its URL in the source system, the connector it came from, and the position of the chunk within the document. An agent answering from a Knowledge Base cites those sources in its reply, so a reader can open the original.

In the built-in chat, the agent also marks each claim with a numbered reference and lists a short verbatim quote for each — tagged with the chunk it came from — in a Sources section at the end of the answer. Archestra checks each quote against the chunk it cites — a quote found in no returned chunk is logged as a likely fabrication. The check never blocks or alters an answer, and it covers the built-in chat only. Set ARCHESTRA_KNOWLEDGE_BASE_QUOTE_VERIFICATION_ENABLED to false to turn it off.

Contextual Retrieval

Chunking separates a passage from the context it sits in. A chunk reading "the limit was raised to 5,000 per minute" is a poor match for "what is the rate limit on the billing API", because neither the product nor the subject appears in it.

Turn contextual retrieval on and each document is summarized once at ingest. That summary is indexed with every chunk of the document, so the chunk above becomes findable by a question naming the billing API. The summary shapes matching only — it is never added to the text the agent reads.

It costs one LLM call per document per sync, billed against the reranking model, and needs a reranking model that can generate text. Enable it with ARCHESTRA_KNOWLEDGE_BASE_CONTEXTUAL_RETRIEVAL_ENABLED.

Context Expansion

Search ranks chunks, but a chunk boundary falls wherever the chunker put it. A hit can begin mid-sentence or cut a table in half.

After ranking, the neighbouring chunks are stitched back onto each hit. Ranking is unaffected — this only widens the passage the agent reads. Expansion stops at any chunk the user cannot read, so it never becomes a way around access control. Set the radius with ARCHESTRA_KNOWLEDGE_BASE_CONTEXT_EXPANSION_RADIUS.

Keyword Search Language

The keyword index stems words so that different forms of one word match. Stemming is language-specific: "Katzen" and "Katze" only collapse to the same term under German rules.

Set the language on each connector under Advanced > Keyword Search Language, to match the language its documents are written in. Choose Simple to turn stemming off, which suits source code and mixed-language sources. One deployment can index an English wiki and a German one correctly at the same time. The setting applies on the connector's next sync.

Tuning

These settings are deployment-wide. See Deployment for the full reference.

Chunk size and contextual retrieval apply at ingest, so a change takes effect as each connector re-syncs.

Configuration

Open Settings > Knowledge. An embedding model must be set before Knowledge Bases can be used. A reranking model is optional.

Embedding Configuration

Pick the API key and embedding model. The embedding model vectorizes ingested documents so they can be queried semantically. The same model is used for both indexing and querying, which is why it is locked once saved.

• Key — only keys whose synced models have configured embedding dimensions appear in this list. If yours is missing, go to LLM Providers > Models, sync the provider, and set the dimensions for the embedding model. Supported dimensions: 384, 768, 1024, 1536, 3072. Keys connected through a subscription sign-in (an X Premium login, for example) do not appear — Knowledge needs an API key.
• Model — any embedding-capable model exposed by the selected key.

To change the embedding model, click Drop to clear the existing index — every document will need to be re-embedded on the next connector sync. The lock also applies in LLM Providers > Models: the configured model's embedding dimensions and input modalities cannot be edited until the configuration is dropped.

Image Embedding

Connectors index image files only when the configured embedding model accepts image input. These models do:

Archestra currently treats embedding models not listed above as text-only, even when their providers may offer multimodal variants that are not yet supported by the knowledge-base client. They cannot be marked as accepting image input in LLM Providers > Models. Connectors skip image formats the model does not accept — a GIF, for example. Images ingested under an earlier configuration are skipped at embedding time. The document completes without them, and the run shows the skipped count.

Titan Multimodal G1 accepts 256 text tokens per input. Cohere Embed v3 accepts 2048 characters — roughly 500 tokens. Longer text chunks are truncated before embedding — only the start of the chunk lands in the vector. Use a text embedding model when your corpus is mostly documents.

Reranking Configuration

Pick the model that scores and reorders search results by relevance. Reranking is optional — without it, search returns fused results unranked.

• Key — any LLM provider API key. Subscription sign-ins do not appear here either.
• Model — any chat model from that provider. Cohere Rerank models are also supported, on Cohere keys and Azure AI Foundry keys, and are called through their native rerank API.

A chat model also powers query expansion and contextual retrieval. A Cohere Rerank model only scores results, so both are skipped with one configured.

A chat reranker scores passages by returning a JSON object, so Archestra asks the endpoint to constrain the model's output to that shape. Test connection checks that it does. If the test reports that the model replied without a JSON object, the endpoint is not applying the constraint. Enable structured outputs on it — a self-hosted vLLM server needs this — or choose a model that supports them.

Document OCR

A scanned PDF has no text layer, so connectors cannot index it — the run reports it under "No text extracted". Configure Document OCR and syncs transcribe those pages with a vision model instead. The text becomes searchable like any other document.

• Key — an API key on a provider that accepts PDF input: Anthropic, OpenAI, Gemini, Bedrock, Azure, OpenRouter, or vLLM.
• Model — a vision-capable model from that provider. Self-hosted models (a vLLM server, for example) sync without modality metadata: mark the model's image or PDF input modality in LLM Providers > Models to make it selectable. Test connection sends a synthetic PDF page to verify the pair works.

OCR runs only on pages that yielded no text. A mixed document — a contract with a scanned signature page, for example — keeps its digital text and gets the scanned pages transcribed. Each transcribed page is one metered model call, recorded in LLM cost statistics under "Knowledge - OCR". A single document is capped at ARCHESTRA_KNOWLEDGE_BASE_OCR_MAX_PAGES_PER_DOCUMENT pages (default 100); pages past the cap stay untranscribed and the run says so.

Saving the configuration for the first time resets every connector's sync checkpoint. The next sync re-reads all sources, so documents previously skipped as unreadable are picked up. A run also carries an overall transcription budget: a document whose pages did not fit is indexed with a warning naming what was left out, and its untranscribed pages are only revisited when the source modifies the document or after another full re-sync.

Creating a Knowledge Base

A Knowledge Base is a set of connectors. Create one from the Knowledge page and assign connectors to get data from. The same Knowledge Base can be reused across multiple agents and MCP Gateways.

Knowledge Files

Knowledge Files is a repository for documents you upload directly — a signed contract that arrived by email, for example. A connector pulls from a source system; here you bring the file yourself. Open Knowledge > Files.

Upload PDF, Word, Markdown, CSV, JSON, HTML or plain text. The text is read at upload, and a file that cannot be read is refused right there — so nothing lands in the repository that would retrieve nothing later. A scanned PDF is accepted when Document OCR is configured; its pages are transcribed when the file is indexed.

Directories group documents and are flat — no sub-directories. Every document and directory has an audience: Organization, Teams, or Only me. Visibility follows the document into retrieval, so sharing a Knowledge Base with an agent does not widen who can read what is inside it.

Uploading stores a document; indexing makes it retrievable. Select documents or whole directories, choose Add to knowledge base, and pick an existing base or create one from the selection.

A file attached to a chat belongs to that conversation. To keep it, save it to the repository — from the attachment in the message, or from the Files panel, where you can select several at once. You choose the name, directory and visibility as you save, and can index it in one step.

Chat, Project, and Knowledge Files

Files live in three places, and each answers a different need.

A file can move up this ladder: save a chat attachment to the repository, then index it into a Knowledge Base.

Use Case: Vendor Security Reviews

A security analyst reviews vendor documents that arrive by email.

1. Upload the questionnaires and SOC 2 reports into a Vendor contracts directory, scoped to the security team.
2. Select the directory and add it to a Vendor security review Knowledge Base.
3. Assign that base to the review agent.
4. Ask the agent which vendors store customer data outside the EU. Every answer cites the document it came from.

Assigning to an Agent

An agent — or an MCP Gateway — reaches knowledge through the Tools & Knowledge Sources setting in its dialog, which has two modes:

• Auto — the agent can search every Knowledge Base and connector the chatting user can access, within the agent's environment. Nothing is assigned; the reachable set follows each user's own visibility.
• Custom — the agent searches only the Knowledge Bases and connectors you assign to it. Pick them under Knowledge Sources; the picker stays disabled until an embedding model is set (see Configuration).

Either mode is still filtered by the chatting user's own visibility, so an agent never surfaces a source the user could not read themselves. Once the agent has at least one reachable source, it gains a query_knowledge_sources tool that searches across them and returns the most relevant documents.

The output of query_knowledge_sources is treated as sensitive by default, which can impact the ability to use subsequent tools. See Archestra MCP Server, and AI Tool Guardrails, for more details.

Connectors pull data from external tools into Knowledge Bases. A connector can be assigned to multiple Knowledge Bases.

Visibility

Each connector has a visibility setting that determines which users can retrieve its data when an agent calls query_knowledge_sources. Connectors and Knowledge Bases are filtered by visibility throughout the UI: users only see sources they have access to, and only those can be assigned to agents and MCP Gateways.

Users with knowledgeSource:admin bypass document ACLs while querying. This permission does not grant access to manage auto-sync connectors.

Auto-sync connectors use dedicated knowledgeSourceAutoSync permissions for read, create, update, and delete actions. Admin and Platform Admin roles receive all four actions by default. Grant them to other users through a custom role. Users without these management actions can still query documents allowed by the synced ACLs.

Enterprise feature (team-scoped visibility and auto-synced ACLs) — see the Pricing Model.

Auto-Sync Permissions

Beta feature — off by default. Set ARCHESTRA_KNOWLEDGE_BASE_AUTO_SYNC_PERMISSIONS_ENABLED=true (or the ARCHESTRA_BETA master switch) to show the visibility option and its Users and Groups tabs. See Deployment.

Auto-sync permissions mirrors the source system's access control into Archestra. Each query returns only documents allowed by the latest permission snapshot. Users with knowledgeSource:admin bypass this filter.

The option appears when the beta flag and Knowledge enterprise feature are enabled. It also requires a supported connector and the applicable knowledgeSourceAutoSync:create or update action.

Auto-sync permissions works with the connectors marked Supported below. Limited means the source's access control is mirrored with a coarser audience model — the row says which. The others do not support it yet.

Credentials and Email Resolution

Permission sync uses the connector's upstream identity. That identity must read both content and its permission settings. Unreadable permission data fails closed, so the affected documents grant no access.

External accounts match Archestra users by email. A hidden or empty email leaves that account unassigned and removes it from resolved audiences. Accounts listed under Users can be assigned manually. An empty group roster must be fixed upstream because manual assignment cannot add members to it.

Each connector section lists its credential type, required scopes, and upstream setup. Use a dedicated identity whose visibility covers every configured source. Test connection validates authentication, but a successful test cannot prove access to every project or permission table.

Editing a connector. Saving new settings or credentials stops the permission sync running against the old ones — that run ends as Superseded. A replacement run starts straight away, so you don't wait for the next scheduled one.

Atlassian Organization Admin API Key

An organization admin API key reads managed accounts' emails through the Atlassian admin APIs. Add it to a Jira or Confluence Cloud connector. Permission sync can then resolve managed users whose profile email is private.

Create the key in Atlassian administration under Settings → API keys:

1. Select Create API key and name it.
2. Leave the key without scopes. Permission sync calls the classic admin APIs, which scopes do not cover.
3. Copy the key into the connector's Organization admin API key field.

The API token stays required. Atlassian does not accept admin API keys on the Jira and Confluence APIs.

Changing Cloud Instance on an existing Jira or Confluence connector changes its authentication method, so re-enter the token or password. Switching to Cloud also requires the Atlassian account email. Switching away from Cloud removes the stored organization admin key. For Server or Data Center, leave Username empty while entering a new personal access token to select PAT authentication; re-enter the username when changing a Basic-auth password.

Deleting and Restoring Knowledge Bases and Connectors

Deleting a knowledge base or connector moves it to a trash — the record is hidden but kept. Deleting a knowledge base leaves its connectors alone: they are unlinked from it, but they are not deleted and keep syncing. Deleting a connector does stop its syncs, and destroys its stored credential.

Anyone with knowledgeSource:delete switches the status filter to Deleted to open the trash. Restore returns the entry to active. A restored knowledge base is immediately live for its previously-assigned agents. A restored connector comes back disabled — re-authenticate it, then enable it to resume syncing.

Global admins can also delete an entry from the trash for good, with Delete permanently. For a knowledge base this destroys the record and its agent and connector assignments; its connectors survive. For a connector it destroys every document it has indexed, along with its run history and access mappings. Nothing brings either back.

Supported Connectors

Archestra ships with these built-in connector types. As an admin, open Page settings on Connectors and switch Available off for any your organization does not allow. A turned-off connector disappears from the pickers, and the API refuses to configure it. Connectors that already exist keep syncing until you delete them.

A sync that indexes nothing, on a connector that holds nothing, finishes as No documents rather than a success. The run names the likely cause -- content that was never shared with the credential, a folder that identity cannot see, or a file-type filter that excludes everything. A later sync that finds no changes is an ordinary success.

Jira

Sync issues and discussions from Atlassian Jira.

Indexed: issue descriptions, comments, and metadata from Jira Cloud or Server.

Authentication: Jira Cloud uses an Atlassian account email and API token. Jira Server and Data Center use a personal access token with the Username field empty. On releases without personal access tokens, enter the account username and password for Basic authentication.

Jira Auto-Sync Permissions

For Jira Cloud, use a dedicated Jira administrator:

1. Create an API token from Atlassian account security. Choose an unscoped token for the connector's site URL.
2. Grant the account Administer Jira and Browse users and groups global permissions.
3. Grant Browse Projects on every synced project. Add the account to every issue-security level whose issues it must index.
4. Create a separate organization admin API key to resolve private managed-account emails.

The product API token reads Jira data. The organization key reads managed-account profiles only. External accounts still need public profile emails or manual assignment.

Jira Server and Data Center content sync remains supported, but auto-sync permissions is not. Its permission APIs differ from Jira Cloud, and Jira exposes no equivalent REST API for issue-security membership. Personal access tokens require Jira Core or Software 8.14+, or Jira Service Management 4.15+. On older releases, enter the username in Username and the password in API Token / Personal Access Token to use Basic authentication.

Do not enable auto-sync permissions for Jira Cloud projects that use issue security. Jira requires both Browse Projects and issue-security membership, but the connector cannot currently enforce that intersection. Browse Projects grants through Project Lead or user/group custom fields, and dynamic issue-security holders such as Reporter and Assignee, are also unsupported.

Confluence

Sync wiki pages from Atlassian Confluence.

Indexed: pages from Confluence Cloud or Server.

Authentication: Confluence Cloud uses an Atlassian account email and API token. Confluence Server and Data Center 7.9+ use a personal access token with the Username field empty. On older releases, enter the account username and password for Basic authentication.

Confluence Auto-Sync Permissions

For Confluence Cloud, use a dedicated account with product access:

1. Create an unscoped API token from Atlassian account security.
2. Enter the site root, such as https://example.atlassian.net, without /wiki.
3. Grant View on every synced space. Add the account to every page and ancestor restriction it must index.
4. Grant Confluence Administrator when audit-based incremental permission reads are required.
5. Create a separate organization admin API key to resolve private managed-account emails.

A Cloud administrator does not automatically bypass page restrictions through the API. Unreadable pages never enter the index.

For Confluence Server or Data Center 7.9+, create a token under Profile > Personal access tokens and leave Username empty. On older releases, enter the username in Username and the password in API Token / Personal Access Token. Membership in the confluence-administrators group provides the broadest space and restricted-page visibility.

GitHub

Sync issues, pull request discussions, and repository files from GitHub.

Indexed: issues, pull requests, comments, and selected text files from GitHub.com or GitHub Enterprise Server. Repository file indexing defaults to Markdown and YAML files.

Authentication: a personal access token or a GitHub App. GitHub App credentials (App ID, installation ID, and private key) are stored once as an organization-level configuration under Settings -> GitHub; the connector references a saved configuration instead of holding its own credentials, so one App can back many connectors and skill imports.

GitHub Auto-Sync Permissions

A GitHub App is the preferred credential. Create one under Settings > Developer settings > GitHub Apps with these read-only permissions:

Install the App on every target repository. Generate a private key and copy its PEM value. Save the App ID, installation ID, API URL, and private key under Settings > GitHub, then select that configuration in the connector.

A fine-grained personal access token needs the same repository and organization permissions. Select every target repository. Its owner also needs write, maintain, or admin access to list collaborators. A classic token needs repo and read:org; authorize it for SAML SSO when the organization requires SSO.

GitHub exposes only each user's public profile email. No App or token permission reveals a private email, so those users need manual assignment.

GitLab

Sync issues and merge request discussions from GitLab.

Indexed: issues, merge requests, their comments, and (optionally) Markdown files from GitLab.com or self-hosted GitLab instances. System-generated notes (assignment changes, label updates, etc.) are filtered out.

Authentication: a personal access token.

GitLab Auto-Sync Permissions

Create a personal access token under Edit profile > Access > Personal access tokens. Grant only the read_api scope and set an expiry. The token's user needs Reporter or higher on every private project. Use an Owner of the configured top-level group for broad project discovery.

A regular token receives only public_email. On self-managed GitLab, an instance administrator token can read private email. Add admin_mode when Admin Mode is enabled. GitLab.com users without public email need manual assignment.

Each project is one permission scope. Its audience is the project's members with the Reporter role or higher — direct members, members inherited from ancestor groups, and members of invited groups, each at their effective access level. Guests are excluded: GitLab does not let them read code or confidential issues, so including them would over-share. Public and internal projects are readable by everyone in your Archestra organization.

Each sync snapshots one member roster per project, shown in the connector's Users and Groups tabs as <project path> members. A member whose email is hidden upstream stays unresolvable — assign them to an Archestra user from the Users tab, or ask them to set a public email on their GitLab profile.

Asana

Sync tasks and discussions from Asana projects.

Indexed: tasks and their user comments from selected Asana projects.

Authentication: a personal access token.

Asana Auto-Sync Permissions

Create a token in the Asana Developer Console. Personal access tokens have no selectable scopes and inherit the user's visibility. Add that user to every private project and team the connector syncs.

Asana Enterprise organizations can use a service account instead. A super admin creates it under Admin console > Apps > Service accounts. Grant Full Permissions, because standard task and membership APIs require that level.

Both credentials expose workspace-member emails. A missing email still needs manual assignment.

Each project is one permission scope. A project shared with the whole workspace grants every workspace member — guests excluded. Any other project grants its explicit members: users directly, teams through their team rosters. A task in several projects is readable through any of them; its scope is the union of those audiences. Task collaborators are granted individually on their tasks.

Each permission sync also snapshots workspace members and team rosters — the connector's Users and Groups tabs show every member with their assignment status, and an account whose email is hidden upstream can be assigned manually from the Users tab. Users added to a project directly — guests included — appear there too, under the synthetic Direct project members group. Limited-access team members get only the projects they are explicitly added to. Guests get only explicit project and task grants.

Permission reads run as the token's user. A project or roster the token cannot read stays fail-closed — use a token from a user who can see every synced project. A task removed from every synced project is hidden until a sync sees it again.

ServiceNow

Sync ITSM records from a ServiceNow instance.

Indexed: incidents, change requests, change tasks, problems, business applications, and published knowledge articles. Incidents are enabled by default; the rest are opt-in.

Authentication: the connector form uses basic auth. Create a dedicated user under User Administration > Users, enable Web service access only, and set a password. API-created connectors can instead leave Email empty and store a pre-issued OAuth bearer token in the API Token field; the connector does not refresh that token.

Required roles. Use a dedicated service account ("Web service access only" is fine). The account needs roles that can read every synced table:

The Can Read / Cannot Read criteria mappings (kb_uc_can_read_mtom, kb_uc_cannot_read_mtom) have no role-based read access out of the box — built-in roles such as knowledge_admin do not open them. Auto-sync permissions needs explicit access control lists (ACLs) on both tables.

Creating ACLs requires the security_admin role. ServiceNow grants it by elevation for the current session, and hides the New button on the ACL list until you elevate: open the profile menu, select Elevate role, and check security_admin. Then:

1. Go to System Security → Access Control (ACL) and select New. Set Type record, Operation read, and Name kb_uc_can_read_mtom with the field left as --None--. Under Requires role, add a role the service account holds. Submit.
2. Create a second ACL for the same table with the field set to *, which grants read on its fields.
3. Repeat both ACLs for kb_uc_cannot_read_mtom.

An account without the right roles fails in one of two ways, depending on the instance's ACLs: the sync errors with HTTP 403 "Insufficient rights to query records", or ServiceNow silently filters the rows and the sync succeeds with nothing ingested. Test the account directly before connecting: curl -u '<user>:<password>' 'https://<instance>.service-now.com/api/now/table/incident?sysparm_limit=1' should return a record, not an error and not an empty result.

ServiceNow Auto-Sync Permissions

ServiceNow decides record access with ACL rules, and those rules cannot be read through its REST API. For ITSM records and business applications, the connector grants each record to its participants instead: assignment group members plus the referenced users — the caller, the opener, and the assignee. Custom ACL conditions can make this audience differ from ServiceNow. To widen a table's audience, add role names under Role audiences (itil, for example) only when every holder can read every synced record in that table.

Knowledge articles follow ServiceNow's own permission model: Can Read and Cannot Read user criteria at knowledge-base and article level. The connector expands each criteria to its users, groups, roles, companies, departments, and locations. Script-based (advanced) criteria cannot be evaluated over the API: on an allow path they grant nobody; on a deny path the affected knowledge base or article is hidden from everyone. A knowledge base without criteria follows the instance's glide.knowman.block_access_with_no_user_criteria property — open to your whole Archestra organization when false, hidden when true or unreadable.

Required access. The connector account needs read access to these tables:

The Required roles section above covers these, including the explicit ACLs the criteria mapping tables need.

Misconfiguration behaves silently. ServiceNow filters out rows an account cannot read instead of returning an error. An under-privileged account therefore looks like missing data: content sync ingests nothing from a table it cannot read, and a permission table it cannot read makes the affected audiences fail closed — the documents exist but nobody can retrieve them. Each permission sync run reports how many audiences it could not read, so check the run details when documents seem to be missing or hidden. Knowledge bases in the HR Service Delivery scope (sn_hr_core) additionally need the sn_hr_core.content_reader role; without it their criteria read as empty and the articles fail closed.

Users granted directly on records appear in the connector's Users tab under the synthetic direct-grants group. A user whose sys_user email is empty stays unresolvable; assign such an account manually from the Users tab.

Notion

Sync pages and databases from a Notion workspace.

Indexed: pages from a Notion workspace.

Authentication: an internal connection's installation access token. A Workspace Owner creates the connection in the Notion Developer portal and copies the token from its Configuration tab.

Notion Auto-Sync Permissions

Create the credential in the Notion Developer portal:

1. As a Workspace Owner, create an internal connection in the target workspace.
2. Enable Read content and User information with email addresses capabilities.
3. Copy the installation access token into Integration Token.
4. Under Content access, connect every page or database root to sync. Access flows to child pages.

Support is Limited. Notion's API does not say who can see a page — there is no sharing endpoint, and teamspaces are not exposed. Archestra cannot mirror per-page access, so every synced page shares one workspace-wide audience:

• A synced page is visible to every workspace member whose Notion email matches an Archestra user's email.
• Each permission sync refreshes the member roster from Notion's users API. The connector page shows a Workspaces tab in place of Groups, with one row per connector: the workspace, named as it is in Notion.
• Guests are never in Notion's member listing, so a guest never gains access through Archestra.
• Member emails need the integration capability "read user information including email addresses" (integration settings, Capabilities tab). A member without a readable email stays unresolvable (fail-closed) until you assign them from the Users tab.

A page that is private or teamspace-restricted in Notion, but shared with the integration, becomes readable by every workspace member through Archestra. Set up the integration's access with that in mind:

• Share only workspace-appropriate content with the integration — a company wiki teamspace, for example.
• Do not share private pages or restricted teamspaces with the integration.
• For content that must reach a narrower audience, use a separate connector with Team-scoped visibility.

This is still stricter than an org-wide connector: access stops at the workspace member roster instead of your whole Archestra organization, and it updates as members join and leave.

SharePoint

Sync documents and site pages from SharePoint Online.

Indexed: documents and site pages from SharePoint Online. Supported document types include .txt, .md, .csv, .json, .xml, .html, .htm, .yaml, .log, .docx, .pdf, and .pptx. When a multimodal embedding model is configured, image files (.jpg, .jpeg, .png, .gif, .webp) up to 4 MB are also indexed.

Authentication: an Azure AD app registration with client credentials (OAuth2). The app needs the Sites.Read.All application permission on Microsoft Graph, with admin consent granted.

Where to find each value:

• Tenant ID — Microsoft Entra ID > App registrations > > Overview > Directory (tenant) ID.
• Client ID — Application (client) ID on the same page.
• Client Secret — the secret Value from Certificates & secrets (not the secret ID).
• Site URL — the exact SharePoint site web URL, not the display name.

SharePoint Auto-Sync Permissions

Create one single-tenant application under Microsoft Entra ID > App registrations. Add a client secret under Certificates & secrets, then copy its Value. Under API permissions, add the application permissions below and select Grant admin consent:

Each document library is one permission scope, and an item (file or folder) that breaks permission inheritance becomes its own scope — a document inherits its nearest such ancestor. Site pages follow the site's default library audience; per-page unique sharing is not modeled. Anonymous sharing links map to everyone in your Archestra organization; "people in your organization" links expand to the tenant's active users.

Microsoft 365 and Entra group grants carry the group's identity, and each permission sync snapshots their member rosters. Direct grantees appear under the synthetic direct-grants group. A group granted only on a single item is not discovered by roster sync. Its grant remains fail-closed until that group also appears on a library root.

SharePoint site groups are not currently expandable. The connector accepts a client secret, while SharePoint Online requires certificate authentication for app-only REST calls. Site-group grants remain fail-closed until certificate credentials are supported.

Sites.Read.All covers library and item grants. Extra permissions unlock more, progressively:

Each tier is detected at runtime: without it, that kind of grant or roster drops (fail-closed) and the rest of the sync proceeds.

OneDrive

Ingests files from OneDrive for Business (personal drives of specified users) via the Microsoft Graph API. Text is extracted from .txt, .md, .csv, .json, .xml, .html, .htm, .yaml, .log files, as well as .docx, .pdf, and .pptx documents. When a multimodal embedding model is configured (see Image Embedding), image files (.jpg, .jpeg, .png, .gif, .webp) up to 4 MB are also ingested and embedded directly.

Authentication uses an Azure AD app registration with client credentials (OAuth2). The app registration requires the Files.Read.All application permission on Microsoft Graph, and admin consent must be granted.

To configure the connector:

• Tenant ID comes from Microsoft Entra ID > App registrations > > Overview > Directory (tenant) ID
• Client ID comes from Application (client) ID on the same page
• Client Secret is the secret Value from Certificates & secrets, not the secret ID
• User IDs should be user principal names (UPNs, e.g. user@company.com) or Azure AD object IDs for the users whose drives you want to sync

Incremental sync uses the lastModifiedDateTime field to fetch only items modified since the last run.

OneDrive Auto-Sync Permissions

Create one single-tenant application under Microsoft Entra ID > App registrations. Add a client secret and copy its Value. Add these Microsoft Graph application permissions, then grant tenant-wide admin consent:

• Files.Read.All reads drive content and item permissions.
• User.Read.All resolves owners and direct user grants to emails.
• GroupMember.Read.All expands Microsoft 365 and Entra groups.
• Sites.FullControl.All enables sharing-aware delta permission scans.

Each configured user's drive is one permission scope, and an item (file or folder) that breaks permission inheritance becomes its own scope — a document inherits its nearest such ancestor. The drive's owner is always part of its audience. Anonymous sharing links map to everyone in your Archestra organization; "people in your organization" links expand to the tenant's active users.

Only groups granted on drive roots are expanded. A Microsoft 365 or Entra group granted only on a uniquely shared item gets no roster and remains fail-closed; manual assignment cannot repair it. Direct grantees appear under the synthetic direct-grants group. SharePoint site groups on personal drives also resolve no members and remain fail-closed.

Files.Read.All covers drive and item grants. Three more application permissions unlock more, progressively:

Each tier is detected at runtime: without it, that kind of grant or roster drops (fail-closed) and the rest of the sync proceeds.

Known Limitations

• Only OneDrive for Business (work/school accounts) is supported. Consumer OneDrive is not supported.
• Syncs the personal drive (/drive) of each specified user; shared libraries are not traversed.

Google Drive

Sync files from Google Drive (My Drive and Shared Drives).

Indexed: files from My Drive and Shared Drives. Supported document types include .txt, .md, .csv, .json, .xml, .html, .htm, .yaml, .log, .docx, .pdf, and .pptx. Google Workspace files (Docs, Sheets, Slides) are also indexed. When a multimodal embedding model is configured, image files (.jpg, .jpeg, .png, .gif, .webp) are indexed too. Files larger than 10 MB are skipped.

Authentication: pick one of three modes. The mode decides which Google identity the connector acts as, and so what it can index.

Use the Workspace domain mode if you have a Workspace tenant -- coverage keeps up with the organization on its own. Reach for one Google account when a single person's Drive is the corpus, or when nobody can change Admin console settings. Service account only suits a small, fixed set of folders somebody is willing to maintain.

Google Workspace Domain

A service account with domain-wide delegation impersonates users across your domain. Coverage follows the organization -- a drive created next week is picked up by the next sync, with nobody sharing anything by hand.

In the Google Cloud Console, create a service account, enable the Google Drive API and the Admin SDK API, and download the JSON key. Copy the service account's client ID from its Advanced settings.

In the Google Admin console, go to Security > Access and data control > API controls > Domain-wide delegation. Add that client ID with the two base scopes:

https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/admin.directory.user.readonly

Paste the JSON key into the connector and enter a Workspace admin address as the Delegated admin email. Setting a Folder ID or Drive IDs scopes the sync to those instead, and the connector then acts as that one admin.

One Google Account

Someone authorizes their own Drive through Google, and the connector indexes what they can see. Archestra stores a refresh token, so the sync keeps working once the first hour is up.

Only that one person authorizes -- whoever sets the connector up. Nobody else signs in to Google, and there is no per-user prompt. What they can see becomes readable by everyone the Knowledge Base is shared with, so pick the account whose view of Drive matches the audience you intend.

This mode needs a Google OAuth client on the deployment. Create a Web application client in the Cloud Console, enable the Google Drive API, and register the redirect URI the connector form shows you. Set ARCHESTRA_KNOWLEDGE_BASE_GOOGLE_DRIVE_OAUTH_CLIENT_ID and ARCHESTRA_KNOWLEDGE_BASE_GOOGLE_DRIVE_OAUTH_CLIENT_SECRET to that client's credentials.

Saving the connector sends you to Google. The connector page then names the connected account and offers Reconnect -- you need it if that account ever revokes access.

Service Account Only

The connector sees only what someone has shared with the service account's email address. Create the service account and key as above, then share each target folder or drive with that address.

Test connection checks the setup rather than just the credential. It confirms that impersonation works for the delegated admin, that the directory can be read when the sync will enumerate one, and that any folder or shared drive you named is reachable. The result says which of those failed.

Google Drive Auto-Sync Permissions

Use Google Workspace domain mode to resolve users and Google Groups. In addition to the two base scopes above, authorize https://www.googleapis.com/auth/admin.directory.group.readonly for group and group-member reads. The delegated account needs directory privileges to read users, groups, and group members. Test connection checks the base scopes but does not validate the group-directory scope.

Domain mode currently indexes every user's Drive, but permission sync lists files only as the delegated admin. Files visible only while impersonating another user remain fail-closed. Do not use domain-wide auto-sync permissions until per-user permission enumeration is supported.

For files the delegated admin can see, direct user grants resolve from the email in the permission list and group grants expand through the Admin SDK directory. Nested groups are not inherited into their parent roster; flatten the parent group upstream, or grant the child group or users directly.

One Google account and Service account only modes cannot read the Workspace directory. Their direct user grants work, but Google Group grants remain unresolved and fail closed.

Dropbox

Sync text and source files from a Dropbox account or team folder.

Indexed: files from a Dropbox account or team folder — text and source files (.md, .txt, .ts, .js, .py, .json, .yaml, .yml, .html, .css, .csv, .xml, .sh, .toml, .ini, .conf), documents (.pdf, .docx, .pptx, .xlsx — every sheet of a workbook, not just the first), and images (.png, .jpg, .jpeg, .gif, .webp) when the configured embedding model accepts image input. Files the connector cannot extract are reported as skipped on the run.

Authentication: a Dropbox access token from the Dropbox App Console. The connector stores this token directly and does not refresh it.

Dropbox Auto-Sync Permissions

Create a scoped app with Full Dropbox access. Add account_info.read, files.metadata.read, files.content.read, and sharing.read. Generate a member token when direct user and shared-folder grants are enough.

Group expansion requires a Dropbox Business team app. Add team_info.read, team_data.member, and groups.read, then have an active team administrator authorize the app. Paste the resulting team-linked token into Access Token.

App Console generated access tokens are short-lived testing credentials. The connector stores only the access token and cannot refresh it, so scheduled content and permission sync stop after expiration. Reconnect with a new token; durable background sync requires an offline OAuth flow, which is not yet supported.

Each shared folder is one permission scope — a file belongs to its nearest containing shared folder. Files outside every shared folder are visible only to the token's account. Shared-folder members resolve to their emails directly; pending invitees are excluded until they accept. A file shared with extra people directly carries those people as additional grants. A file shared directly with a group does not carry that group — only shared-folder group grants are mirrored.

A team-linked token expands granted groups, including the automatic team-wide group, to active members. A member token leaves group rosters empty and fail-closed; manual assignment cannot populate them. Direct grantees appear under the synthetic direct-grants group.

Shared links are not reflected. A file shared only by link stays visible to the audiences above, nobody more.

Linear

Sync issues, projects, and cycles from a Linear workspace.

Indexed: issues by default, with optional projects (and recent updates) and cycles.

Authentication: a Linear personal API key. Create one under Settings > Security & access > Personal API keys in Linear, then paste it into the connector's Personal Access Token field.

Linear Auto-Sync Permissions

Create a personal API key under Settings > Account > Security & Access > Personal API keys. Select Read and every team the connector will sync. Use a dedicated workspace owner or administrator that belongs to every private team; the role alone does not grant private-team access.

Linear returns member emails through the same key. No extra scope is required.

Linear's access unit is the team. Issues and cycles get their team's audience: a public team admits every workspace member, a private team only its listed members. Guests get access only through teams they were invited to. A project's audience is the members of its teams plus the users listed on the project. Each sync also snapshots every team's roster, so the connector's Users and Groups tabs show each member with their assignment status. Suspended accounts belong to no audience.

The API key sees what its owner can see. A private team the owner does not belong to syncs no content and grants no access. Use a key from an owner whose access matches what you want indexed.

Outline

Sync published documents from an Outline workspace.

Indexed: published documents. Both Outline cloud (https://app.getoutline.com) and self-hosted instances are supported.

Authentication: an Outline API key. Create one under Settings > API & Apps in your Outline workspace. Only documents the key has access to are synced.

Outline Auto-Sync Permissions

Create an API key under Settings > API Keys. An unscoped key inherits its creator's endpoint and collection access. For a scoped key, grant auth.info, documents.list, users.list, groups.list, groups.memberships, collections.list, collections.info, collections.memberships, collections.group_memberships, and shares.list.

Use a dedicated admin that belongs to every private target collection. Admin status does not automatically reveal a private collection. User emails come from users.list, so an account that cannot list users leaves all members unresolved.

Each collection is one permission scope. A collection's audience is its individual members, its granted groups, and — when the collection has workspace-wide default access — every active workspace member except guests. Guests only see collections they are explicitly added to, directly or through a group.

Each permission sync also snapshots group member rosters, so the connector's Users and Groups tabs show every member with their assignment status. Members granted a collection individually appear there too, under the synthetic direct-grants group. Workspace-wide default access appears as a group named after your workspace, holding every active non-guest member.

Published share links are the only public surface. A published document share maps that document — and its child documents, when the share includes them — to everyone in your Archestra organization. A published collection share does the same for the whole collection.

A collection whose permissions cannot be read hides its documents from everyone until a later sync reads them. Documents an Outline user can only reach through a direct per-document share (not a public link) are not carried over; they stay limited to the collection's audience.

Salesforce

Sync CRM records from a Salesforce org.

Indexed: CRM records from a Salesforce org. By default the connector syncs Account, Contact, Opportunity, and Case. You can list other object API names in the Objects field, or use Advanced Object Config JSON to pick exact fields and associations per object.

Authentication: a Salesforce username, password, and security token. The password field must contain the password directly concatenated with the security token (no separator). To get the token: log in to Salesforce, click your User Avatar > Settings, then go to My Personal Information > Reset My Security Token and check your email.

Example advanced config:

{
  "Lead": {
    "fields": ["FirstName", "LastName", "Company", "Email"],
    "associations": { "Account": ["Name"] }
  },
  "Case": {
    "fields": ["Subject", "Status", "Priority", "Description"]
  }
}

Id, Name, and LastModifiedDate are always included automatically.

Salesforce Auto-Sync Permissions

Use a dedicated Salesforce integration user. The same username, password, and security token authenticate content and permission reads. Configure its profile or permission sets with:

• API Enabled. In Setup > User Interface, enable SOAP API login(). If SOAP login restrictions are enforced, also grant Use Any API Auth. Salesforce retires this authentication method in Summer '27, so Archestra must migrate to External Client App OAuth before then.
• Read object and field permissions for every configured field and association.
• Read access to each object's owner fields and share object.
• Read access to User, Group, and GroupMember.
• View All Users for grant-holder email resolution.
• View All Records on every synced object, or View All Data, for complete ingestion.
• Modify Metadata Through Metadata API Functions, or Modify All Data, for organization-wide defaults.

Each object is one permission scope, decided by its organization-wide default. A public object grants every user in the Archestra organization. A private object resolves records from owners and modeled share rows. A contact inherits its parent account's audience.

Restriction rules, territory hierarchies, high-volume portal shares, object CRUD access, and field-level visibility are not modeled. Restriction rules can narrow access upstream, so do not sync restricted objects through auto-sync permissions. Private objects in large organizations resolve per record; use a longer permission-sync interval.

Every permission sync also snapshots the org's groups and queues with their (recursively expanded) memberships, plus record owners and per-user share grantees under the synthetic direct-grants group — so the connector's Users and Groups tabs show every grant-holder with their assignment status, and an account whose email is hidden (or matches no Archestra user's email) can be assigned manually from the Users tab. Inactive users stay visible in the roster but never resolve to access.

Web Crawler

Crawl static HTML pages from a documentation site or public web property.

Indexed: same-host HTML pages discovered from the start URL. The crawler extracts page text, removes common navigation and layout elements, and stores each page with its canonical URL when one is present.

Authentication: none in the initial version. The crawler only fetches pages reachable over HTTP(S).

Private and internal network addresses are blocked. Start URLs and discovered pages cannot resolve to loopback, link-local, RFC 1918 private ranges, cloud metadata endpoints, or other reserved address ranges. Hosts are checked before each fetch, but DNS records can change between validation and the final network request.

If the start URL is the site root, such as https://example.com/, and no include path prefixes are configured, the crawler can discover any same-host page within the configured depth and page limits.

Perforce (Helix Core)

Sync text files from Perforce Helix Core depot paths.

Indexed: files matching the configured extensions (defaults to .md, .yaml, .yml) under the configured depot paths, at their latest submitted revision. Files with non-text Perforce filetypes (binary, symlink, etc.) and files larger than 2 MB are skipped regardless of the extension list, so broadening the extensions (e.g. adding .txt, .json, or .xml) is safe even in depots that mix documentation with binary assets. Optional exclude paths carve subtrees (e.g. generated or vendored directories) out of the synced depot paths.

Authentication: a Perforce username with a login ticket, sent as HTTP basic authentication. The ticket must be valid for all hosts — generate it with p4 login -a -p. For long-lived access, use a service account whose group has an unlimited ticket timeout. The account needs read access to the configured depot paths.

The connector talks to the P4 REST API, served by the built-in P4 web server. An administrator must start the web server on the P4 Server (p4 webserver start -p <port>; it serves HTTPS automatically when the server has an SSL certificate configured). The REST API is a Perforce Technology Preview feature (introduced with P4 Server 2025.2), so its behavior may change between server releases. No p4 client binary and no client workspace (P4CLIENT) are required — files are listed and read directly in depot syntax over HTTP. For servers with self-signed certificates, provide the CA to the backend via standard Node.js trust configuration (NODE_EXTRA_CA_CERTS).

Incremental syncs are driven by submitted changelist numbers: after the initial sync, only files changed since the last synced changelist are re-indexed. File deletions are not propagated on incremental syncs; use Force re-sync to rebuild the index after large depot restructurings.

Each depot path and extension combination is listed in its own REST API request. On very large depots, server maxresults limits or per-request response bounds can reject a listing; configure narrower depot paths if the initial sync fails while listing files.

Perforce Auto-Sync Permissions

Use two dedicated Perforce identities:

1. Give the content user read access to every configured depot path. Generate its all-host ticket with p4 login -a -p.
2. Give the permission user admin access with dm.protects.allow.admin=1, or super access, plus a password. This identity runs p4 protects -a, reads groups, and reads every user spec.
3. Populate each Perforce user's Email field. Missing emails require manual assignment.

The connector supports auto-sync permissions. The REST API cannot read the protections table, so permission sync runs the p4 CLI in a dedicated in-cluster pod — the p4 shim. This requires the Kubernetes orchestrator. The shim pod is isolated: it accepts connections only from platform pods and connects out only to the Perforce server. For ssl: targets the server's certificate fingerprint is trusted on first use, like p4 trust. The image contains no Perforce software; the backend downloads the pinned p4 binary when it provisions the pod — see Deployment for the image and binary-source variables (air-gapped installs point them at an internal mirror).

Choosing the auto-sync-permissions visibility adds three fields to the form:

The permission user needs admin access with the server configurable dm.protects.allow.admin=1, or super access, to read the full protections table with p4 protects -a. The group and user-list reads require only list access.

Leave P4 Port empty on a normal server. The P4 web server runs inside the Perforce server, so Archestra dials the Server URL's host on port 1666 and works out the transport by trying plain and SSL. Fill the field in only when something else serves the REST API — an ingress in front of the web server, for example.

Test Connection checks the whole path. It reaches the server over the wire address, signs the admin user in, and reads the protections table, so a wrong address or an under-privileged account shows up here rather than at the first permission sync.

Permission sync runs in a pod of its own, one per connector. The pod exists while the connector syncs permissions and is removed when it stops — when you delete the connector, disable it, or change its visibility. Changing the server, the admin user or any credential replaces the pod, so a revoked credential stops working straight away.

A document's audience is the set of users whose effective read access to its depot path the protections table grants, walked with the exclusion lines honored. Access is evaluated as from an unnamed host, so host-restricted lines don't participate. Audiences are always individual users — granting through a group still resolves to its members, because an exclusion line can carve a member out of a granted group.

Users are matched to Archestra accounts by the Email field of their Perforce user spec. A user without a resolvable email is dropped from audiences (fail-closed); assign such accounts to Archestra users from the connector's Users tab.

M-Files

Sync versioned files and their source permissions from an M-Files vault.

Beta feature — off by default. Set ARCHESTRA_KNOWLEDGE_BASE_MFILES_CONNECTOR_ENABLED=true (or the ARCHESTRA_BETA master switch) to show the connector type. See Deployment.

Indexed: supported files attached to the configured M-Files object types. The default object type is 0 (documents). Text, Markdown, CSV, JSON, XML, HTML, YAML, Office documents, and PDFs are indexed; supported images are indexed when a multimodal embedding model is configured. Files larger than 25 MB are skipped.

Authentication: a dedicated M-Files login account, or an Application Account when ARCHESTRA_KNOWLEDGE_BASE_MFILES_OAUTH_ENABLED is enabled. Login accounts exchange a username and password for short-lived MFWS tokens. Application Accounts use OAuth client credentials.

Three more settings exist on the connector config and are tuned through the API rather than the form: objectTypeIds (managed object types, default 0), batchSize (documents per indexing batch, default 50) and permissionExtensionMethod (the installed VAF extension-method name, default ArchestraKnowledgePermissionSnapshot). Leaving them unset keeps the backend defaults.

M-Files Auto-Sync Permissions

Install the VAF Add On below before creating the connector. In M-Files Admin, add a dedicated login account to the vault and grant Change full control of vault. Also grant read access to every configured object, version, and file. The administrative role permits add-on calls but does not grant content visibility by itself.

For Application Account authentication, create an M-Files Application Account and map it to a vault user with the same access. Configure an identity-provider application for client credentials. Enter its token endpoint, client ID, client secret, token audience, M-Files authentication configuration name and scope, and Application Account username.

The add-on returns user and group rosters. Accounts without an email stay unresolved and need manual assignment.

M-Files VAF Add On

The Archestra VAF Add On is a vault application for M-Files Server. Syncing requires it. MFWS does not expose change tracking, exact permission reads, or group membership — the add-on supplies them from inside the vault. File content never flows through it. Every call requires the Change full control role, enforced by M-Files itself. Unreadable permissions fail closed.

Install it once per connected vault, from the connector form:

• Installation script — copy the one-line command and run it in PowerShell on the M-Files server as a system administrator. It downloads the add-on, installs it into the vault you choose, and restarts the vault.
• Manual installation — download the .mfappx package and install it in M-Files Admin: right-click the vault, then Applications, then Install.

Pre-built packages are published as m-files-vaf-add-on-v<version> releases on GitHub. The source lives in integrations/m-files-vaf-add-on; its README covers building from source and the add-on contract. For development deployments, two variables override where the install script gets the package — see Deployment.

Environments

A connector can be assigned a deployment environment. Only agents and gateways in the same environment can use its knowledge — a "dev" agent cannot query a "prod" connector. Unassigned connectors belong to the Default environment. See Environments.

Adding New Connector Types

See Adding Knowledge Connectors for a developer guide on implementing new connector types.