### Install OpenAI Node.js Client

Source: https://docs.ragie.ai/docs/step-4-generate

Installs the official OpenAI Node.js client library using npm. This package is required to interact with the OpenAI API.

```shell
npm install openai
```

--------------------------------

### Install langchain-ragie package

Source: https://docs.ragie.ai/docs/langchain-ragie

Instructions for installing the langchain-ragie library into a Python environment. Users can choose between pip or poetry based on their project's dependency management system.

```pip
pip install langchain-ragie
```

```poetry
poetry add langchain-ragie
```

--------------------------------

### Install Ragie TypeScript Client

Source: https://docs.ragie.ai/docs/step-2-upload-documents

Installs the necessary Ragie TypeScript client package using npm. This is a prerequisite for using the Ragie TypeScript SDK in your project.

```shell
npm install ragie
```

--------------------------------

### Metadata Filtering Examples (JSON)

Source: https://docs.ragie.ai/docs/metadata-filters

Demonstrates how to use the metadata query language to filter documents. Examples cover using arrays as metadata values, applying various operators, and combining filters with AND and OR logic.

```json
{
  "genre": ["comedy", "documentary"]
}
```

```json
{
  "genre": "comedy"
}
```

```json
{
  "genre": {"$in": ["documentary", "action"]}
}
```

```json
{
  "$and": [{ "genre": "comedy" }, { "genre": "documentary" }]
}
```

```json
{
  "genre": {"$in": ["comedy", "documentary", "drama"]}
}
```

```json
{
  "genre": {"$eq": "drama"},
  "year": {"$gte": 2020}
}
```

```json
{
  "$and": [{ "genre": {"$eq": "drama"} }, { "year": {"$gte": 2020} }]
}
```

```json
{
  "$or": [{ "genre": {"$eq": "drama"} }, { "year": {"$gte": 2020} }]
}
```

--------------------------------

### Install Ragie SDK via Package Manager

Source: https://docs.ragie.ai/docs/ragie-typescript

Commands to install the ragie npm package using common JavaScript package managers. Choose the command corresponding to your project's preferred dependency manager.

```npm
npm i ragie
```

```yarn
yarn add ragie
```

```pnpm
pnpm add ragie
```

--------------------------------

### API Response Structures

Source: https://docs.ragie.ai/docs/changes-to-the-api

JSON examples representing the responses from the Create Document and Get Document Chunks endpoints. These structures include status information, temporal metadata for media, and links for streaming or downloading content.

```json
{
  "status": "partitioning",
  "id": "id123",
  "created_at": "2025-05-15T19:58:03.483172Z",
  "updated_at": "2025-05-15T19:58:03.586856Z",
  "name": "presentation.mp4",
  "metadata": {},
  "partition": "default",
  "chunk_count": null,
  "external_id": "",
  "page_count": null
}
```

```json
{
  "pagination": {
    "next_cursor": null,
    "total_count": 10
  },
  "chunks": [
    {
      "id": "id123",
      "index": 0,
      "text": "The text of the chunk.",
      "metadata": {
        "end_time": 57.68,
        "start_time": 2.44
      },
      "links": {
        "self": {
          "href": "https://api.ragie.ai/documents/docId/chunks/chunkId",
          "type": "application/json"
        },
        "self_audio_stream": {
          "href": "https://api.ragie.ai/documents/docId/chunks/chunkId/content?media_type=audio/mpeg",
          "type": "audio/mpeg"
        }
      }
    }
  ]
}
```

--------------------------------

### DefinitionList Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents a definition-style list. The 'content' field contains markdown-formatted definition list text.

```json
{
  "type": "DefinitionList",
  "content": "Parse\n: Extract structured document elements\n\nIndex\n: Create retrievable chunks and embeddings"
}
```

--------------------------------

### EmailAddress Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents an email address. The 'content' field stores the email address string.

```json
{
  "type": "EmailAddress",
  "content": "support@example.com"
}
```

--------------------------------

### Bibliography Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents bibliography or references content. The 'content' field holds markdown-formatted bibliography text.

```json
{
  "type": "Bibliography",
  "content": "1. Smith, J. *Security Systems*. 2025.\n2. Doe, A. *Infrastructure at Scale*. 2024."
}
```

--------------------------------

### Author Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents an author or byline. The 'content' field stores the author's name.

```json
{
  "type": "Author",
  "content": "Jane Smith"
}
```

--------------------------------

### Button Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents a button-like user interface element. The 'content' field stores the button's label.

```json
{
  "type": "Button",
  "content": "Submit"
}
```

--------------------------------

### Caption Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents a caption for an image or figure. The 'content' field holds the caption text.

```json
{
  "type": "Caption",
  "content": "Figure 2. Quarterly revenue by region."
}
```

--------------------------------

### Get Partition Usage Information

Source: https://docs.ragie.ai/docs/partitions

Fetches usage information for a specific partition, including monthly and total pages processed/hosted, document count, and limit exceeded status.

```APIDOC
## GET /partitions/{partition_id}

### Description
Retrieves usage statistics for a given partition. This includes `pages_processed_monthly`, `pages_hosted_monthly`, `pages_processed_total`, `pages_hosted_total`, and `document_count`. It also indicates if a limit has been exceeded via `limit_exceeded_at`.

### Method
GET

### Endpoint
`/partitions/{partition_id}`

### Parameters
#### Path Parameters
- **partition_id** (string) - Required - The unique identifier of the partition.

### Response
#### Success Response (200)
- **pages_processed_monthly** (integer) - The number of pages processed in the current month.
- **pages_hosted_monthly** (integer) - The number of pages hosted in the current month.
- **pages_processed_total** (integer) - The total number of pages processed.
- **pages_hosted_total** (integer) - The total number of pages hosted.
- **document_count** (integer) - The total number of documents in the partition.
- **limit_exceeded_at** (string) - An ISO 8601 Date Time string indicating when a limit was exceeded, or null if no limit is exceeded.

#### Response Example
```json
{
  "pages_processed_monthly": 1500,
  "pages_hosted_monthly": 1200,
  "pages_processed_total": 15000,
  "pages_hosted_total": 12000,
  "document_count": 500,
  "limit_exceeded_at": null
}
```
```

--------------------------------

### Comment Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents a comment or annotation text. The 'content' field stores the comment's text.

```json
{
  "type": "Comment",
  "content": "Reviewer note: verify the totals against the signed copy."
}
```

--------------------------------

### GET /connections

Source: https://docs.ragie.ai/docs/managing-connections

Retrieve a list of all existing connections associated with the account.

```APIDOC
## GET /connections

### Description
Returns a list of all connections currently configured.

### Method
GET

### Endpoint
https://api.ragie.ai/connections

### Response
#### Success Response (200)
- **connections** (array) - List of connection objects

#### Response Example
{
  "connections": []
}
```

--------------------------------

### Code Snippet Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents a code snippet or block. The 'content' field contains the code itself, and 'language' specifies the programming language.

```json
{
  "type": "Code",
  "content": "def hello():\n    return \"world\"",
  "language": "python"
}
```

--------------------------------

### Barcode Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents a barcode and nearby associated text. The 'content' field contains the text associated with the barcode.

```json
{
  "type": "Barcode",
  "content": "Tracking ID: 1Z999AA10123456784"
}
```

--------------------------------

### Create Google Drive Authenticator with cURL

Source: https://docs.ragie.ai/docs/whitelabel-connectors

This snippet demonstrates how to create an authenticator for Google Drive using cURL. It requires your project's client_id and client_secret. The response will include an ID for the created authenticator, which is essential for subsequent connection setups. All data is encrypted.

```bash
curl --location 'https://ragie.ai/authenticators' \
--header 'Authorization: Bearer your_token' \
--header 'Content-Type: application/json' \
--data '{
  "provider": "google",
  "name": "My Google Authenticator",
  "client_id": "id",
  "client_secret": "secret"
}'
```

--------------------------------

### Initiate OAuth Connection for File Selection

Source: https://docs.ragie.ai/docs/white-label-with-embed-flow

This cURL command initiates the OAuth connection process for selecting files via Google Drive within the Ragie embed flow. It requires your Ragie API key, a redirect URI, and the authenticator ID obtained from the previous step. The command specifies the provider, source type, and desired mode for the connection, returning a URL to start the authentication process.

```curl
curl --location 'https://api.ragie.ai/connections/oauth' \
--header 'Authorization: Bearer <your_key>' \
--header 'Content-Type: application/json' \
--data '{
  "redirect_uri": "<Your redirect url>",
  "partition": "google_files",
  "source_type": "google_drive",
  "metadata": {},
  "mode": "hi_res",
  "theme": "system",
  "page_limit": 100,
  "authenticator_id": "b5e77fb7-026c-408f-837a-2bf3b4ba0c6b"
}'
```

--------------------------------

### Get Document Chunk Response Structure

Source: https://docs.ragie.ai/docs/changes-to-the-api

Example JSON response structure for retrieving a document chunk, including metadata, links, and modality-specific data like word-level timestamps.

```json
{
  "id": "id123",
  "index": 0,
  "text": "The text of the chunk.",
  "metadata": {
    "end_time": 57.68,
    "start_time": 2.44
  },
  "modality_data": {
    "type": "audio",
    "word_timestamps": [
      {
        "start_time": 2.44,
        "end_time": 3.06,
        "word": " President",
        "probability": 0.75537109375
      }
    ]
  }
}
```

--------------------------------

### Set up Project Directory

Source: https://docs.ragie.ai/docs/step-4-generate

Creates a new directory for the project and navigates into it. This is the initial step for organizing the application files.

```shell
mkdir generate-example
cd generate-example
```

--------------------------------

### Partition Management API

Source: https://docs.ragie.ai/docs/partitions

This section details how to manage partitions, including explicit creation and how partitions are handled across different API endpoints.

```APIDOC
## Working with Partitions

### Creating Partitions

A Partition is automatically created anytime a document, connection or instruction is created in it.

### Documents and Partitions

Documents can be created in a partition by providing an optional `partition` string when creating them. If a partition is omitted the document will be created in the "default" partition.

### Retrievals

The optional `partition` parameter can be provided when doing retrievals. When present the retrieval will be scoped to that Partition. Fine grained scoping via metadata filters may be combined with partition scoping.

### Connections and Partitions

Connections can be created in a partition by providing an optional `partition` string when creating them. If a partition is omitted, documents managed by the partition will be in the "default" partition.

### Entity Extraction Instructions and Partitions

Instructions can be created in a partition by providing an optional `partition` string when creating them. If a partition is provided, the instruction will attempt to extract entities from documents in all partitions. If a partition is provided, the instruction will only execute on documents in that partition.

### Partitions Handling for Other Endpoints

Many other endpoints support scoping the request to a partition using the `partition` http header or a parameter with that same name in the Ragie SDKs. If partition is omitted the requests will be scoped to the "default" partition. One caveat to this behavior is accounts created prior to 1/9/2025, which will have the requests scoped to all partitions. Those accounts may opt in to stricter partition enforcement by contacting [support@ragie.ai.](mailto:support@ragie.ai.) If you're using partitions, it's strongly encouraged to explicitly set `partition` on requests that support it.

#### Endpoints that support partition scoping

* [Get Document](https://docs.ragie.ai/reference/getdocument)
* [Delete Document](https://docs.ragie.ai/reference/deletedocument)
* [Update Document File](https://docs.ragie.ai/reference/updatedocumentfile)
* [Update Document Raw](https://docs.ragie.ai/reference/updatedocumentraw)
* [Patch Document Metadata](https://docs.ragie.ai/reference/patchdocumentmetadata)
* [Get Document Chunks](https://docs.ragie.ai/reference/getdocumentchunks)
* [Get Document Chunk](https://docs.ragie.ai/reference/getdocumentchunk)
* [Get Document Summary](https://docs.ragie.ai/reference/getdocumentsummary)
* [Get Instruction Extracted Entities](https://docs.ragie.ai/reference/getdocumentsummary)
* [Get Document Extracted Entities](https://docs.ragie.ai/reference/listentitiesbydocument)

## Managing Partitions

### Explicitly Creating Partitions

While partitions can be created implicitly through various operations like creating a document, they can also be explicitly created using [Create Partition](https://docs.ragie.ai/reference/create_partition_partitions_post). This can be useful if creating a partition with limits defined is required before documents are created in it.
```

--------------------------------

### Initialize OAuth Connection with Optional Parameters

Source: https://docs.ragie.ai/docs/initiating-a-connection

Demonstrates how to include optional parameters such as metadata, mode, and partition when initializing an OAuth connection. These parameters assist in filtering data during retrieval.

```curl
curl https://api.ragie.ai/connections/oauth \
  -H "Authorization: Bearer $RAGIE_API_KEY" \
  --json '{"source_type": "google_drive", "redirect_uri": "https://example.com/link/to/your/application", "metadata": {"user_id": "my-application-user-id"}, "mode": "hi_res", "partition": "my-application-tenant-id" }'
```

--------------------------------

### Create package.json for Project

Source: https://docs.ragie.ai/docs/step-4-generate

Initializes a package.json file for a Node.js project. This file manages project metadata and dependencies.

```json
{
  "name": "generate-example",
  "version": "1.0.0",
  "main": "index.mjs",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": ""
}
```

--------------------------------

### GET /documents/{document_id}

Source: https://docs.ragie.ai/docs/rate-limits

Retrieve details for a specific document by its ID.

```APIDOC
## GET /documents/{document_id}

### Description
Retrieves a document by its unique ID. Rate limits are 1000/m for Developer, 2000/m for Starter, and 4000/m for Pro plans.

### Method
GET

### Endpoint
/documents/{document_id}

### Parameters
#### Path Parameters
- **document_id** (string) - Required - The unique identifier of the document.

### Response
#### Success Response (200)
- **id** (string) - Document ID
- **metadata** (object) - Document metadata

#### Response Example
{
  "id": "doc_12345",
  "metadata": {}
}
```

--------------------------------

### POST /documents

Source: https://docs.ragie.ai/docs/rate-limits

Create a new document in the Ragie system.

```APIDOC
## POST /documents

### Description
Creates a new document. Rate limits are 30/m for Developer, 50/m for Starter, and 100/m for Pro plans.

### Method
POST

### Endpoint
/documents

### Request Body
- **document_data** (object) - Required - The document content and metadata.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created document.

#### Response Example
{
  "id": "doc_12345"
}
```

--------------------------------

### GET /documents/{id}/summary

Source: https://docs.ragie.ai/docs/summary-index

Retrieves the automatically generated summary for a specific document.

```APIDOC
## GET /documents/{id}/summary

### Description
Fetches the high-level summary generated for a document. Summarization is automatic for compatible document types.

### Method
GET

### Endpoint
/documents/{id}/summary

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document.

### Response
#### Success Response (200)
- **summary** (string) - The generated summary text of the document.

#### Response Example
{
  "summary": "This document outlines the quarterly sales strategy and key feature requests from enterprise clients."
}
```

--------------------------------

### Create an Extraction Instruction Configuration

Source: https://docs.ragie.ai/docs/entity-extraction

Defines the structure for an extraction instruction, including the prompt, scope, entity schema, and metadata filters. This configuration is used with the Ragie create instruction API to automate data extraction from documents.

```json
{
  "name": "emails",
  "active": true,
  "scope": "chunk",
  "prompt": "extract all emails from the document",
  "entity_schema": {"type": "object","properties": {"emails": {"type": "array","items": {"type": "string"}}}},
  "filter": { "type": "customer_doc" }
}
```

--------------------------------

### GET /connections/{connection_id}/stats

Source: https://docs.ragie.ai/docs/managing-connections

Retrieve statistics for a specific connection, such as the total document count.

```APIDOC
## GET /connections/{connection_id}/stats

### Description
Returns the total number of documents associated with the specified connection.

### Method
GET

### Endpoint
https://api.ragie.ai/connections/{connection_id}/stats

### Parameters
#### Path Parameters
- **connection_id** (string) - Required - The unique identifier of the connection

### Response
#### Success Response (200)
- **document_count** (integer) - Total number of documents
```

--------------------------------

### Create Google Drive Connection with cURL

Source: https://docs.ragie.ai/docs/whitelabel-connectors

This cURL request shows how to establish a connection to Google Drive after an authenticator has been set up. It requires the authenticator ID and specifies data synchronization details, including partition strategy, data to sync (with IDs and MIME types), and credentials like a refresh token. The connection will begin syncing data automatically after creation.

```bash
curl --location 'https://ragie.ai/authenticators/963cad11-50d2-477b-94d7-d039beecf3db/connection' \
--header 'Authorization: Bearer your_token' \
--header 'Content-Type: application/json' \
--data '{
    "partition_strategy": {
        "static": "hi_res",
        "audio": true,
        "video": "audio_only"
    },
    "partition": "string",
    "page_limit": 1000,
    "metadata": {},
    "connection": {
        "provider": "google_drive",
        "data": [
            {
                "id": "id", 
                "name": "name",
                "mime_type": "application/vnd.google-apps.folder"
            }
        ],
        "email": "test",
        "credentials": {
            "refresh_token": "string"
        }
    }
}'
```

--------------------------------

### Upload Video File to Ragie

Source: https://docs.ragie.ai/docs/example

Demonstrates how to initialize the Ragie client and upload a video file for ingestion. The process requires a File object and specifies the video mode for processing.

```typescript
const ragie = new Ragie({
  auth: process.env.RAGIE_API_KEY,
});

const file = new File([blob], "presentation.mp4");

const result = await ragie.documents.create({
  file: file,
  mode: { video: "audio_video",}
});
```

--------------------------------

### PUT /connections/{connection_id}/enabled

Source: https://docs.ragie.ai/docs/managing-connections

Update the enabled status of a specific connection to start or stop synchronization.

```APIDOC
## PUT /connections/{connection_id}/enabled

### Description
Enable or disable a connection. Disabled connections will stop syncing data.

### Method
PUT

### Endpoint
https://api.ragie.ai/connections/{connection_id}/enabled

### Parameters
#### Path Parameters
- **connection_id** (string) - Required - The unique identifier of the connection

#### Request Body
- **enabled** (boolean) - Required - Set to true to enable or false to disable

### Request Example
{
  "enabled": false
}
```

--------------------------------

### Run the RAG Application

Source: https://docs.ragie.ai/docs/step-4-generate

Executes the Node.js script to run the RAG application. This command initiates the data retrieval and content generation process.

```shell
node index.mjs
```

--------------------------------

### Partition Patterns for Webhooks

Source: https://docs.ragie.ai/docs/webhooks

Explanation of how to use `partition_pattern` to filter webhook events based on document partitions.

```APIDOC
## Partition Patterns for Webhooks

### Description
Partitions are an optional feature that logically separates documents within Ragie. Webhook endpoints may configure an optional `partition_pattern`. If present, document-related webhook events will only be sent to the endpoint if the document's partition matches the `partition_pattern`. `partition_pattern`s are defined as globs.

### Method
N/A (Configuration Information)

### Endpoint
N/A (Configuration Information)

### Parameters
#### Request Body (Configuration)
- **partition_pattern** (string, optional) - A glob pattern to match document partitions.

### Request Example
N/A

### Response
N/A
```

--------------------------------

### CalendarDate Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents a date string extracted from the document. The 'content' field stores the date as it appears in the text.

```json
{
  "type": "CalendarDate",
  "content": "March 1, 2026"
}
```

--------------------------------

### Create Document with Audio, Video, and Static Modes

Source: https://docs.ragie.ai/docs/changes-to-the-api

Demonstrates how to upload files to the Ragie AI API using different processing modes. The 'mode' parameter allows for specific configurations for audio, video, and static document processing, including support for combined multi-modal inputs.

```typescript
const file = new File([blob], "presentation.mp3");

const result = await ragie.documents.create({
  file: file,
  mode: {
        audio: true,
  },
  metadata: {
    category: "business",
  },
});
```

```typescript
const file = new File([blob], "presentation.mp4");

const result = await ragie.documents.create({
  file: file,
  mode: {
        video: "audio_video",
  },
  metadata: {
    category: "business",
  },
});
```

```typescript
const file = new File([blob], "presentation.pdf");

const result = await ragie.documents.create({
  file: file,
  mode: "hi_res",
  metadata: {
    category: "business",
  },
});
```

```typescript
const file = new File([blob], "presentation.mp4");

const result = await ragie.documents.create({
  file: file,
  mode: {
    static: "hi_res",
    audio: true,
    video: "audio_video",
  },
  metadata: {
    category: "business",
  },
});
```

--------------------------------

### Query Document Status with Ragie SDK

Source: https://docs.ragie.ai/docs/step-2-upload-documents

Demonstrates how to retrieve the processing status of a document using the Ragie TypeScript SDK. It shows how to initialize the SDK, specify a document ID, and fetch the document object, which includes a 'status' field indicating if it's 'ready'.

```typescript
import { Ragie } from "ragie";

const apiKey = "<YOUR API KEY>";
const id = "21881de1-65f7-4816-b571-3ef69661c375";

const ragie = new Ragie({
  auth: apiKey
});

// Retrieve document status
(async () => {
  const document = await ragie.documents.get({
    documentId: id
  });

  console.log(document);
})();
```

--------------------------------

### Delete Tutorial Documents with Ragie API (JavaScript)

Source: https://docs.ragie.ai/docs/step-5-cleanup

This script iterates through and deletes all documents tagged with the 'tutorial' scope in your Ragie instance. It utilizes the `ragie.documents.list` API with a filter and `nextCursor` for pagination, and `ragie.documents.delete` to remove each document. Ensure you replace '<YOUR API KEY>' with your actual Ragie API key.

```javascript
import { Ragie } from "ragie";

const apiKey = "<YOUR API KEY>";

const ragie = new Ragie({
  auth: apiKey
});

(async () => {
  while (true) {
    try {
      const response = await ragie.documents.list({
        filter: `{"scope": "tutorial"}`
      });

      const documents = response.result.documents;

      for (const document of documents) {
        try {
          await ragie.documents.delete({
            documentId: document.id
          });
          console.log(`Deleted document ${document.id}`);
        } catch (error) {
          console.error(`Failed to delete document ${document.id}:`, error);
          throw error;
        }
      }

      if (!response.result.pagination.nextCursor) {
        console.warn("No more documents\n");
        break;
      }
    } catch (error) {
      console.error("Failed to retrieve or process documents:", error);
      throw error;
    }
  }
})();
```

--------------------------------

### Define Address Element JSON

Source: https://docs.ragie.ai/docs/elements-api

An example of the JSON structure for an Address element, which includes the type identifier and the raw address string content.

```json
{
  "type": "Address",
  "content": "123 Main Street\nSpokane Valley, WA 99206"
}
```

--------------------------------

### Multipart File Uploader API

Source: https://docs.ragie.ai/docs/step-2-upload-documents

This API allows you to upload files directly to Ragie. The example demonstrates reading files from a directory and uploading them one by one.

```APIDOC
## POST /documents

### Description
Uploads a file to Ragie for processing.

### Method
POST

### Endpoint
/documents

### Parameters
#### Request Body
- **file** (Blob) - Required - The file content to upload.
- **name** (string) - Required - The name of the file.
- **metadata** (object) - Optional - Metadata to associate with the document.
  - **title** (string) - Optional - The title of the document.
  - **scope** (string) - Optional - The scope of the document.

### Request Example
```json
{
  "file": "<Blob object of the file content>",
  "name": "podcast.mp3",
  "metadata": {
    "title": "Podcast Episode 1",
    "scope": "tutorial"
  }
}
```

### Response
#### Success Response (200)
- **documentId** (string) - The unique identifier for the uploaded document.
- **status** (string) - The processing status of the document.

#### Response Example
```json
{
  "documentId": "doc_abc123",
  "status": "processing"
}
```
```

--------------------------------

### Create a Connection

Source: https://docs.ragie.ai/docs/whitelabel-connectors

Creates a new data connection using a previously created authenticator. This connection will begin syncing data based on the provided configuration.

```APIDOC
## POST /authenticators/{authenticator_id}/connection

### Description
Creates a new data connection using a specified authenticator. This connection will begin syncing data based on the provided configuration.

### Method
POST

### Endpoint
https://ragie.ai/authenticators/{authenticator_id}/connection

### Parameters
#### Path Parameters
- **authenticator_id** (string) - Required - The ID of the authenticator to use for this connection.

#### Request Body
- **partition_strategy** (object) - Optional - Defines how data should be partitioned.
  - **static** (string) - Optional - A static partition key.
  - **audio** (boolean) - Optional - Whether to include audio data.
  - **video** (string) - Optional - Strategy for video data (e.g., "audio_only").
- **partition** (string) - Optional - A specific partition to sync.
- **page_limit** (integer) - Optional - The maximum number of items to fetch per page.
- **metadata** (object) - Optional - Custom metadata to associate with the connection.
- **connection** (object) - Required - Configuration for the data connection.
  - **provider** (string) - Required - The provider of the data source (e.g., "google_drive").
  - **data** (array) - Required - A list of data items to sync.
    - **id** (string) - Required - The ID of the data item.
    - **name** (string) - Required - The name of the data item.
    - **mime_type** (string) - Optional - The MIME type of the data item.
  - **email** (string) - Optional - An email address associated with the connection.
  - **credentials** (object) - Optional - Credentials specific to the connection.
    - **refresh_token** (string) - Required if not using an authenticator for token refresh - The refresh token for the service.

### Request Example
```json
{
    "partition_strategy": {
        "static": "hi_res",
        "audio": true,
        "video": "audio_only"
    },
    "partition": "string",
    "page_limit": 1000,
    "metadata": {},
    "connection": {
        "provider": "google_drive",
        "data": [
            {
                "id": "id", 
                "name": "name",
                "mime_type": "application/vnd.google-apps.folder"
            }
        ],
        "email": "test",
        "credentials": {
            "refresh_token": "string"
        }
    }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the connection was created.

#### Response Example
```json
{
  "message": "Connection created successfully."
}
```
```

--------------------------------

### Define Metadata for Dropbox Connection

Source: https://docs.ragie.ai/docs/dropbox-connection

Example of the JSON format used to associate custom metadata with a Dropbox connection. This metadata allows for filtering data during downstream operations.

```json
{
  "company": "acme"
}
```

--------------------------------

### Get Document Chunk Content

Source: https://docs.ragie.ai/docs/changes-to-the-api

Retrieves the content of a document chunk in a specific format. Supports streaming media by specifying the mediaType parameter.

```typescript
const response = await client.documents.getChunkContent({
      documentId: "docId",
      chunkId: "chunkId",
      mediaType: "audio/mpeg",
});
```

--------------------------------

### Filter Document Elements for Tables using Ragie AI API

Source: https://docs.ragie.ai/docs/getting-started-with-parse-elements-api

This example demonstrates how to filter document elements to retrieve only 'Table' types. The output includes the markdown representation of the table, along with other element details.

```markdown
| Layer Type                  | Complexity per Layer | Sequential Operations | Maximum Path Length |
| --------------------------- | -------------------- | --------------------- | ------------------- |
| Self-Attention              | O(n*-d)             | o(1)                  | o(1)                |
| Recurrent                   | O(n-d?)              | O(n)                  | O(n)                |
| Convolutional               | O(k-n-d?)            | ()(1)                 | O(logk(n))          |
| Self-Attention (restricted) | O(r-n-d)             | 0(1)                  | O(n/r)              |
```

--------------------------------

### AudioTranscriptionSegment Example (JSON)

Source: https://docs.ragie.ai/docs/elements-api

Represents a segment of transcribed audio with per-word timing and probability data. The 'content' field holds the transcribed text, and 'modality_data' provides details for each word.

```json
{
  "type": "AudioTranscriptionSegment",
  "content": "Welcome to the quarterly review.",
  "modality_data": [
    { "word": "Welcome", "probability": 0.99, "start": 0.0, "end": 0.42 },
    { "word": "to", "probability": 0.98, "start": 0.43, "end": 0.50 },
    { "word": "the", "probability": 0.99, "start": 0.51, "end": 0.58 },
    { "word": "quarterly", "probability": 0.97, "start": 0.59, "end": 1.10 },
    { "word": "review.", "probability": 0.98, "start": 1.11, "end": 1.55 }
  ]
}
```

--------------------------------

### POST /retrievals

Source: https://docs.ragie.ai/docs/example

Retrieves relevant chunks from ingested documents based on a natural language query.

```APIDOC
## POST /retrievals

### Description
Performs a semantic search across ingested documents to find relevant information based on the provided query.

### Method
POST

### Endpoint
/retrievals

### Request Body
- **query** (string) - Required - The search query string.

### Request Example
```typescript
const response = await ragie.retrievals.retrieve({
  query: "What are the 3 main points of the presentation?",
});
```

### Response
#### Success Response (200)
- **scored_chunks** (Array) - List of relevant text chunks with associated metadata and media links.

#### Response Example
{
  "scored_chunks": [
    {
      "text": "{\"video_description\": \"The 3 main...\"}",
      "score": 0.167,
      "id": "id123",
      "metadata": { "start_time": 0, "end_time": 15 }
    }
  ]
}
```

--------------------------------

### GET /chunks/{id}/links

Source: https://docs.ragie.ai/docs/changes-to-the-api

Retrieves the available media and text links for a specific chunk, including streaming and download URLs for audio and video content.

```APIDOC
## GET /chunks/{id}/links

### Description
Retrieves a set of links for a specific chunk, allowing access to plain text, audio, and video representations of both the individual chunk and the parent document.

### Method
GET

### Endpoint
/chunks/{id}/links

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the chunk.

### Request Example
GET /chunks/chunk_123/links

### Response
#### Success Response (200)
- **self_text** (string) - Plain text of the chunk.
- **self_audio_download** (object) - Link to download chunk audio.
- **self_audio_stream** (object) - Link to stream chunk audio.
- **self_video_download** (object) - Link to download chunk video.
- **self_video_stream** (object) - Link to stream chunk video.
- **document_text** (string) - Plain text of the parent document.
- **document_audio_download** (object) - Link to download document audio.
- **document_audio_stream** (object) - Link to stream document audio.
- **document_video_download** (object) - Link to download document video.
- **document_video_stream** (object) - Link to stream document video.

#### Response Example
{
  "self_audio_stream": {
    "href": "https://api.ragie.ai/v1/chunks/chunk_123/audio/stream"
  },
  "document_video_download": {
    "href": "https://api.ragie.ai/v1/documents/doc_456/video/download"
  }
}
```

--------------------------------

### POST /documents

Source: https://docs.ragie.ai/docs/example

Uploads a video file to Ragie for processing and ingestion.

```APIDOC
## POST /documents

### Description
Ingests a video file into the Ragie system. The file is processed and partitioned for future retrieval.

### Method
POST

### Endpoint
/documents

### Request Body
- **file** (File) - Required - The video file to be uploaded.
- **mode** (Object) - Required - Configuration for processing, set { video: "audio_video" }.

### Request Example
```typescript
const file = new File([blob], "presentation.mp4");
const result = await ragie.documents.create({
  file: file,
  mode: { video: "audio_video" }
});
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the document.
- **status** (string) - Current processing status (e.g., "partitioning").
- **name** (string) - Name of the uploaded file.

#### Response Example
{
  "status": "partitioning",
  "id": "id123",
  "name": "presentation.mp4"
}
```