# Contextual AI Documentation

## Docs

- [Get Metrics](https://docs.contextual.ai/api-reference/agents-query/get-metrics.md): Returns usage and user-provided feedback data. This information can be used for data-driven improvements and optimization.
- [Get Retrieval Info](https://docs.contextual.ai/api-reference/agents-query/get-retrieval-info.md): Return metadata of the contents used to generate the response for a given message.
- [Provide Feedback](https://docs.contextual.ai/api-reference/agents-query/provide-feedback.md): 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.

If providing feedback on a retrieval, include the `message_id` from the `/query` response, and a `content_id` returned in the query's `retrieval_contents` list.

For feedback on generations, include `message_id` and do not include a `content_id`.
- [Query](https://docs.contextual.ai/api-reference/agents-query/query.md): Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions.
- [Create Agent](https://docs.contextual.ai/api-reference/agents/create-agent.md): 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.

If no `datastore_id` is provided in the configuration, this API automatically creates an empty `Datastore` and configures the `Agent` to use the newly created `Datastore`.

> 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](https://docs.contextual.ai/api-reference/agents/delete-agent.md): 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](https://docs.contextual.ai/api-reference/agents/edit-agent.md): Modify a given `Agent` to utilize the provided configuration.

Fields not included in the request body will not be modified.
- [Get Agent Metadata](https://docs.contextual.ai/api-reference/agents/get-agent-metadata.md): Get metadata and configuration of a given `Agent`.
- [List Agents](https://docs.contextual.ai/api-reference/agents/list-agents.md): Retrieve a list of all `Agents`.
- [Reset Agent](https://docs.contextual.ai/api-reference/agents/reset-agent.md): Reset a given `Agent` to default configuration.
- [Delete Document](https://docs.contextual.ai/api-reference/datastores-documents/delete-document.md): Delete a given document from its `Datastore`. This operation is irreversible.
- [Get Document Metadata](https://docs.contextual.ai/api-reference/datastores-documents/get-document-metadata.md): Get details of a given document, including its `name` and ingestion job `status`.
- [Ingest Document](https://docs.contextual.ai/api-reference/datastores-documents/ingest-document.md): 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) or PPT(X) file. The filename must end with one of the following extensions: `.pdf`, `.html`, `.htm`, `.mhtml`, `.doc`, `.docx`, `.ppt`, `.pptx`.
- [List Documents](https://docs.contextual.ai/api-reference/datastores-documents/list-documents.md): 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](https://docs.contextual.ai/api-reference/datastores-documents/update-document-metadata.md): 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](https://docs.contextual.ai/api-reference/datastores/create-datastore.md): 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](https://docs.contextual.ai/api-reference/datastores/delete-datastore.md): 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](https://docs.contextual.ai/api-reference/datastores/edit-datastore-configuration.md)
- [Get Datastore Metadata](https://docs.contextual.ai/api-reference/datastores/get-datastore-metadata.md): 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](https://docs.contextual.ai/api-reference/datastores/list-datastores.md): 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](https://docs.contextual.ai/api-reference/datastores/reset-datastore.md): Reset the give `Datastore`. This operation is irreversible and it deletes all the documents associated with the datastore.
- [Generate](https://docs.contextual.ai/api-reference/generate/generate.md): 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](https://docs.contextual.ai/api-reference/lmunit/lmunit.md): 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](https://docs.contextual.ai/api-reference/parse/parse-file.md): Parse a file into a structured Markdown and/or JSON. Files must be less than 100MB and 400 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](https://docs.contextual.ai/api-reference/parse/parse-list-jobs.md): 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](https://docs.contextual.ai/api-reference/parse/parse-result.md): 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](https://docs.contextual.ai/api-reference/parse/parse-status.md): 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](https://docs.contextual.ai/api-reference/rerank/rerank.md): 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](https://docs.contextual.ai/api-reference/users/get-users.md): Retrieve a list of `users`.
- [Invite Users](https://docs.contextual.ai/api-reference/users/invite-users.md): 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](https://docs.contextual.ai/api-reference/users/remove-user.md): Delete a given `user`.
- [Update User](https://docs.contextual.ai/api-reference/users/update-user.md): Modify a given `User`.

Fields not included in the request body will not be modified.
- [Node.js SDK](https://docs.contextual.ai/sdks/node.md)
- [Python SDK](https://docs.contextual.ai/sdks/python.md)
- [Advanced Query Features](https://docs.contextual.ai/user-guides/advanced-query-guide.md): Learn how to leverage multi-turn and structured outputs
- [Contextual AI Agent Parameters](https://docs.contextual.ai/user-guides/agent-params.md): Learn how to customize the behavior and performance of your agents
- [Beginner's Guide](https://docs.contextual.ai/user-guides/beginner-guide.md): Create a specialized RAG agent less than 5 Minutes
- [Pricing and Billing](https://docs.contextual.ai/user-guides/billing.md): Pricing and billing guide for on-demand, usage-based customers
- [Key Concepts](https://docs.contextual.ai/user-guides/key-concepts.md): Welcome to the home of your new documentation
- [LLMs.txt](https://docs.contextual.ai/user-guides/llms.md): Contextual AI documentation in LLM-friendly format
- [MCP Server](https://docs.contextual.ai/user-guides/mcp-server.md): Integrate Contextual AI with MCP-compatible clients like Cursor IDE and Claude Desktop
- [Snowflake Native Application](https://docs.contextual.ai/user-guides/snowflake.md): This guide explains how to install and use the Contextual AI Snowflake Native App