# CCPA Source: https://docs.contextual.ai/admin-setup/ccpa # GDPR Source: https://docs.contextual.ai/admin-setup/gdpr # HIPAA Source: https://docs.contextual.ai/admin-setup/hipaa # LLMs.txt Source: https://docs.contextual.ai/admin-setup/llms-txt Helping LLMs index Contextual AI content more efficiently Contextual AI documentation is provided in the llms.txt format — a standardized, LLM-friendly structure that makes it easy for large language models to parse and reference. ## Available Formats We provide two versions of our documentation: * [llms.txt](/llms.txt): A concise overview containing brief descriptions of key features and direct links to detailed documentation sections. * [llms-full.txt](/llms-full.txt): A comprehensive version that includes the same structure as llms.txt but with expanded details for each section. # Overview Source: https://docs.contextual.ai/admin-setup/overview Everything You Need to Get Up & Running with Contextual AI This section provides the core tools and guidance to configure, secure, and manage your Contextual AI environment. Start here to establish a reliable, governed foundation for building and running contextual AI workflows. ### [RBAC](/admin-setup/rbac) Manage access with fine-grained, role-based permissions that control who can view, modify, and administer your Contextual AI resources. Use RBAC to enforce least privilege, streamline collaboration, and maintain strong governance across teams. ### [Pricing & Billing](/admin-setup/pricing-and-billing) View and manage your organization’s subscription details, usage, and invoicing. This section explains how Contextual AI tracks consumption and helps you stay aligned with your plan as your workloads grow. ### [Security & Compliance](/admin-setup/soc2) Learn how Contextual AI protects your data through enterprise-grade security controls, encryption, governance policies, and compliance certifications. This section outlines the safeguards that keep your contextual workloads secure and audit-ready. ### [LLMs.txt](/admin-setup/llms-txt) Configure the `LLMs.txt` file to declare which models your organization uses, define model access rules, and ensure consistent behavior across environments. This section covers the file format, best practices, and how Contextual AI interprets these settings. # Pricing & Billing Source: https://docs.contextual.ai/admin-setup/pricing-billing Details on the cost structure for on-demand, usage-based plans The following guidance is intended for self-service users using Contextual AI in On-Demand mode. Users on provisioned throughput plans should direct any billing questions to their account managers. *** ## Usage Modes Contextual AI supports two usage modes: | **Mode** | **Description** | **Good For** | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **On-Demand**

Get started immediately by creating a Contextual AI Workspace. New workspaces receive \$25 in free credits.

Get an additional \$25 for signing up with a work email, and \$5 for watching the introductory video. | | | | **Provisioned Throughput**

Contact [sales@contextual.ai](mailto:sales@contextual.ai) or your account team. | | | ### Services You can also purchase expert support services for fixed terms, regardless of usage mode. With a service package, you get dedicated support from our Sales Engineering and Customer Machine Learning Engineering team to optimize performance and design full solutions. Contact [sales@contextual.ai](mailto:sales@contextual.ai) or your account manager for more information. *** ## On-Demand Pricing In On-Demand mode, all Contextual AI usage—whether through the UI or APIs—is billed as follows: * **query** is the endpoint called when you interact with an **Agent**. It invokes a multi-step RAG pipeline, and the cost of a given query is the sum of the costs for each step in the pipeline. These steps can be configured via **Agent Settings**. The average cost per query is \~\$0.05.
**STEP** **PRICE**
**Query Optimization**
Reformulation and decomposition.		 \$1/1M toks
**Encode**
Encode the user query for search.		 \$0.03/1M toks
**Rerank**
Rerank the retrieved chunks.		 \$0.12/1M toks
**Filter**
Filter chunks prior to generation.		 \$1/1M toks
**Generate**
Final response generation.		 Input: \$3/1M toks
Output: \$15/1M toks
**Groundedness & Safety**
Post-generation groundedness checks.		 \$1/1M toks
**API Reference:** [Agent Creation](https://docs.contextual.ai/api-reference/agents/create-agent) and [Query](https://docs.contextual.ai/api-reference/agents-query/query) Component APIs allow you to leverage key capabilities and models in a modular way.
**COMPONENT** **PRICE**
**Parse**
Parse unstructured documents into markdown and/or JSON.		 Basic: \$3/1K pgs
Standard: \$40/1K pgs
[Parse API Docs](https://docs.contextual.ai/api-reference/parse/parse-file)  
**Rerank**
Rerank based on natural language instructions.		 \$0.12/1M toks
[Rerank API Docs](https://docs.contextual.ai/api-reference/rerank/rerank)  
**Generate**
Generate using the most grounded language model in the world.		 Input: \$3/1M toks
Output: \$15/1M toks
[Generate API Docs](https://docs.contextual.ai/api-reference/generate/generate)  
**LMUnit**
Evaluate LLM output using natural language unit tests.		 \$3/1M toks
[LMUnit API Docs](https://docs.contextual.ai/api-reference/lmunit/lmunit)  
Documents added to **Datastores** are sent through our ingestion pipeline where they are parsed, chunked, and indexed in a vector store.
**STEP** **PRICE**
**Ingest** \$48.50/1K pages
**API Reference:** [Ingest](https://docs.contextual.ai/api-reference/datastores-documents/ingest-document) Pricing is subject to change. This pricing sheet reflects the latest information as of July 2025. *** ## Viewing Usage Stats & Adding Credit You can view your usage statistics and add more credits directly from the Contextual AI UI. ### Monitoring Usage & Spend To see your usage stats: 1. Click on **Usage** in the sidebar. The usage page shows a month-by-month breakdown of your usage and spend across the various charged components and endpoints. ### Adding & Managing Payment Methods In order to top-up credits, you must have a valid payment method linked to your Contextual AI workspace. To link a payment method: 1. Navigate to the **Billing** page in your workspace 2. Click on **Payment Methods** in the **Learn More** section 3. Click the **+New** button in the upper right of the page 4. Fill out the card or bank information in the form, then click **Next** 5. Fill out your billing address, then click **Save Payment Method** To remove an existing stored payment method: 1. Locate it in the list of payment methods 2. Click the menu icon 3. Click **Remove Payment Method** ### Credit Top-Up To continue using Contextual AI once your credits are depleted, you must add credits to your account. To top-up your credits: 1. Navigate to the **Billing** page in your workspace 2. Add a valid credit card under **Payment Methods,** if you havent already 3. Click **Add Credits** and fill out the corresponding form 4. Click **Next** and confirm the payment # Role-Based Access Control (RBAC) Source: https://docs.contextual.ai/admin-setup/rbac Define custom roles and permission bundles across agents, datastores, and more. *********Contextual AI is excited to introduce Role-Based Access Control (RBAC). RBAC is exclusive to customers on our Provisioned Throughput plan. Please contact your account team for more information.********* Admins can now define custom roles with tailored permission bundles across key objects — including Agents, Datastores, Billing, and other administrative features. Permissions can be scoped to specific Agents or Datastores, enabling finer-grained governance so every team member has the right level of access for their role. **Groups** make access management even simpler: add multiple users to a Group, then assign that Group to a Role. ## Roles ### Navigating to the Roles Page First, click `Settings` under `Admin` in the side-panel. Screenshot 2025-11-12 at 2.23.28 PM.png Next, click `Roles` under `Access Control`. Untitled 2.001.jpeg ### Default Roles Your tenant comes with three default roles: * `Admin`: Default role with full access to agents, datastores, and workspace settings. * `User`: Default role that every new user is automatically assigned to. This role **does not** come with any access to agents or datastores. * `Power User`: Default role that grants read access to all agents and datastores. By default, all new users are given the `User` role. They won't be able to access agents or datastores until they’re assigned a Role with higher-level permissions. Screenshot 2025-11-12 at 4.00.25 PM.png ### Creating a Custom Role You can create custom roles to meet your governance needs. Here are examples of custom roles you can create: * **Billing Admin** – Access to billing and usage features * **Data Ingestor** – Manage and ingest documents within specific Datastores * **Agent User** – Query and interact with designated Agents * **Agent Admin** – Maintain and optimize designated Agents First, click "New Role" in the **Roles** page. Screenshot 2025-11-12 at 2.36.20 PM.png Second, input a Role Name and Description. Click "Create role". Screenshot 2025-11-12 at 2.48.07 PM.png ### Configuring Role Permissions After creating a Role, you will be automatically directed to the Role page. The first tab is for you to configure permissions. Click “Add Permission” to associate a permission with the Role. Screenshot 2025-11-12 at 2.49.20 PM.png You will need to select what type of object you want to grant access to. You have three options: * `Agents`: Select this to give permissions on an agent * `Datastores`: Select this to give permissions on a Datastore * `Admin Tools`: Select this to give access to admin functions like billing and [annotating feedback](https://docs.contextual.ai/user-guides/feedback). Screenshot 2025-11-12 at 2.54.03 PM.png You can then configure permissions relevant to the object type you selected. #### Configuring Agent Permissions On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take. * `Query Agents`: This permission will let assigned users query the agent. * `Manage Agents`: This permission will let assigned users query the agent and edit its configs. It is a superset of `Query Agents`. * `Create Agents`: This permission will let assigned users create an agent. On the **right**, you’ll see the **objects** these permissions apply to. * For `Query Agents` and `Manage Agents`, you can select specific agents or select `All Agents`. * The`Create Agents` permission will apply globally. Screenshot 2025-11-12 at 3.00.35 PM.png **Important:** To query data from an agent’s linked datastores, a user must have both (i) `Query Agents` or `Manage Agents` and (ii) `Read Documents` (or higher) on the specific datastores. This ensures that when an agent is linked to multiple datastores, users can only query the ones they are permitted to access. Example: * `Agent_1` is linked to `Datastore_1` and `Datastore_2`. * The user has `Query Agents` on `Agent_1` and `Read Documents` on `Datastore_1` only. * As a result, only documents from `Datastore_1` will be retrieved. #### Configuring Datastore Permissions On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take. * `Read Documents`: This permission will let assigned users see the datastore and read documents inside. * `Manage Documents`: This permission will let assigned users read documents, as well as upload/delete them. It is a superset of `Read Documents`. * `Manage Datastores`: This permission will let assigned users manage documents, as well as edit the datastore configs. It is a superset of `Manage Documents`. * `Create Datastores`: This permission will let assigned users create a datastore. On the **right**, you’ll see the **objects** these permissions apply to. * For `Read Documents` , `Manage Documents` and `Manage Datastores`, you can select specific datastores or select `All Datastores`. * The`Create Datastores` permission will apply globally. Screenshot 2025-11-12 at 3.04.27 PM.png **Important:** To query data from an agent’s linked datastores, a user must have both (i) `Query Agents` or `Manage Agents` and (ii) `Read Documents` (or higher) on the specific datastores. This ensures that when an agent is linked to multiple datastores, users can only query the ones they are permitted to access. #### Configuring Admin Permissions On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take. * `Create Agents`: This permission will let assigned users create an agent. * `Create Datastores`: This permission will let assigned users create a datastore. * `Manage Billing & Usage`: This permission will let assigned users view and configure the `Billing` page. * `Manage Feedback Annotation`: This permission will let assigned users [view and annotate agent-level feedback](https://docs.contextual.ai/user-guides/feedback). All these permissions apply globally. Screenshot 2025-11-12 at 3.11.26 PM.png ### Review your Permissions Review all the permissions that you have provisioned for the Role. You can add more permissions or remove existing ones by clicking on the three dots beside each permission and clicking "Remove". Screenshot 2025-11-12 at 3.13.23 PM.png ### Assigning a User to a Role To assign a user to the Role, click the `Assigned Users` tab in the Roles Page. Screenshot 2025-11-12 at 3.14.24 PM.png Next, click "Assign Users". You'll be able to select multiple users to add to the role. Click "Confirm". Screenshot 2025-11-12 at 3.15.16 PM.png Third, review the users you've added. You can add more users or remove existing ones by clicking on the three dots beside a user and clicking "Remove". Screenshot 2025-11-12 at 3.16.16 PM.png **You’re all set!** The assigned users now have the access defined in this Role. ### Dealing with Role Conflicts If a user is assigned to two roles with different permissions on the same object, we will take the **union of permissions**. Example: * User is assigned to `Role A` which is given `Query Agents` on `All Agents` * User is also assigned to `Role B` which is given the higher-level `Manage Agents` on `Agent A`. * Outcome: * User will have `Manage Agents` on `Agent A` * User will have `Query Agents` on every other agent. ### Managing Roles After creating a Role, you can return to its configuration page at any time. To do so, navigate to the **Roles** page and click on the Role you want to edit. Screenshot 2025-11-12 at 3.30.02 PM.png You can also delete a Role by clicking on the three dots beside it and clicking "Delete". Screenshot 2025-11-12 at 3.26.12 PM.png ### Creating Agents and Datastores If a user has created an Agent or Datastore, an owner Role will automatically be created with `Manage Agent` or `Manage Datastore` permissions. The user will automatically be assigned to that Role. Screenshot 2025-11-12 at 3.45.49 PM.png ## Groups ### Navigating to the Groups page Groups can help simplify access management. You can add multiple users to a Group and assign the Group to a Role. First, click `Settings` under `Admin` in the side-panel. Screenshot 2025-11-12 at 2.23.28 PM.png Next, click "Groups" under "Access Control". Untitled 4.001.jpeg ### Creating a Group Click "New Group". Screenshot 2025-11-12 at 3.36.38 PM.png Fill in Group Name and Description Screenshot 2025-11-12 at 3.37.52 PM.png Click "Create group". You'll be automatically redirected to the Group page. ### Assigning Users to the Group Click the tab "Assigned Users". Screenshot 2025-11-12 at 3.40.01 PM.jpg Click "Assign Users" and select the users you want to include in the Group. Click "Confirm". Screenshot 2025-11-12 at 3.39.02 PM.png Review the users you have added. You can add more users to the Group or remove existing users by clicking the three dots and clicking "Remove". Screenshot 2025-11-12 at 3.39.32 PM.png ### Associating a Group with a Role Navigate to the first tab: "Roles". Screenshot 2025-11-12 at 3.43.47 PM.png Click "Add Roles". You can select roles to associate with your Group. Screenshot 2025-11-12 at 3.41.42 PM.png Click "Add Roles". You can add more roles or remove existing ones by clicking on the three dots and clicking "Remove". Screenshot 2025-11-12 at 3.46.40 PM.png **You're set!** Members of the Group now have have the access defined in the attached Roles. ### Managing a Group After creating a Group, you can return to its configuration page at any time. To do so, navigate to the **Groups** page and click on the Group you want to edit. Screenshot 2025-11-12 at 3.48.21 PM.png You can also delete a Group by clicking on the three dots beside it and clicking "Delete". Screenshot 2025-11-12 at 3.48.37 PM.png ## User Management You can view the roles and groups associated with each user. First, navigate to `Members` in the `Access Control` tab. You will see the list of members in your workspace. Screenshot 2025-11-24 at 11.53.27 AM.png To see the **roles** assigned to the user, click the `Expand` button in the `Roles` column. You will see (i) the assigned roles, (ii) the permissions included in each role, and (iii) whether it was assigned directly to the user or inherited via group membership. You can also open up the Role Page with the top-left button. Screenshot 2025-11-24 at 11.57.04 AM.png To see the **groups** that the user belongs to, click the `Expand` button in the `Groups` column. You will see (i) the user's groups and (ii) the roles associated with each group. You can also open up the Group Page with the top-left button. Screenshot 2025-11-24 at 12.03.25 PM.png # SOC 2 Source: https://docs.contextual.ai/admin-setup/soc2 Contextual AI SOC 2 Compliance ## Overview Contextual AI is **SOC 2 Type II certified**, demonstrating that our security controls and operational practices meet the highest standards for protecting enterprise data. ![Alt Text](https://cdn.sanity.io/images/aw1pcv4c/production/1676425030178745ab94dfe0a96604369d93aa9b-5760x3240.png?w=3840\&fm=webp\&q=75\&dpr=2) This certification verifies that our systems, processes, and safeguards operate effectively over time—not just at a single point of audit. *** ## What SOC 2 Type II Means SOC 2 Type II evaluates how well an organization upholds the **Trust Service Criteria**: * **Security** * **Availability** * **Confidentiality** An independent auditor verified that Contextual AI maintains strong, continuously monitored controls across all three criteria. *** ## Security at Every Layer ### Proven Security Controls Our compliance audit confirms consistent adherence to stringent policies and processes governing data handling, infrastructure, and operations. ### Data Protection * **Encryption in transit:** TLS 1.2+ * **Encryption at rest:** AES-256 * **Key management:** Cloud-native KMS services with restricted access ### Deployment Options Choose the environment that fits your organization’s security posture: * **SaaS** (fully managed) * **VPC** (private cloud) * **On-premises** (self-managed) ### Authentication & Access * Enterprise **SSO** with **SAML** or **OIDC** * **Role-based access control (RBAC)** for fine-grained permissions *** ## Core Security Controls | Category | Description | | ------------------------- | ---------------------------------------------------------------------------------------------- | | **Application Security** | Continuous SAST/SCA scanning, dependency monitoring, and vulnerability management | | **Business Continuity** | Kubernetes-based orchestration, automated failover, distributed infrastructure | | **Monitoring & Response** | Real-time detection via centralized security data lake and defined incident-response playbooks | | **Bug Bounty Program** | Ongoing responsible-disclosure program with independent security researchers | *** ## Continuous Compliance * SOC 2 Type II is one component of our broader compliance framework. * Contextual AI is hosted on **Google Cloud Platform**, which maintains its own certifications: SOC 2, SOC 3, PCI DSS, ISO/IEC 27017, and CSA STAR. * We continuously evaluate and update controls to address evolving security and privacy requirements for enterprise AI systems. *** ## Learn More * [SOC 2 Announcement](https://contextual.ai/blog/contextual-ai-is-soc-2-type-2-certified) * [Security Overview](https://contextual.ai/security) * [Trust Center](https://trust.contextual.ai/resources) – Request a copy of our SOC 2 Type II report * [Contact Support](https://contextual.ai/contact-us) for compliance or security-related inquiries # Get Metrics Source: https://docs.contextual.ai/api-reference/agents-query/get-metrics api-reference/openapi.json get /agents/{agent_id}/metrics Returns usage and user-provided feedback data. This information can be used for data-driven improvements and optimization. # Get Retrieval Info Source: https://docs.contextual.ai/api-reference/agents-query/get-retrieval-info api-reference/openapi.json get /agents/{agent_id}/query/{message_id}/retrieval/info Return metadata of the contents used to generate the response for a given message. # Provide Feedback Source: https://docs.contextual.ai/api-reference/agents-query/provide-feedback api-reference/openapi.json post /agents/{agent_id}/feedback Provide feedback for a generation or a retrieval. Feedback can be used to track overall `Agent` performance through the `Feedback` page in the Contextual UI, and as a basis for model fine-tuning. # Query Source: https://docs.contextual.ai/api-reference/agents-query/query api-reference/openapi.json post /agents/{agent_id}/query/acl Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions. # Query Source: https://docs.contextual.ai/api-reference/agents-query/query-1 api-reference/openapi.json post /agents/{agent_id}/query Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions. # Copy Agent Source: https://docs.contextual.ai/api-reference/agents/copy-agent api-reference/openapi.json post /agents/{agent_id}/copy Copy an existing agent with all its configurations and datastore associations. The copied agent will have "[COPY]" appended to its name. # Create Agent Source: https://docs.contextual.ai/api-reference/agents/create-agent api-reference/openapi.json post /agents Create a new `Agent` with a specific configuration. This creates a specialized RAG `Agent` which queries over one or multiple `Datastores` to retrieve relevant data on which its generations are grounded. Retrieval and generation parameters are defined in the provided `Agent` configuration. > Note that self-serve users are currently required to create agents through our UI. Otherwise, they will receive the following message: "This endpoint is disabled as you need to go through checkout. Please use the UI to make this request." # Delete Agent Source: https://docs.contextual.ai/api-reference/agents/delete-agent api-reference/openapi.json delete /agents/{agent_id} Delete a given `Agent`. This is an irreversible operation. Note: `Datastores` which are associated with the `Agent` will not be deleted, even if no other `Agent` is using them. To delete a `Datastore`, use the `DELETE /datastores/{datastore_id}` API. # Edit Agent Source: https://docs.contextual.ai/api-reference/agents/edit-agent api-reference/openapi.json put /agents/{agent_id} Modify a given `Agent` to utilize the provided configuration. Fields not included in the request body will not be modified. # Get Agent Metadata Source: https://docs.contextual.ai/api-reference/agents/get-agent-metadata api-reference/openapi.json get /agents/{agent_id}/metadata Get metadata and configuration of a given `Agent`. # Get Template Configuration Source: https://docs.contextual.ai/api-reference/agents/get-template-configuration api-reference/openapi.json get /agents/templates/{template} # List Acl Templates Source: https://docs.contextual.ai/api-reference/agents/list-acl-templates api-reference/openapi.json get /agents/templates/acl Retrieve a list of all available ACL Templates. Each ACL template combines a DB template with an ACL config. # List Agents Source: https://docs.contextual.ai/api-reference/agents/list-agents api-reference/openapi.json get /agents Retrieve a list of all `Agents`. # List Templates Source: https://docs.contextual.ai/api-reference/agents/list-templates api-reference/openapi.json get /agents/templates Retrieve a list of all available Templates. # Reset Agent Source: https://docs.contextual.ai/api-reference/agents/reset-agent api-reference/openapi.json put /agents/{agent_id}/reset Reset a given `Agent` to default configuration. # Save Template Source: https://docs.contextual.ai/api-reference/agents/save-template api-reference/openapi.json post /agents/{agent_id}/template # Get Balance Source: https://docs.contextual.ai/api-reference/billing/get-balance api-reference/openapi.json get /billing/balance Get the remaining balance for a tenant # Get Billing Metadata Source: https://docs.contextual.ai/api-reference/billing/get-billing-metadata api-reference/openapi.json get /billing/metadata Non admin endpoint for getting the billing metadata for a tenant. # Get Billing Mode History Source: https://docs.contextual.ai/api-reference/billing/get-billing-mode-history api-reference/openapi.json get /billing/billing_mode/history Get the billing mode history for a tenant for a specific month. Args: request: Request object containing year and month with validation user_context: User context with tenant admin permissions Returns: Billing mode history records for the specified month and year Returns at least one entry which is the mode of the first date of the given month, with potential mode changes in the middle of the month. If no record found, defaults to LEGACY mode. # Get Earliest Usage Date Endpoint Source: https://docs.contextual.ai/api-reference/billing/get-earliest-usage-date-endpoint api-reference/openapi.json get /billing/usages/earliest_date Get the earliest usage date for a tenant # Get Monthly Usage Endpoint Source: https://docs.contextual.ai/api-reference/billing/get-monthly-usage-endpoint api-reference/openapi.json get /billing/usages/monthly Get monthly usage data for a tenant with validation for year and month parameters. Args: request: Request object containing year and month with validation user_context: User context with tenant admin permissions resource_id: Optional[UUID]. If provided, get usage data for a specific resource. Otherwise, get aggregated usage data across all resources. Returns: Monthly usage records for the specified month and year # Get Top Up History Endpoint Source: https://docs.contextual.ai/api-reference/billing/get-top-up-history-endpoint api-reference/openapi.json get /billing/balance/top-ups Get the top-up history for a tenant. Paginated. # Get Content Metadata Source: https://docs.contextual.ai/api-reference/contents/get-content-metadata api-reference/openapi.json get /datastores/{datastore_id}/contents/{content_id}/metadata # Get Document Contents Source: https://docs.contextual.ai/api-reference/contents/get-document-contents api-reference/openapi.json get /datastores/{datastore_id}/contents # Delete Document Source: https://docs.contextual.ai/api-reference/datastores-documents/delete-document api-reference/openapi.json delete /datastores/{datastore_id}/documents/{document_id} Delete a given document from its `Datastore`. This operation is irreversible. # Edit Chunk Content Source: https://docs.contextual.ai/api-reference/datastores-documents/edit-chunk-content api-reference/openapi.json put /datastores/{datastore_id}/chunks/{content_id}/content Edit the content of a specific chunk in a datastore. This operation updates the chunk's text content and regenerates its embeddings. # Get Document Metadata Source: https://docs.contextual.ai/api-reference/datastores-documents/get-document-metadata api-reference/openapi.json get /datastores/{datastore_id}/documents/{document_id}/metadata Get details of a given document, including its `name` and ingestion job `status`. # Get Parse Results Source: https://docs.contextual.ai/api-reference/datastores-documents/get-parse-results api-reference/openapi.json get /datastores/{datastore_id}/documents/{document_id}/parse Get the parse results that are generated during ingestion for a given document. Retrieving parse results for existing documents ingested before the release of this endpoint is not supported and will return a 404 error. # Ingest Document Source: https://docs.contextual.ai/api-reference/datastores-documents/ingest-document api-reference/openapi.json post /datastores/{datastore_id}/documents Ingest a document into a given `Datastore`. Ingestion is an asynchronous task. Returns a document `id` which can be used to track the status of the ingestion job through calls to the `GET /datastores/{datastore_id}/documents/{document_id}/metadata` API. This `id` can also be used to delete the document through the `DELETE /datastores/{datastore_id}/documents/{document_id}` API. `file` must be a PDF, HTML, DOC(X), PPT(X), PNG, JPG, or JPEG file. The filename must end with one of the following extensions: `.pdf`, `.html`, `.htm`, `.mhtml`, `.doc`, `.docx`, `.ppt`, `.pptx`, `.png`, `.jpg`, `.jpeg`. # List Documents Source: https://docs.contextual.ai/api-reference/datastores-documents/list-documents api-reference/openapi.json get /datastores/{datastore_id}/documents Get list of documents in a given `Datastore`, including document `id`, `name`, and ingestion job `status`. Performs `cursor`-based pagination if the number of documents exceeds the requested `limit`. The returned `cursor` can be passed to the next `GET /datastores/{datastore_id}/documents` call to retrieve the next set of documents. # Update Document Metadata Source: https://docs.contextual.ai/api-reference/datastores-documents/update-document-metadata api-reference/openapi.json put /datastores/{datastore_id}/documents/{document_id}/metadata Post details of a given document that will enrich the chunk and be added to the context or just for filtering. If Just for filtering, start with "_" in the key. # Create Datastore Source: https://docs.contextual.ai/api-reference/datastores/create-datastore api-reference/openapi.json post /datastores Create a new `Datastore`. A `Datastore` is a collection of documents. Documents can be ingested into and deleted from a `Datastore`. A `Datastore` can be linked to one or more `Agents`, and conversely, an `Agent` can be associated with one or more `Datastores` to ground its responses with relevant data. This flexible many-to-many relationship allows `Agents` to draw from multiple sources of information. This linkage of `Datastore` to `Agent` is done through the `Create Agent` or `Edit Agent` APIs. > Note that self-serve users are currently required to create datastores through our UI. Otherwise, they will receive the following message: "This endpoint is disabled as you need to go through checkout. Please use the UI to make this request." # Delete Datastore Source: https://docs.contextual.ai/api-reference/datastores/delete-datastore api-reference/openapi.json delete /datastores/{datastore_id} Delete a given `Datastore`, including all the documents ingested into it. This operation is irreversible. This operation will fail with status code 400 if there is an active `Agent` associated with the `Datastore`. # Edit Datastore Configuration Source: https://docs.contextual.ai/api-reference/datastores/edit-datastore-configuration api-reference/openapi.json put /datastores/{datastore_id} # Get Datastore Metadata Source: https://docs.contextual.ai/api-reference/datastores/get-datastore-metadata api-reference/openapi.json get /datastores/{datastore_id}/metadata Get the details of a given `Datastore`, including its name, create time, and the list of `Agents` which are currently configured to use the `Datastore`. # List Datastores Source: https://docs.contextual.ai/api-reference/datastores/list-datastores api-reference/openapi.json get /datastores Retrieve a list of `Datastores`. Performs `cursor`-based pagination if the number of `Datastores` exceeds the requested `limit`. The returned `cursor` can be passed to the next `GET /datastores` call to retrieve the next set of `Datastores`. # Reset Datastore Source: https://docs.contextual.ai/api-reference/datastores/reset-datastore api-reference/openapi.json put /datastores/{datastore_id}/reset Reset the give `Datastore`. This operation is irreversible and it deletes all the documents associated with the datastore. # Generate Source: https://docs.contextual.ai/api-reference/generate/generate api-reference/openapi.json post /generate Generate a response using Contextual's Grounded Language Model (GLM), an LLM engineered specifically to prioritize faithfulness to in-context retrievals over parametric knowledge to reduce hallucinations in Retrieval-Augmented Generation and agentic use cases. The total request cannot exceed 32,000 tokens. See our [blog post](https://contextual.ai/blog/introducing-grounded-language-model/) and [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/02-generate/generate.ipynb). Email [glm-feedback@contextual.ai](mailto:glm-feedback@contextual.ai) with any feedback or questions. # LMUnit Source: https://docs.contextual.ai/api-reference/lmunit/lmunit api-reference/openapi.json post /lmunit Given a `query`, `response`, and a `unit_test`, return the response's `score` on the unit test on a 5-point continuous scale. The total input cannot exceed 7000 tokens. See a code example in [our blog post](https://contextual.ai/news/lmunit/). Email [lmunit-feedback@contextual.ai](mailto:lmunit-feedback@contextual.ai) with any feedback or questions. >🚀 Obtain an LMUnit API key by completing [this form](https://contextual.ai/request-lmunit-api/) # Parse File Source: https://docs.contextual.ai/api-reference/parse/parse-file api-reference/openapi.json post /parse Parse a file into a structured Markdown and/or JSON. Files must be less than 300MB and 2000 pages. We use LibreOffice to convert DOC(X) and PPT(X) files to PDF, which may affect page count. See our [blog post](https://contextual.ai/blog/document-parser-for-rag) and [code examples](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/04-parse/parse.ipynb). Email [parse-feedback@contextual.ai](mailto:parse-feedback@contextual.ai) with any feedback or questions. # Parse List Jobs Source: https://docs.contextual.ai/api-reference/parse/parse-list-jobs api-reference/openapi.json get /parse/jobs Get list of parse jobs, sorted from most recent to oldest. Returns all jobs from the last 30 days, or since the optional `uploaded_after` timestamp. # Parse Result Source: https://docs.contextual.ai/api-reference/parse/parse-result api-reference/openapi.json get /parse/jobs/{job_id}/results Get the results of a parse job. Parse job results are retained for up to 30 days after job creation. Fetching results for a parse job that is older than 30 days will return a 404 error. # Parse Status Source: https://docs.contextual.ai/api-reference/parse/parse-status api-reference/openapi.json get /parse/jobs/{job_id}/status Get the status of a parse job. Parse job results are retained for up to 30 days after job creation. Fetching a status for a parse job that is older than 30 days will return a 404 error. # Rerank Source: https://docs.contextual.ai/api-reference/rerank/rerank api-reference/openapi.json post /rerank Rank a list of documents according to their relevance to a query primarily and your custom instructions secondarily. We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. The reranker supports multilinguality. The total request cannot exceed 400,000 tokens. The combined length of the query, instruction and any document with its metadata must not exceed 8,000 tokens. See our [blog post](https://contextual.ai/blog/introducing-instruction-following-reranker/) and [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/rerank.ipynb). Email [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai) with any feedback or questions. # Get Users Source: https://docs.contextual.ai/api-reference/users/get-users api-reference/openapi.json get /users Retrieve a list of `users`. # Invite Users Source: https://docs.contextual.ai/api-reference/users/invite-users api-reference/openapi.json post /users Invite users to the tenant. This checks if the user is already in the tenant and if not, creates the user. We will return a list of user emails that were successfully created (including existing users). # Remove User Source: https://docs.contextual.ai/api-reference/users/remove-user api-reference/openapi.json delete /users Delete a given `user`. # Update User Source: https://docs.contextual.ai/api-reference/users/update-user api-reference/openapi.json put /users Modify a given `User`. Fields not included in the request body will not be modified. # Get Consent Source: https://docs.contextual.ai/api-reference/workspaces/get-consent api-reference/openapi.json get /workspaces/consent Retrieve the current consent status for the workspace. # Update Consent Source: https://docs.contextual.ai/api-reference/workspaces/update-consent api-reference/openapi.json put /workspaces/consent Update the consent status for the workspace. # Auto & Manual Syncing Source: https://docs.contextual.ai/connectors/auto-manual-syncing Detailed instructions on how to set up Auto & Manual Syncing ## Overview You can enable or disable **auto-syncing** at the top of your Datastore. When enabled, data changes are synced every 3 hours and permission updates every hour. **Note:** Box connectors automatically sync every 24 hours due to rate limits in the Box API. Please contact [connectors@contextual.ai](mailto:connectors@contextual.ai) if you need faster syncing. Please note that changes may not appear immediately. Contextual AI relies on the upstream data source’s API (for example, SharePoint), and updates are only pulled once the API confirms that changes have been made. Screenshot 2025-09-08 at 7.01.51 PM.png You can also trigger a **manual sync** to pull in changes. Screenshot 2025-09-08 at 7.01.55 PM.png Possible sync status indicators include: * **Syncing metadata:** We are syncing file metadata, users, and groups. We will need to sync metadata before we can begin ingestion. * **Processing:** We are ingesting any document or metadata changes. * **Synced / Green checkmark:** The sync has completed successfully. * **Partially Synced:** Some documents failed in the sync. To correct this issue, wait for 10-15 minutes and retrigger a manual sync. The failed documents will be retried. * **Failed:** All documents failed in the sync. Make sure that you have sufficient credits and retry with a manual sync after waiting for 10-15 minutes. If your sync still fails, please contact [connectors@contextual.ai](mailto:connectors@contextual.ai) for further assistance. # Box Source: https://docs.contextual.ai/connectors/box Connect your Box documents to Contextual AI ## Connecting Box Log in through the Contextual AI UI and follow these steps to configure Box as a data source. ### 1. Set Data Source Name & Type * Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right. * Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button. * On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step. **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance. ### 2. Review Access Levels & Set Account Type * Click the **Connect** button next to **Box**. * Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue. * Select your **Account Type**: **Admin account (read-only)** - You are setting up a connection for your organization and have admin access to your data source. **User account (read-only)** - You are setting up a personal connection or do not have admin access to your data source. Please [refer to this link](https://help.merge.dev/articles/9280406-why-are-specific-scopes-needed-for-file-storage-integrations) for a full list of permissions you need for admin authorization. * Click **Open window** to grant access to your Box account. ### 3. Grant Access & Sync Settings * Review the access permissions that will be granted from your Box account. * Click **Grant Access to Box** to continue. ### 4. Configure Sync Settings Contextual AI offers two ways to sync your data. You can choose to sync all your files or only specific folders in Box. #### Sync Options * **Share all files** - Grants access to all your content in Box. * **Share specific files** - Restricts access to only the folders you select. To share specific folders: * Hover over the folder and check the box to select it. * You can click into a folder to view its contents, but note that **only folders**—not individual files—can be selected. * Select one or multiple folders as needed. * Click **Confirm** to finalize your selections, then click **Next** once setup is complete. * You can review or edit your connection (for example, to choose a different folder) on the confirmation page. Click **Finish setup** to continue. ### 5. Create Datastore & Start Sync You’re now ready to start syncing your data. Click **Create** to initialize your connection and create your datastore. You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs your file metadata, users, and groups. This process is typically quick but may take a few hours if you have a large number of files, users, or groups. Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**. **Note:** You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested. You can check the progress bar to track how many documents remain to be processed. Once all documents finish ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use. # Confluence Source: https://docs.contextual.ai/connectors/confluence Connect your Confluence documents to Contextual AI ## Connecting Confluence Log in through the Contextual AI UI and follow these steps to configure Confluence as a data source. ### 1. Set Data Source Name & Type * Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right. * Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button. * On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step. **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance. ### 2. Review Access Levels, Set Account Type & Confluence Site * Click the **Connect** button next to **Confluence**. * Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue. * On the **Enter additional information** screen, enter the URL of your Confluence site and click **Next**. * On the **Connect Confluence** screen, click the **Open window** button. * Log in to your Confluence account. Review the requested permissions click **Accept** to continue. * Click the **Next** button to install the Forge app and proceed to the next step. ### 3. Grant Access & Sync Settings * Select the level of access to grant from your Confluence account: * **Share specific content** — Restricts access to only the content you select. * **Share all content** — Grants access to all your content in Confluence. * Click the **Finish setup** button on the **Success!** page. ### 4. Create Datastore & Start Sync You’re now ready to start syncing your data. Click **Create** to initialize your connection and create your datastore. You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs the contents of your Confluence site. This process is typically quick but may take some time if you have a large site. Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**. **Note:** You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested. You can check the progress bar to track the status of the sync. Once the contents of your Confluence site finishes ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use. # Entitlements Enforcement Source: https://docs.contextual.ai/connectors/entitlements-enforcement Using your Connector with Entitlements Enforcement ## Using your Connector with Entitlements Enforcement To use your connected Datastore, simply link it to an Agent and start querying. All original datasource entitlements are automatically enforced. If you do not have access to a document in the source system, two restrictions will apply: 1. The document will not be used to generate a response to the your query. 2. On the **Datastore** page, the document will be displayed as **Private Document**. You'll only be able to view documents that you have access to. Screenshot 2025-09-08 at 6.56.01 PM.png # Google Drive Source: https://docs.contextual.ai/connectors/google-drive Connect your Google Drive documents to Contextual AI ## Connecting Google Drive Log in through the Contextual AI UI and follow these steps to configure Google Drive as a data source. ### 1. Set Data Source Name & Type * Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right. * Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button. * On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step. **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance. ### 2. Review Access Levels & Set Account Type * Click the **Connect** button next to **Google Drive**. * Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue. * Select your **Account Type**: **Admin account (read-only)** - You are setting up a connection for your organization and have admin access to your data source. **User account (read-only)** - You are setting up a personal connection or do not have admin access to your data source. Please [refer to this link](https://help.merge.dev/articles/9280406-why-are-specific-scopes-needed-for-file-storage-integrations) for a full list of permissions you need for admin authorization. * Click **Open window** to authorize your account. ### 3. Authorize Connection & Sync Settings * In the pop-up window, select the account for authorizing the connection. * Click **Continue** to authorize the connection. ### 4. Configure Sync Settings Contextual AI offers two ways to sync your data. You can choose to sync all your files or only specific folders in Google Drive. #### Sync Options * **Share all files** - Grants access to all content in your Google Drive. * **Share specific folders** - Restricts access to only the folders you select. To share specific folders: * Hover over the folder and check the box to select it. * You can click into a folder to view its contents, but note that **only folders**—not individual files—can be selected. * Select one or multiple folders as needed. * Click **Confirm** to finalize your selections, then click **Next** once setup is complete. You can review or edit your connection (for example, to choose a different folder) on the confirmation page. Click **Finish** to continue. ### 5. Create Datastore & Start Sync You’re now ready to start syncing your data. Click **Create** to initialize your connection and create your datastore. You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs your file metadata, users, and groups. Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**. **Note:** The syncing process is typically quick, but may take a few hours if you have a large number of files, users, or groups.

You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested. You can check the progress bar to track how many documents remain to be processed. Once all documents finish ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use. # Local File Upload Source: https://docs.contextual.ai/connectors/local-file-upload Upload your documents to Contextual AI ## Uploading Your Local File Log in through the Contextual AI UI and follow these steps to upload a local file to use as a data source. ### 1. Set Data Source Name & Type * Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right. * Give your datastore a unique name, then click the **local file upload button** (the left panel) as the method for adding content to your datastore. Click the **Next** button. ### 2. Upload & Process Your File * On the **Datastores** page, click the **Upload** button. * Drag and drop or select the file to upload, and click the **Start Uploading** button. * After Contextual AI finishes processing your file, go back to the **Datasources** page. You should see your newly-created datasource with the previously uploaded file. # Microsoft OneDrive Source: https://docs.contextual.ai/connectors/microsoft-onedrive Connect your Microsoft OneDrive documents to Contextual AI ## Connecting Microsoft OneDrive You can sync your OneDrive data via the Contextual AI SharePoint connector. **Note:** Before getting started, ensure that you are a Super Admin. [Follow this guide](https://contextualai.integrations.guide/articles/10744024) to configure Super Admin permissions in SharePoint. Log in through the Contextual AI UI and follow these steps to configure OneDrive as a data source. ### 1. Set Data Source Name & Type * Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right. * Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button. * On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step. **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance. ### 2. Review Access Levels & Set Account Type * Click the **Connect** button next to **SharePoint**. * Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue. * Select your **Account Type**: **Admin account (read-only)** - You are setting up a connection for your organization and have admin access to your data source. **User account (read-only)** - You are setting up a personal connection or do not have admin access to your data source. Please [refer to this link](https://help.merge.dev/articles/9280406-why-are-specific-scopes-needed-for-file-storage-integrations) for a full list of permissions you need for admin authorization. * Click **Open window** to authorize your account. ### 3. Configure Sync Settings Contextual AI offers two ways to sync your data. You can choose to sync all your files or only specific folders. #### Sync Options * **Share all files** - Grants access to all content. This includes OneDrive folders within SharePoint sites and an individual user’s OneDrive folders. * **Share specific folders** - Restricts access to only the folders you select. You can pick specific OneDrive folders within SharePoint sites, but not an individual user’s OneDrive folders. Once you've selected and configured your sync option, click **Confirm** to finalize your selections, then click **Next** once setup is complete. Click **Finish setup** to continue. On the next page, click **Create** to initialize your connection and create your datastore. You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs your file metadata, users, and groups. Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**. You can check the progress bar to track how many documents remain to be processed. **Note:** The syncing process is typically quick, but may take a few hours if you have a large number of files, users, or groups.

You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested. Once all documents finish ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use. # Microsoft SharePoint Source: https://docs.contextual.ai/connectors/microsoft-sharepoint Connect your Microsoft SharePoint documents to Contextual AI ## Connecting Microsoft SharePoint Log in through the Contextual AI UI and follow these steps to configure SharePoint as a data source. You can sync OneDrive data via the SharePoint connector. For detailed instructions, please see [Connecting to OneDrive via Sharepoint](#connecting-to-onedrive-via-sharepoint) ### 1. Set Data Source Name & Type * Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right. * Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button. * On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step. **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance. ### 2. Review Access Levels & Set Account Type * Click the **Connect** button next to **SharePoint**. * Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue. * Select your **Account Type**: Admin account (read-only)\*\* - You are setting up a connection for your organization and have admin access to your data source. User account (read-only)\*\* - You are setting up a personal connection or do not have admin access to your data source. Please [refer to this link](https://help.merge.dev/articles/9280406-why-are-specific-scopes-needed-for-file-storage-integrations) for a full list of permissions you need for admin authorization. * Click **Open window** to authorize your account. ### 3. Configure Sync Settings Contextual AI offers two ways to sync your data. You can choose to sync all your files or only specific folders in Sharepoint. #### Sync Options * **Share all files** - Grants access to all content in Sharepoint. * **Share specific folders** - Restricts access to only the folders you select. To share specific folders: * Hover over the folder and check the box to select it. * You can click into a folder to view its contents, but note that **only folders**—not individual files—can be selected. * Select one or multiple folders as needed. * Click **Confirm** to finalize your selections, then click **Next** once setup is complete. * Click **Finish setup** to continue. On the next page, click **Create** to initialize your connection and create your datastore. You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs your file metadata, users, and groups. Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**. You can check the progress bar to track how many documents remain to be processed. **Note:** The syncing process is typically quick, but may take a few hours if you have a large number of files, users, or groups.

You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested. Once all documents finish ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use. # Overview Source: https://docs.contextual.ai/connectors/overview Connecting your data to Contextual AI Contextual AI data connectors enable you to seamlessly integrate data from third-party sources. Key features include: * **Full ingestion and indexing** - Data is ingested and indexed through our advanced pipeline, ensuring optimal performance and speed compared to live search. * [Entitlements enforcement](#using-your-connector-with-entitlements-enforcement) - Permissions from your upstream data sources are automatically synced and enforced within the Contextual platform. Users without access to a document cannot see it in the Datastore or query against it. * [Auto and manual syncing](#auto--manual-syncing) - Data updates are synced every 3 hours, while permissions are refreshed every hour to maintain freshness. You can also trigger a manual sync at any time to capture changes. * **Folder-level selection** - Sync only the folders you need. ### Supported Data Sources Contextual AI currently supports the following data sources: * [Box:](box) PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files * [Confluence:](confluence) PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files * [Google Drive:](google-drive) Google Docs, Google Slides, PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files * [OneDrive:](microsoft-onedrive) PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files * [Sharepoint:](microsoft-sharepoint) PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files **Coming Soon:** Support for Dropbox and Salesforce

Please email [connectors@contextual.ai](mailto:connectors@contextual.ai) for connector-related questions or feedback. # Fun Demos Source: https://docs.contextual.ai/examples/fun-demos Explore real-world use cases and live demos ## Overview These demos are playful, interactive examples that highlight the creativity and versatility of the Contextual AI platform. These demos go beyond traditional use cases to show how agents can understand context, adapt to different scenarios, and deliver surprisingly delightful results. Whether you're exploring quirky chatbots, imaginative data interactions, or unexpected applications of contextual intelligence, these demos offer a lighthearted way to experience the platform’s capabilities firsthand. * [McConaughAI: Building Matthew McConaughey with Contextual AI](https://colab.research.google.com/drive/1AY-lbs0B-9zRyK8AY0tHHlKcXEGk9sTs?usp=sharing#scrollTo=f3fiRy-MHNWo) - This demo shows how Contextual AI makes it easy to build a private, Matthew McConaughey-inspired RAG agent powered solely by curated source material. # Contextual AI Demos Source: https://docs.contextual.ai/examples/overview-demos Explore real-world use cases and live demos Contextual AI's demos showcase how our platform and API components power intelligent, grounded, and secure AI experiences across industries. Alt text ## Overview Each demo highlights a real-world scenario—from customer support copilots that draw on private knowledge bases to research assistants that understand context across documents and data sources. You’ll see how Contextual AI unifies retrieval, reasoning, and generation to deliver answers that are accurate, explainable, and compliant. ## Experiment with Contextual AI in Action Some of these demos are fully interactive, while others are full-realized notebooks that allow you to explore the platform’s capabilities hands-on, at the code level. Learn how developers use Contextual AI’s APIs, connectors, and structured output features to build reliable AI agents that adapt to enterprise workflows. ## More Resources For more demos and sample code, please visit the following: * [GitHub Repos](https://github.com/ContextualAI) * [Hugging Face](https://huggingface.co/ContextualAI) # RAG Agent Source: https://docs.contextual.ai/examples/rag-agent Explore real-world use cases and live demos ## Overview Contextual AI lets you create and run specialized AI agents that are powered by your data. This demo creates a retrieval-augmented generation (RAG) agent for a financial use case. The agent will answer questions based on the documents provided, but avoid any forward looking statements (e.g., "Tell me about sales in 2048") ## Scope This example can be completed in under 30 minutes and walks you through the core steps of building a simple RAG workflow: * **Create a Datastore:** The home for your unstructured documents. * **Ingest Documents:** We’ll upload a single PDF, though the platform scales to many formats—including HTML. * **Create a RAG Agent:** All you need to begin is a well-crafted system prompt. * **Query the Agent:** Get answers grounded entirely in your own data. ## Prerequisites * Contextual AI API Key * Python 3.9+ ## Running The Demo You can run the demo either locally or using Google Colab: * [VS Code Instructions](https://github.com/ContextualAI/examples/tree/main/02-hands-on-lab#-getting-started) * [Google Colab](https://colab.research.google.com/github/ContextualAI/examples/blob/main/02-hands-on-lab/lab1_create_agent.ipynb) # Google Sheets Tutorial Source: https://docs.contextual.ai/examples/tutorial-google-sheets Explore real-world use cases and live demos ## Overview This tutorial guides you through a Google Sheets script that integrates with Contextual AI. The script automates form filling by connecting to Contextual AI’s API, enabling dynamic, real-time population of form fields powered by a Contextual AI RAG agent. Alt text ## Features * Use Contextual AI RAG Agents directly from within Google Sheets * Real-time API integration ## Prerequisites * Access to Google Sheets * A Contextual AI API key *** ## Tutorial Steps To get started, make sure you have already set up your **Agent**. If note, you can [follow these directions](https://github.com/ContextualAI/examples/blob/main/01-getting-started/quick-start.ipynb). ### 1. Configuring the Sheets Script Ensure that the documents [Vanguard BND Prospectus](https://github.com/ContextualAI/examples/blob/main/04-sheets-script/data/F0928.pdf) and [iShares Government Bond Prospectus](https://github.com/ContextualAI/examples/blob/main/04-sheets-script/data/govt-ishares-u-s-treasury-bond-etf-fund-fact-sheet-en-us.pdf) are uploaded to your Agent’s datastore. 1. Open the [example Google Sheet](https://docs.google.com/spreadsheets/u/3/d/1Yh8SWJaF88Jz040j4dudSKJS5Npkbz4lxfdDHj9agkw/edit?usp=sharing) with the script installed. 2. Go to **`File → Make a copy`** (so you have your own version). 3. Go to **`Extensions → Apps Script`**. 4. Modify the `agent URL` and `API key` with your **Agent ID** and **API key**. 5. Add your form fields in **Column A**. 6. Add your instructions in **Column B** (hidden by default). *** ### 2. Running the Script * Custom **menu buttons** are already included to run the scripts. * Select the **three vertical dots** on the buttons to modify executed scripts. * Watch **Column C** for processing status updates. * Results appear **in real time** as they’re fetched. *** ## Code Structure The script consists of two main functions: ### 1. `fetchDataAndPopulateSheet()` Coordinates the data fetching process, manages sheet range selection, and schedules API calls. ```javascript theme={null} function fetchDataAndPopulateSheet() { const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet(); const loadingCell = sheet.getRange("D1"); loadingCell.setValue("Bear with us... asking Contextual AI..."); // update with your agent ID and API key const apiUrl = 'https://api.contextual.ai/v1/agents/99bd0fc6-75ca-4057-91b1-28dc1c261221/query?retrievals_only=false' const apiKey = 'key-ADD_YOURS'; try { const scopeMetadata = sheet.getRange(1, 3).getValue(); // Column B, Row 1 const formFieldsRange = sheet.getRange(5, 1, sheet.getLastRow() - 4, 2); // Columns A and B starting from Row 5 const formFieldsValues = formFieldsRange.getValues(); const rowsWithData = formFieldsValues .map(([field, instructions], idx) => ({ field, instructions, row: idx + 5 })) .filter(({ field, instructions }) => field && instructions); rowsWithData.forEach(({ row }) => { sheet.getRange(row, 3).setValue("Bear with us... asking Contextual AI..."); }); // Staggered execution of API calls rowsWithData.forEach((data, index) => { makeApiCall(data, scopeMetadata, apiUrl, apiKey, sheet); }); } catch (error) { console.error(`Error in fetchDataAndPopulateSheet: ${error.message}`); } finally { loadingCell.clearContent(); } } ``` ### 2. makeApiCall() Handles individual API calls to Contextual AI Formats request payload Processes API responses ``` function makeApiCall(data, scopeMetadata, apiUrl, apiKey, sheet) { const { field, instructions, row } = data; console.log(`Starting call: ${row}`) const messageContent = `Ignore the previous format. ${instructions}: ${field} (${scopeMetadata})`; const payload = { messages: [ { content: messageContent, role: "user", }, ], }; const options = { method: 'post', headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json', 'Accept': 'application/json', }, payload: JSON.stringify(payload), }; try { sheet.getRange(row, 3).setValue("Bear with us... asking Contextual AI..."); SpreadsheetApp.flush(); // Ensure the value is displayed before the API call const response = UrlFetchApp.fetch(apiUrl, options); const result = JSON.parse(response.getContentText()); console.log(`Finished call: ${row}`) const answer = result.message.content.trim(); const retrievalContents = JSON.stringify(result.retrieval_contents, null, 2); const attributions = JSON.stringify(result.attributions, null, 2); // Populate the sheet with the API response data sheet.getRange(row, 3).setValue(answer); // Column C (Answer) //sheet.getRange(row, 4).setValue(retrievalContents); // Column D (Retrieved Documents) //sheet.getRange(row, 5).setValue(attributions); // Column E (Evidence) SpreadsheetApp.flush(); } catch (error) { console.error(`Error in processing row ${row}: ${error.message}`); sheet.getRange(row, 3).setValue("Error: " + error.message); } } ``` ## Error Handling The script includes basic error handling: * API connection issues * Data formatting problems * Rate limiting responses * Invalid sheet ranges ## Security Considerations * Store API keys securely * Don't share sheets containing API credentials * Regularly rotate API keys * Limit script access to necessary users only ## Troubleshooting This guide assumes basic familiarity with Google Sheets and Apps Script. For detailed API documentation, refer to the [Contextual AI API docs](/api-reference/datastores/list-datastores). # RAG Evaluation with Ragas Source: https://docs.contextual.ai/examples/tutorial-rag-eval-ragas Explore real-world use cases and live demos ## Overview This tutorial demonstrates how to use Ragas to evaluate the quality of your Contextual AI's Retrieval Augmented Generation (RAG) agents. The purpose of this notebook is to show the flexibility of Contextual AI's platform to support external evaluation approaches. The approach shown here with Ragas can be used similarly with other evaluation tools. ### What is Ragas? Ragas is an open-source evaluation framework specifically designed for RAG systems. It provides several important metrics to assess the quality of both the retrieval and generation components: * **Faithfulness** - Measures if the generated answer is factually consistent with the retrieved context * **Context Relevancy** - Evaluates if the retrieved passages are relevant to the question * **Context Recall** - Checks if all information needed to answer the question is present in the context * **Answer Relevancy** - Assesses if the generated answer is relevant to the question A key advantage of Ragas is that it can perform reference-free evaluations, meaning you don't need ground truth answers to evaluate your Contextual AI RAG pipeline. This makes it particularly useful for evaluating production systems built with Contextual AI where labeled data may not be available. This tutorial assumes you already have a Contextual AI Agent setup. If you haven't, please follow the [Contextual AI Platform Quickstart](https://contextualai-new-home-nav.mintlify.app/quickstarts/platform) ## Scope This tutorial can be completed in under 30 minutes and covers: * Setting up the Ragas evaluation environment * Preparing evaluation datasets * Querying Contextual AI RAG agents * Calculating RAGAS metrics: * Faithfulness: Measures factual consistency with retrieved context * Context Recall: Evaluates completeness of retrieved information * Answer Accuracy: Assesses match with reference answers * Analyzing and exporting evaluation results ## Prerequisites * Contextual AI API Key * OpenAI API Key (for RAGAS evaluation) * Python 3.8+ * Required dependencies (listed in `requirements.txt`) ## Environment Setup Before running the notebook, install the required packages below. These libraries provide tracking, evaluation, export capabilities, and LLM access. ### Required Packages * **langfuse** – Tracking and observability * **ragas** – Core evaluation framework * **openpyxl** – Enables exporting results to Excel * **openai** – Provides LLM access (used internally by RAGAS) * **langchain-openai** – LangChain integration with OpenAI * **langchain-contextual** – Connects LangChain to Contextual AI Together, these packages form a complete evaluation pipeline. Installation may take a few minutes depending on your connection speed and whether you already have some dependencies installed. ```python theme={null} %pip install langfuse ragas openpyxl openai langchain-openai langchain-contextual --upgrade --quiet ``` You may need to restart the kernel to use updated packages. ## Import Dependencies With the environment ready, we can import the necessary libraries and initialize our clients. The imports are grouped for clarity and maintainability: ### Import Structure * **Standard library imports** — Core Python functionality * **Third-party imports** — Data processing and API interaction * **RAGAS imports** — Evaluation metrics and utilities * **Client initialization** — Contextual AI client and the evaluator LLM Contextual AI uses **GPT-4o** as the evaluator model, as high-quality evaluation depends on the model’s ability to understand nuance, interpret context, and accurately compare textual information. ```python theme={null} # Standard library imports import os import random import time import asyncio import uuid from typing import List, Dict, Any import requests # Third party imports import pandas as pd import tqdm import openai from langchain_openai import ChatOpenAI from contextual import ContextualAI from ragas.dataset_schema import SingleTurnSample from ragas.llms import LangchainLLMWrapper from ragas.metrics import Faithfulness, ContextRecall, AnswerAccuracy # API Keys os.environ["OPENAI_API_KEY"] = "API_KEY" os.environ["CONTEXTUAL_API_KEY"] = "API_KEY" # Initialize clients client = ContextualAI() evaluator_llm = LangchainLLMWrapper(ChatOpenAI(model="gpt-4o")) ``` ```python theme={null} def fetch_file(filepath): if not os.path.exists(os.path.dirname(filepath)): # Ensure the directory exists os.makedirs(os.path.dirname(filepath), exist_ok=True) # Create if not exists print(f"Fetching {filepath}") response = requests.get(f"https://raw.githubusercontent.com/ContextualAI/examples/main/01-getting-started/{filepath}") with open(filepath, 'wb') as f: f.write(response.content) fetch_file('data/eval_short.csv') ``` ``` Fetching data/eval_short.csv ``` ## Running The Notebook Once you've set up your environment and dependencies, continue preparing your evaluation data by following [Steps 3-8 in the example notebook](https://github.com/ContextualAI/examples/blob/main/07-evaluation-ragas/Using_RAGAS.ipynb), which includes testing your RAG pipeline and applying RAGAS metrics to your evaluation samples. * [Using\_RAGAS.ipynb](https://github.com/ContextualAI/examples/blob/main/07-evaluation-ragas/Using_RAGAS.ipynb) # Agent Composer YAML Cheat Sheet Source: https://docs.contextual.ai/how-to-guides/ac-yaml-cheatsheet A single-page reference for Agent Composer YAML Agent Composer is currently available in private preview for enterprise users. For more information or to request access, please contact your Contextual AI representative. Agent Composer YAML defines **executable agent workflows** as graphs.\ Each graph specifies **inputs → nodes → outputs** and runs via `/query/acl`. *** ## Minimal Graph ```yaml theme={null} inputs: query: str outputs: response: str nodes: generate: type: ResponseGenerationStep input_mapping: query: __inputs__#query __outputs__: type: output input_mapping: response: generate#response ``` *** ## Root-level Fields | Field | Required | Notes | | ----------- | -------- | ---------------------------------------- | | `inputs` | ✅ | Root graph accepts **only** `query: str` | | `outputs` | ✅ | Must be JSON-serializable | | `nodes` | ✅ | Execution steps | | `ui_output` | ⚠️ | Required if multiple outputs | *** ## Core Rules (Remember These) * Root graph: one input only (query) * All node inputs must be wired * Outputs must be JSON-serializable * Multiple outputs → set exactly one ui\_output * `__outputs__` node is mandatory *** ## Wiring Syntax ```yaml theme={null} node_name#output_key ``` Special nodes: * `__inputs__` → graph/subgraph inputs * `__outputs__` → graph outputs *** ## Node Template ```yaml theme={null} node_name: type: StepType config: {} config_overrides: {} input_mapping: input: upstream#output ``` Common fields: * `type` (required) * `input_mapping` * `config` (static) * `config_overrides` (runtime) * `ui_stream_types` *** ## Output Node ```yaml theme={null} __outputs__: type: output input_mapping: result: node#output ``` * No config * No outputs * Maps internal values → API outputs *** ## UI Streaming ```yaml theme={null} ui_stream_types: retrievals: true generation: true ``` * Declared per node * Multiple nodes may stream * Independent of `ui_output` *** ## Subgraphs (Reusable Workflows) Define: ```yaml theme={null} my_subgraph: inputs: query: str outputs: docs: List[str] nodes: ... ``` Use: ```yaml theme={null} retriever: type: subgraph:my_subgraph input_mapping: query: __inputs__#query ``` * Nestable * Reusable * Isolated I/O scope *** ## Conditional Execution ```yaml theme={null} conditional: type: ConditionalStep config: variable: score branches: - condition: ">= 0.8" executable: HighQuality - condition: "< 0.8" executable: LowQuality input_mapping: score: eval#score ``` * Top-down evaluation * First match executes * Branch `__inputs__` != graph inputs *** ## Agentic Research Pattern Standard flow: 1. `CreateMessageHistoryStep` 2. `AgenticResearchStep` 3. `GenerateFromResearchStep` ### Message History ```yaml theme={null} create_message_history: type: CreateMessageHistoryStep input_mapping: query: __inputs__#query ``` ### Agentic Research ```yaml theme={null} research: type: AgenticResearchStep ui_stream_types: retrievals: true ``` * Multi-turn agent loop * Plans and invokes tools * Produces structured research ### Tools ```yaml theme={null} tools_config: - name: search_docs step_config: type: SearchUnstructuredDataStep ``` Rules: * Use either step\_config or graph\_config * Inputs = basic Python types ### Final Generation ```yaml theme={null} generate: type: GenerateFromResearchStep ui_stream_types: generation: true ``` Consumes `message_history` and `research` as inputs *** ## Run a Graph (Python) ```python theme={null} graph = ExecutableGraph.from_yaml(yaml_string) graph.execute_graph({"query": "Hello"}) ``` ## API Response * `outputs` * `workflow_trace` * `dynamic_agent_trace` (if agentic steps used) *** ## Common Errors | Error | Fix | | ----------------------- | ---------------------- | | Missing node input | Wire it | | No `__outputs__` | Add output node | | Multiple outputs | Set `ui_output` | | Non-serializable output | Convert to basic types | # Agent Composer YAML Step Reference Source: https://docs.contextual.ai/how-to-guides/ac-yaml-reference An authoritative list of all the Agent Composer step types Agent Composer is currently available in private preview for enterprise users. For more information or to request access, please contact your Contextual AI representative. ## Overview This catalog lists step types available for use in Agent Composer YAML graphs, including their configuration parameters, required inputs, outputs, and supported UI stream types. *** ### AgenticResearchStep * **Description:** Runs a multi-turn agent loop that plans and invokes tools to gather information and produce structured research output. * **Config Parameters:** * `agent_config: Dict[str, Any] = required` * `tools_config: Optional[List[Dict[str, Any]]] = None` * `version: str = "0.1"` * **Inputs:** `message_history: List[MessageAndRole]` * **Outputs:** *(varies by implementation; commonly includes structured research output consumed by generation steps)* * **UI Stream Types:** `RETRIEVALS` > Tip: For final response synthesis, pair `AgenticResearchStep` with `GenerateFromResearchStep`. *** ### AppendStep * **Description:** Appends a given item to a list and returns the new list. * **Config:** None * **Inputs:** `list: List[Any]`, `element: Any` * **Outputs:** `output: List[Any]` * **UI Stream Types:** None *** ### AttributionStep * **Description:** Step to handle attributions. * **Config Parameters:** * `attribution: Optional[bool] = None` * `template_attribution: Optional[str] = None` * `attribution_model: Optional[str] = None` * `number_of_retrievals_for_attribution: Optional[int] = None` * **Inputs:** `generation_result: GenerationResult`, `chunks_info: List[Dict]` * **Outputs:** `attribution_result: AttributionResult` * **UI Stream Types:** `ATTRIBUTION` *** ### BuildPromptStep * **Description:** Step to build the final prompt. * **Config Parameters:** * `untrusted_system_prompt: Optional[str] = None` * `untrusted_no_retrieval_system_prompt: Optional[str] = None` * `template_seed: Optional[str] = None` * `template_query: Optional[str] = None` * `template_knowledge: Optional[str] = None` * `max_new_tokens: Optional[int] = None` * `skip_context_truncation: Optional[bool] = None` * `allow_multi_turn: Optional[bool] = None` * `avoid_commentary: Optional[bool] = None` * `attribution: Optional[bool] = None` * **Inputs:** `query: str`, `retrievals: Retrievals`, `retrieval_record: Retrieval`, `message_history: List[MessageAndRole]`, `chunks_info: List[Dict]` * **Outputs:** `retrieval_record: Retrieval`, `message_history: List[MessageAndRole]`, `chunks_info": List[Dict]` * **UI Stream Types:** `RETRIEVALS` *** ### CheckRetrievalNeedStep * **Description:** Step to check if retrieval is needed for the given query. * **Config Parameters:** * `should_check_retrieval_need: Optional[bool] = None` * `template_should_retrieve: Optional[str] = None` * **Inputs:** `query: str` * **Outputs:** `is_retrieval_needed: bool`, `retrievals: Retrievals` * **UI Stream Types:** None *** ### ConcatenateStep * **Description:** Concatenates two lists. * **Config:** None * **Inputs:** `list1: List[Any]`, `list2: List[Any]` * **Outputs:** `output: List[Any]` * **UI Stream Types:** None *** ### ContextualAgentStep * **Description:** Step to retrieve information from contextual agents. * **Config Parameters:** `agent_ids: Optional[List[str]] = None` * **Inputs:** `query: str` * **Outputs:** `retrievals: Retrievals` * **UI Stream Types:** `RETRIEVALS` *** ### ConstantStep * **Description:** Provides constant values as outputs. * **Config Parameters:** `value: Any = required` * **Inputs:** None * **Outputs:** `output: Any` * **UI Stream Types:** None *** ### ContextualizeChunk * **Description:** Contextualize chunk text with surrounding document context using VLM. * **Config Parameters:** * `shard_tokens: int = 20000` * `shard_overlap: int = 10000` * **Inputs:** `chunk: Dict[str, Any]`, `tenant_id: str`, `document_id: str` * **Outputs:** `chunk: Dict[str, Any]` * **UI Stream Types:** None *** ### CreateMessageHistoryStep * **Description:** Converts a query into a message history. * **Config Parameters:** * `enable_model_armor: Optional[bool] = None` * `should_check_retrieval_need: Optional[bool] = None` * `template_should_retrieve: Optional[str] = None` * `untrusted_system_prompt: Optional[str] = None` * `untrusted_no_retrieval_system_prompt: Optional[str] = None` * `template_seed: Optional[str] = None` * `template_query: Optional[str] = None` * `template_knowledge: Optional[str] = None` * `max_new_tokens: Optional[int] = None` * `skip_context_truncation: Optional[bool] = None` * `allow_multi_turn: Optional[bool] = None` * `avoid_commentary: Optional[bool] = None` * `attribution: Optional[bool] = None` * **Inputs:** `query: str` * **Outputs:** `message_history: List[MessageAndRole]` * **UI Stream Types:** `RETRIEVALS: False` *** ### DeleteMemberStep * **Description:** Deletes the specified key from a dict or a pydantic model. * **Config Parameters:** `allow_missing_key: bool = False` * **Inputs:** `input: Union[dict, BaseModel]`, `key: str` * **Outputs:** `output: Union[dict, BaseModel]` * **UI Stream Types:** None *** ### DocumentDownloadStep * **Description:** Downloads documents from ingestion storage using DownloadDocumentTool. * **Config:** None * **Inputs:** `tenant: dict`, `datastore_id: UUID`, `short_path: str` * **Outputs:** `content: str`, `file_name: str`, `document_id: str`, `full_gcs_path: str`, `content_type: str`, `size_bytes: int` * **UI Stream Types:** None *** ### EntitleRetrievalsStep * **Description:** Post-process retrievals. * **Config:** None * **Inputs:** `retrievals: Retrievals` * **Outputs:** `retrievals: Retrievals`, `entitlements_api_time_elapsed: float` * **UI Stream Types:** None *** ### ExtractChunkMetadata * **Description:** Extract key-value metadata from chunk text using VLM. * **Config:** None * **Inputs:** `chunk: Dict[str, Any]`, `prompt: str`, `vlm_model: str` * **Outputs:** `metadata: Dict[str, Any]`, `chunk: Dict[str, Any]` * **UI Stream Types:** None *** ### ExtractMetadataStep * **Description:** Extract metadata from PDF using ExtractMetadataTool. * **Config:** None * **Inputs:** `content: str`, `full_gcs_path: str`, `user_id: UUID`, `file_name: str` * **Outputs:** `shard_metadata_list: List[ShardMetadata]` * **UI Stream Types:** None *** ### FileAnalysisInputStep * **Description:** Analyze files uploaded at query time. * **Config:** None * **Inputs:** `query: str` * **Outputs:** `retrievals: Retrievals` * **UI Stream Types:** `RETRIEVALS` *** ### FilterRetrievalsStep * **Description:** Filter retrievals. * **Config Parameters:** * `template_filter: Optional[str] = None` * `filter_retrievals: Optional[bool] = None` * `filter_model: Optional[str] = None` * `structured_output: Optional[bool] = None` * `untrusted_filter_prompt: Optional[str] = None` * `enable_batch_processing: Optional[bool] = None` * **Inputs:** `query: str`, `retrievals: Retrievals` * **Outputs:** `retrievals: Retrievals` * **UI Stream Types:** None *** ### GenerateEmbeddingsStep * **Description:** Generate embeddings for the query. * **Config Parameters:** * `max_encoder_length: Optional[int] = None` * `retrieval_encoder_model: Optional[str] = None` * **Inputs:** `query: str`, `reformulated_query: str`, `expanded_queries: List[str]` * **Outputs:** `query_embedding: List[float]`, `merged_embeded_reformulated_queries: List[Tuple[List[float], str]]` * **UI Stream Types:** None *** ### GenerateFromResearchStep * **Description:** Generate a response. * **Config Parameters:** * `model_name_or_path: str` * `base_url: Optional[str] = None` * `identity_guidelines_prompt: str = "You are a helpful assistant made by Contextual AI."` * `response_guidelines_prompt: str = "You should respond in a friendly and helpful manner."` * `litellm_modify_params: bool | Literal["auto"] = "auto"` * `version="0.1"` * **Inputs:** `message_history: List[MessageAndRole]`, `research: List` * **Outputs:** `response: str` *** ### GenerationStep * **Description:** Generate a response. * **Config Parameters:** * `temperature: Optional[float] = None` * `max_new_tokens: Optional[int] = None` * `top_p: Optional[float] = None` * `frequency_penalty: Optional[float] = None` * `seed: Optional[int] = None` * `attribution: Optional[bool] = None` * **Inputs:** `message_history: List[MessageAndRole]`, `chunks_info: List[Dict]`, `disable_streaming: bool` * **Outputs:** `generation_result: GenerationResult` * **UI Stream Types:** `GENERATION` *** ### GetAgentInfoStep * **Description:** Answers questions about the agent itself. * **Config:** None * **Inputs:** `query: str` * **Outputs:** `generation_result: GenerationResult` * **UI Stream Types:** None *** ### GetDatastoreStatisticsStep * **Description:** Handle datastore statistics (as provided). * **Config:** None * **Inputs:** `query: str` * **Outputs:** `generation_result: GenerationResult` * **UI Stream Types:** None *** ### GetDatastoreSummaryStep * **Description:** Aggregates results to generate a datastore summary. * **Config:** None * **Inputs:** `datastore_statistics: GenerationResult`, `documents_summary: GenerationResult`, `query: str` * **Outputs:** `generation_result: GenerationResult` * **UI Stream Types:** None *** ### GetDocumentsSummaryStep * **Description:** Generates a summary of documents in the datastore. * **Config:** None * **Inputs:** `query: str` * **Outputs:** `generation_result: GenerationResult` * **UI Stream Types:** None *** ### GetMemberStep * **Description:** Extract values from dictionaries or object attributes. * **Config Parameters:** `key: str = required` * **Inputs:** `input: Union[dict, BaseModel]` * **Outputs:** `output: Any` * **UI Stream Types:** None *** ### GetPlatformInfoStep * **Description:** Answers questions about the platform itself. * **Config:** None * **Inputs:** `query: str` * **Outputs:** `generation_result: GenerationResult` * **UI Stream Types:** None *** ### GroundednessStep * **Description:** Compute groundedness scores. * **Config Parameters:** * `attribution: Optional[bool] = None` * `calculate_groundedness: Optional[bool] = None` * **Inputs:** `generation_result: GenerationResult`, `attribution_result: AttributionResult`, `chunks_info: List[Dict]` * **Outputs:** `groundedness_scores: List[GroundednessScore]` * **UI Stream Types:** `GROUNDEDNESS` *** ### IndexChunkMetadata * **Description:** Index chunk with metadata in ElasticSearch. * **Config:** None * **Inputs:** `chunk: Dict[str, Any]`, `metadata: Dict[str, Any]`, `index_config: Dict[str, str]`, `tenant_id: str`, `document_id: str` * **Outputs:** `indexed: bool`, `chunk_id: str` * **UI Stream Types:** None *** ### IndexMetadataStep * **Description:** Index metadata into Elasticsearch using IndexMetadataTool. * **Config:** None * **Inputs:** `shard_metadata_list: List[ShardMetadata]`, `tenant: dict`, `datastore_id: UUID` * **Outputs:** `doc_id_list: List[str]` * **UI Stream Types:** None *** ### IndexStep * **Description:** Return the element at a given index of a list. * **Config:** None * **Inputs:** `list: List[Any]`, `index: int` * **Outputs:** `output: Any` * **UI Stream Types:** None *** ### IsFirstTurnStep * **Description:** Returns whether this is the first turn in a multi-turn interaction. * **Config:** None * **Inputs:** None * **Outputs:** `is_first_turn: bool`, `turn_count: int` * **UI Stream Types:** None *** ### JSONCreatorStep * **Description:** Creates JSON objects with dynamic variable substitution using `$`. * **Config Parameters:** `schema: str = required` * **Inputs:** Dynamic (based on `$variables` in schema) * **Outputs:** `json: Dict[str, Any]` * **UI Stream Types:** None *** ### LanguageModelStep * **Description:** Generic language model inference with template variables. * **Config Parameters:** * `prompt_template: str = required` * `model_id: str = required` * `temperature: float = 0.7` * `max_tokens: int = 1000` * `structured_output: Optional[Dict] = None` * **Inputs:** Dynamic (template variables) * **Outputs:** `response: str` * **UI Stream Types:** None *** ### LengthStep * **Description:** Return the length of a list. * **Config:** None * **Inputs:** `list: List[Any]` * **Outputs:** `output: int` * **UI Stream Types:** None *** ### MCPClientStep * **Description:** Execute tools on Model Context Protocol servers. * **Config Parameters:** * `server_url: str = required` * `tool_name: str = required` * `tool_args: str = required` * `transport_type: str = "http"` * `connection_timeout: int = 30` * `server_name: Optional[str] = None` * `auth_headers: Optional[Dict[str, str]] = None` * **Inputs:** Dynamic (based on `tool_args`) * **Outputs:** `mcp_result: Dict[str, Any]` * **UI Stream Types:** None *** ### MergeStep * **Description:** Merge two dicts (or pydantic models). * **Config Parameters:** `allow_key_conflicts: bool = False` * **Inputs:** `dict1: Union[dict, BaseModel]`, `dict2: Union[dict, BaseModel]` * **Outputs:** `output: Union[dict, BaseModel]` * **UI Stream Types:** None *** ### ModelArmorFilterUserPromptStep * **Description:** Send user prompt to model armor for safety check. * **Config Parameters:** `enable_model_armor: Optional[bool] = None` * **Inputs:** `query: str` * **Outputs:** None * **UI Stream Types:** None *** ### ProcessMetadataStep * **Description:** Process metadata for retrievals. * **Config:** None * **Inputs:** `retrievals: Retrievals` * **Outputs:** `retrievals: Retrievals` * **UI Stream Types:** None *** ### QueryDecompositionStep * **Description:** Decompose the query. * **Config Parameters:** * `query_decomposition_prompt: Optional[str] = None` * `query_decomposition_model: Optional[str] = None` * `enable_query_decomposition: Optional[bool] = None` * **Inputs:** `query: str` * **Outputs:** `expanded_queries: List[str]` * **UI Stream Types:** None *** ### QueryExpansionStep * **Description:** Expand the query. * **Config Parameters:** * `query_expansion_prompt: Optional[str] = None` * `query_expansion_model: Optional[str] = None` * `enable_query_expansion: Optional[bool] = None` * **Inputs:** `query: str` * **Outputs:** `reformulated_query: str`, `documents_filters: Optional[Union[CompositeMetadataFilter, BaseMetadataFilter]]` * **UI Stream Types:** `QUERY_REFORMULATION` *** ### QueryMultiturnStep * **Description:** Handle query multiturn. * **Config Parameters:** * `query_multiturn_model: Optional[str] = None` * `allow_multi_turn: Optional[bool] = None` * `untrusted_multiturn_system_prompt: Optional[str] = None` * `template_query_multiturn: Optional[str] = None` * **Inputs:** `query: str` * **Outputs:** `reformulated_query: str` * **UI Stream Types:** `QUERY_REFORMULATION` *** ### QueryRegexStrippingStep * **Description:** Strip the query. * **Config Parameters:** `query_regex_stripping: Optional[List[str]] = None` * **Inputs:** `query: str` * **Outputs:** `reformulated_query: str` * **UI Stream Types:** None *** ### ReformulateQueryStep * **Description:** Reformulate a query for datastore search. * **Config Parameters:** None * **Inputs:** `query: str` * **Outputs:** `reformulated_query: str`, `translate_needed: bool`, `detected_language: str` * **UI Stream Types:** `QUERY_REFORMULATION` *** ### RerankRetrievalsStep * **Description:** Rerank retrievals. * **Config Parameters:** `rerank_top_k: Optional[int] = None`, `reranker: Optional[str] = None`, `rerank_retrievals: Optional[bool] = None`, `rerank_instructions: Optional[str] = None`, `reranker_score_filter_threshold: Optional[float] = None`, `rerank_with_llm: Optional[bool] = None`, `template_rerank: Optional[str] = None`, `structured_output: Optional[bool] = None`, * **Inputs:** `query: str`, `retrievals: Retrievals` * **Outputs:** `retrievals: Retrievals` * **UI Stream Types:** None *** ### ResponseGenerationStep * **Description:** Generate a response based on query + retrievals. * **Config Parameters:** None * **Inputs:** `retrievals: Retrievals`, `query: str`, `translate_needed: bool`, `detected_language: str` * **Outputs:** `response: str`, `attribution_result: AttributionResult`, `groundedness_scores: List[GroundednessScore]` * **UI Stream Types:** `RETRIEVALS`, `GENERATION`, `ATTRIBUTION`, `GROUNDEDNESS` *** ### SalesforceSOSLStep * **Description:** Execute SOSL searches against Salesforce. * **Config Parameters:** `username: Optional[str] = None`, `password: Optional[SecretStr] = None`, `security_token: Optional[SecretStr] = None`, `client_id: Optional[str] = None`, `client_secret: Optional[SecretStr] = None`, `login_url: Optional[str] = None`, `auth_token_secret: Optional[SecretStr] = None`, `objects_to_return: str = "Case(Id, Subject, Status, Priority, Account.Name, Contact.Name)"`, `limit: int = 250`, `timeout: int = 30` * **Inputs:** `query: str` * **Outputs:** `search_results: str` * **UI Stream Types:** None *** ### SearchShardMetadataStep * **Description:** Search document shard metadata using instant search. * **Config Parameters:** `default_size: int = 10` * **Inputs:** `query: str` * **Outputs:** `shard_search_results: List[Dict[str, Any]]` * **UI Stream Types:** None *** ### SearchStep * **Description:** Perform search using the search service. * **Config Parameters:** `datastores: Optional[List[UUID]] = None`, `disable_structured_data_search: bool = False` * **Inputs:** `query: str`, `query_embedding: List[float]`, `merged_embeded_reformulated_queries: List[Tuple[List[float], str]]`, `documents_filters: Optional[...]` * **Outputs:** `retrievals: Retrievals` * **UI Stream Types:** None *** ### SearchStructuredDataStep * **Description:** Search structured data. * **Config Parameters:** `datastores: Optional[List[UUID]] = None` * **Inputs:** `query: str` * **Outputs:** `retrievals: Retrievals` * **UI Stream Types:** None *** ### SearchUnstructuredDataStep * **Description:** Search unstructured data and return retrievals. * **Config Parameters:** None * **Inputs:** `query: str` * **Outputs:** `retrievals: Retrievals` * **UI Stream Types:** `QUERY_REFORMULATION` *** ### SetMemberStep * **Description:** Update values of dictionaries or pydantic objects. * **Config Parameters:** `overwrite: bool = False` * **Inputs:** `input: Union[dict, BaseModel]`, `key: str`, `value: Any` * **Outputs:** `output: Union[dict, BaseModel]` * **UI Stream Types:** None *** ### ShardImageExtractionStep * **Description:** Extract page images from PDF shard search results. * **Config Parameters:** `default_dpi: int = 144` * **Inputs:** `shard_search_results: List[Dict[str, Any]]` * **Outputs:** `extracted_images: List[str]` * **UI Stream Types:** None *** ### SliceStep * **Description:** Slice a list from `start_index` to `end_index`. * **Config:** None * **Inputs:** `list: List[Any]`, `start_index: int`, `end_index: int` * **Outputs:** `output: List[Any]` * **UI Stream Types:** None *** ### TranslateQueryStep * **Description:** Translate the query. * **Config Parameters:** `translate_confidence: Optional[float] = None`, `template_translation_forward: Optional[str] = None`, `template_translation_reverse: Optional[str] = None`, `translate_model: Optional[str] = None`, `translate_needed: Optional[bool] = None` * **Inputs:** `query: str` * **Outputs:** `reformulated_query: str`, `translate_needed: bool`, `detected_language: str` * **UI Stream Types:** None *** ### TranslateResponseStep * **Description:** Translate the response. * **Config Parameters:** `template_translation_forward: Optional[str] = None`, `template_translation_reverse: Optional[str] = None`, `translate_model: Optional[str] = None` * **Inputs:** `generation_result: GenerationResult`, `translate_needed: bool`, `detected_language: str` * **Outputs:** `generation_result: GenerationResult` * **UI Stream Types:** `GENERATION` *** ### VisionLanguageModelStep * **Description:** Vision language model inference with multimodal inputs. * **Config Parameters:** `model_id: str = "vertex_ai/gemini-2.0-flash"`, `temperature: float = 0.0`, `max_tokens: int = 4096`, `structured_output: Optional[Dict[str, Any]] = None` * **Inputs:** `query: str`, `images: List[str]` * **Outputs:** `generation_result: GenerationResult` * **UI Stream Types:** `GENERATION` *** ### WebSearchStep * **Description:** Perform web search. * **Config Parameters:** `model: str = "gemini-2.5-flash"` * **Inputs:** `query: str` * **Outputs:** `web_result: WebResult` * **UI Stream Types:** None *** ### WebhookStep * **Description:** Execute a webhook call with static and dynamic configuration. * \*\*Config Parameters: `webhook_url: str`, `method: HttpMethod = HttpMethod.POST`, `auth_token: Optional[SecretStr] = None`, `timeout: int = 30`, `retries: int = 2`, `static_headers: Optional[Dict[str, str]] = None`, `webhook_name: str = "webhook-step"` * **Inputs:** `context_data: Dict[str, Any]` * **Outputs:** `webhook_result: Optional[Dict[str, Any]]` * **UI Stream Types:** None *** ### WrapStep * **Description:** Transform data by wrapping inputs in dictionaries. * **Config Parameters:** `key: str = required` * **Inputs:** `input: Any` * **Outputs:** `output: Dict[str, Any]` * **UI Stream Types:** None ## Additional Resources * [Agent Composer Quickstart Guide](/quickstarts/agent-composer) * [Agent Composer GUI How-to Guide](/how-to-guides/agent-composer-gui) * [Supply Chain Operator Demo](/examples/supply-chain-operator) # Agent Composer GUI Source: https://docs.contextual.ai/how-to-guides/agent-composer-gui Using the Agent Composer GUI to visually build workflows Agent Composer is currently available in private preview for enterprise users. For more information or to request access, please contact your Contextual AI representative. ## Overview The Agent Composer GUI provides a visual way to build agent workflows in Contextual AI, replacing manual YAML with an intuitive, drag-and-drop canvas. | Component | Description | Function | | ------------------ | ----------------------------------------- | --------------------------- | | Agent Composer GUI | Visual builder for agent workflows | Replaces hand-written YAML | | Canvas | Area where nodes are placed and connected | Supports drag, drop, select | | Node Drawer | Right-side panel for adding nodes | Drag onto canvas | Together, these components ensure workflows are type-safe, executable, and quick to move from concept to a working agent. The Agent Composer GUI is part of Contextual AI's enterprise offering. For access, please contact your Contextual AI representative. *** ## Building an Agent Workflow To create an agent workflow, open the Workflow Builder and add nodes from the drawer to define each step of the process. As the workflow grows, group related nodes into subgraphs to keep the graph organized and reusable, then connect nodes with type-safe connections to define how data flows between components. When the workflow is complete, save your progress, optionally export the graph as YAML, and create or update an agent. This allows you to iterate and refine the workflow over time. *** ## Nodes Agent Composer workflows are built from a set of node types, each designed to serve a specific role within an agent’s execution graph. Some nodes perform straightforward processing, while others introduce configuration, branching logic, or dynamic behavior at runtime. ### Adding Nodes Nodes can be added from the right-side drawer by dragging and dropping them onto the canvas. ### Removing Nodes Remove a node by clicking to select it, then either press `BACKSPACE` or click the trash bin icon in the node's toolbar.