// Constants for output path and API URL.
const OUTPUT_PATH = "api-reference/openapi.json";
const API_URL = "https://api.app.contextual.ai/v1/openapi.json";

/**
 * Fetches the OpenAPI specification from the API.
 * Preserves the raw JSON to maintain the original key order.
 *
 * @param {string} apiKey - Authentication token for the API.
 * @returns {Promise<{parsed: unknown, raw: string}>} Object containing both parsed and raw JSON.
 */
async function fetchOpenAPISpec(apiKey) {
  console.log(`Fetching OpenAPI specification from ${API_URL}...`);

  try {
    const response = await fetch(API_URL, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    });

    if (!response.ok) {
      const body = await response.text();
      throw new Error(
        `Failed to fetch OpenAPI specification. HTTP status: ${response.status}, Body: ${body}`
      );
    }

    // Get the raw response text to preserve key order.
    const rawText = await response.text();

    // Parse the JSON to verify it's valid.
    const parsed = JSON.parse(rawText);

    return {
      parsed,
      raw: rawText,
    };
  } catch (error) {
    throw new Error(
      `Failed to fetch OpenAPI specification: ${
        error instanceof Error ? error.message : String(error)
      }`
    );
  }
}

/**
 * Saves the OpenAPI specification to a file.
 * IMPORTANT: This implementation preserves the original key order
 * by parsing and stringifying the raw JSON text, preventing
 * unnecessary diffs in version control.
 *
 * @param {Object} specData - The specification data to save.
 * @param {unknown} specData.parsed - The parsed JSON object (used for validation).
 * @param {string} specData.raw - The raw JSON string (used for preserving order).
 * @param {string} path - The file path where the specification should be saved.
 * @returns {Promise<void>}
 */
async function saveOpenAPISpec(specData, path) {
  try {
    // Format JSON with 2-space indent while preserving key order.
    // Using JSON.parse and JSON.stringify in this way maintains the original order.
    const formatted = JSON.stringify(specData.parsed, null, 2);

    // Ensure the directory exists.
    await ensureDirectoryExists(path);

    // Write to file using Bun's file system API.
    await Bun.write(path, formatted);

    console.log(`OpenAPI specification saved to ${path}`);
  } catch (error) {
    throw new Error(
      `Failed to save OpenAPI specification: ${
        error instanceof Error ? error.message : String(error)
      }`
    );
  }
}

/**
 * Cleans the existing OpenAPI specification file by applying consistent formatting.
 * Reads the file, parses it, and rewrites it with proper JSON formatting.
 * This helps normalize formatting and remove any inconsistencies.
 *
 * @param {string} path - The file path of the OpenAPI specification to clean.
 * @returns {Promise<void>}
 */
async function cleanOpenAPISpec(path = OUTPUT_PATH) {
  const fs = require("node:fs/promises");

  try {
    console.log(`Cleaning OpenAPI specification at ${path}...`);

    // Read the existing file.
    const rawContent = await fs.readFile(path, "utf8");

    // Parse the JSON to validate and normalize it.
    const parsed = JSON.parse(rawContent);

    // Format JSON with 2-space indent for consistency.
    const formatted = JSON.stringify(parsed, null, 2);

    // Write the cleaned content back to the file.
    await Bun.write(path, formatted);

    console.log(`OpenAPI specification cleaned successfully at ${path}`);
  } catch (error) {
    throw new Error(
      `Failed to clean OpenAPI specification: ${
        error instanceof Error ? error.message : String(error)
      }`
    );
  }
}

/**
 * Creates all directories in the path if they don't exist.
 * Uses Node.js fs/promises API for maximum compatibility.
 *
 * @param {string} filePath - The path to the file for which directories should be created.
 * @returns {Promise<void>}
 */
async function ensureDirectoryExists(filePath) {
  const { mkdir } = require("node:fs/promises");
  const path = require("node:path");

  const dir = path.dirname(filePath);

  try {
    await mkdir(dir, { recursive: true });
  } catch (error) {
    // Ignore if directory already exists.
    if (error.code !== "EEXIST") {
      throw new Error(
        `Failed to create directory: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }
}

/**
 * Main function that orchestrates the process.
 * Fetches the OpenAPI spec and saves it to the output file.
 *
 * @returns {Promise<void>}
 */
async function main() {
  const apiKey = process.env.CTXL_API_KEY;

  if (!apiKey) {
    console.error("Error: CTXL_API_KEY environment variable is not set.");
    process.exit(1);
  }

  try {
    // Fetch the OpenAPI specification.
    const spec = await fetchOpenAPISpec(apiKey);

    // Save the specification to file.
    await saveOpenAPISpec(spec, OUTPUT_PATH);

    console.log("OpenAPI specification updated successfully.");
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error));
    process.exit(1);
  }
}

// Check command line arguments to determine which function to run.
const args = process.argv.slice(2);

if (args.includes("--clean")) {
  // Run the cleaning function directly.
  cleanOpenAPISpec()
    .then(() => {
      console.log("Cleaning completed successfully.");
    })
    .catch((error) => {
      console.error(error instanceof Error ? error.message : String(error));
      process.exit(1);
    });
} else {
  // Execute the main function (default behavior).
  main();
}


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`.

List Datastores

Configuration for document chunking settings.

Chunking mode to use. Options are: `heading_depth`, `heading_greedy`, `simple_length`. `heading_depth` creates a new chunk whenever a higher-level section heading is encountered (i.e. h2 → h3 → h4 would be one group, then a new h2 would start another group). `heading_greedy` creates a new chunk whenever any section heading is encountered. `simple_length` creates chunks of a fixed length.
        

Chunking Mode

Whether to enable section-based contextualization for chunking

Enable Section Based Contextualization

Target maximum length of text tokens chunks for chunking. Chunk length may exceed this value in some edge cases.

Max Chunk Length Tokens

Target minimum length of chunks in tokens. Must be at least 384 tokens less than `max_chunk_length_tokens`. Chunk length may be shorter than this value in some edge cases.

Min Chunk Length Tokens

ChunkingConfiguration

Defines available chunking strategies.

- `heading_depth`: Creates a new chunk whenever a higher-level section heading is encountered.

- `heading_greedy`: Creates a new chunk whenever any section heading is encountered.

- `simple_length`: Creates chunks of a fixed length.

ChunkingMode

Mode for figure captioning.

- `detailed`: Use the default figure prompt, which generates a detailed caption for each figure.

- `custom`: Use a custom prompt.

- `ignore`: Disable figure captioning.

DatastoreFigureCaptionMode

Datastore output entry with additional fields for public API.

Configuration

Timestamp of when the datastore was created

Created At

Datastore Type

Name

DatastoreOutputEntry

Configuration for data extraction settings from documents at datastore level. Controls settings for document parsing. Includes those from `/parse` API along with some extra ingestion-only ones.

Enable Split Tables

Mode for figure captioning. Options are `detailed`, `custom`, or `ignore`. Set to `ignore` to disable figure captioning. Set to `detailed` to use the default figure prompt, which generates a detailed caption for each figure. Set to `custom` to use a custom prompt.
        

Prompt to use for generating image captions. Must be non-empty if `figure_caption_mode` is `custom`. Otherwise, must be null.

Figure Captioning Prompt

Maximum number of cells for split tables in markdown files. Ignored if `enable_split_tables` is False.

Max Split Table Cells

DatastoreParseConfiguration

Configuration for unstructured datastores.

UnstructuredDatastoreConfigModel

Location

Message

Error Type

ValidationError

BearerAuth

DatastoreOutputList

HTTPValidationError

Contextual AI Documentation

Create a Specialized RAG Agent in Less than 5 Minutes

Beginner's Guide

Learn how to leverage multi-turn and structured outputs

Advanced Query Features

This guide explains how to install and use the Contextual AI Snowflake Native App

Snowflake Native Application

Welcome to the home of your new documentation

Key Concepts

Learn how to customize the behavior and performance of your agents

Agent Configs

Contextual AI Agent Parameters

Python SDK

Node.js SDK

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."

Create Datastore

Reset the give `Datastore`. This operation is irreversible and it deletes all the documents associated with the datastore.

Reset Datastore

Edit Datastore Configuration

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`.

Delete Datastore

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`.

Get Datastore Metadata

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.

List 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) or PPT(X) file. The filename must end with one of the following extensions: `.pdf`, `.html`, `.htm`, `.mhtml`, `.doc`, `.docx`, `.ppt`, `.pptx`.

Ingest Document

Get details of a given document, including its `name` and ingestion job `status`.

Get Document 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.

Update Document Metadata

Delete a given document from its `Datastore`. This operation is irreversible.

Delete Document

List 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.

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."

Create Agent

Modify a given `Agent` to utilize the provided configuration.

Fields not included in the request body will not be modified.

Edit Agent

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.

Delete Agent

Get metadata and configuration of a given `Agent`.

Get Agent Metadata

Reset a given `Agent` to default configuration.

Reset Agent

Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions.

Query

Return metadata of the contents used to generate the response for a given message.

Get Retrieval Info

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`.

Provide Feedback

Returns usage and user-provided feedback data. This information can be used for data-driven improvements and optimization.

Get Metrics

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/)

LMUnit

Get Users

Modify a given `User`.

Fields not included in the request body will not be modified.

Update User

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).

Invite Users

Remove User

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.

Generate

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.

Rerank

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 File

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.

Parse Status

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 Result

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.

/datastores

/datastores/{id}/documents

/agents

/agents/{id}/query

/lmunit

/users

/generate

/rerank

/parse

List Datastores

Authorizations

Query Parameters

Response