Index API & Clients Guide

This guide highlights the core workflow for working with Index programmatically.

Tip

See full API reference here.

App setup

Python Sync Client

Install API client package

pip install llama-cloud

Import and configure client

from llama_cloud.client import LlamaCloud

client = LlamaCloud(token='<llama-cloud-api-key>')

Python Async Client

Install API client package

pip install llama-cloud

Import and configure client

from llama_cloud.client import AsyncLlamaCloud

async_client = AsyncLlamaCloud(token='<llama-cloud-api-key>')

TypeScript Client

Install API client package

npm install llama-cloud-services

Create new index

Upload files

Python Sync Client

with open('test.pdf', 'rb') as f:
  file = client.files.upload_file(upload_file=f)

Python Async Client

with open('test.pdf', 'rb') as f:
  file = await async_client.files.upload_file(upload_file=f)

TypeScript Client

import fs from "fs";
import { uploadFileApiV1FilesPost } from "llama-cloud-services/api";

const fileBlob = new Blob([fs.createReadStream("./test.pdf")]);

const file = await uploadFileApiV1FilesPost({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  query: {
    project_id: "...",
  },
  body: {
    upload_file: fileBlob,
  },
});

console.log(file.data?.id);

Tip

See Files API for full details on file management.

Configure data sources

Python Sync Client

from llama_cloud.types import CloudS3DataSource

ds = {
  'name': 's3',
  'source_type': 'S3',
  'component': CloudS3DataSource(bucket='test-bucket')
}
data_source = client.data_sources.create_data_source(request=ds)

Python Async Client

from llama_cloud.types import CloudS3DataSource

ds = {
'name': 's3',
'source_type': 'S3',
'component': CloudS3DataSource(bucket='test-bucket')
}
data_source = await async_client.data_sources.create_data_source(request=ds)

TypeScript Client

import { createDataSourceApiV1DataSourcesPost } from "llama-cloud-services/api";

const data_source = await createDataSourceApiV1DataSourcesPost({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  query: {
    project_id: "...",
  },
  body: {
    name: "s3",
    source_type: "S3",
    component: {
      bucket: "test-bucket",
    },
  },
});

console.log(data_source.data?.id);

Tip

See Data Sources API for full details on data source management.

See full list of data sources and specifications.

Configure data sinks

Python Sync Client

from llama_cloud.types import CloudPineconeVectorStore

ds = {
'name': 'pinecone',
'sink_type': 'PINECONE',
'component': CloudPineconeVectorStore(api_key='test-key', index_name='test-index')
}
data_sink = client.data_sinks.create_data_sink(request=ds)

Python Async Client

from llama_cloud.types import CloudPineconeVectorStore

ds = {
'name': 'pinecone',
'sink_type': 'PINECONE',
'component': CloudPineconeVectorStore(api_key='test-key', index_name='test-index')
}
data_sink = await async_client.data_sinks.create_data_sink(request=ds)

TypeScript Client

import { createDataSinkApiV1DataSinksPost } from "llama-cloud-services/api";

const data_sink = await createDataSinkApiV1DataSinksPost({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  query: {
    project_id: "...",
  },
  body: {
    name: "pinecone",
    sink_type: "PINECONE",
    component: {
      api_key: "...",
      index_name: "my-index-in-pinecone",
    },
  },
});

console.log(data_sink.data?.id);

Tip

See Data Sinks API for full details on data sink management.

See full list of data sinks and specifications.

Setup transformation and embedding config

Tip

See Parsing & Transformation for full details on transformation guide.

# Embedding config
embedding_config = {
    'type': 'OPENAI_EMBEDDING',
    'component': {
        'api_key': '<YOUR_API_KEY_HERE>', # editable
        'model_name': 'text-embedding-ada-002' # editable
    }
}

# Transformation auto config
transform_config = {
    'mode': 'auto',
    'config': {
        'chunk_size': 1024, # editable
        'chunk_overlap': 20 # editable
    }
}

Create index (i.e. pipeline)

Python Sync Client

pipeline = {
    'name': 'test-pipeline',
    'embedding_config': embedding_config,
    'transform_config': transform_config,
    'data_sink_id': data_sink.id
}

pipeline = client.pipelines.upsert_pipeline(request=pipeline)

Python Async Client

pipeline = {
    'name': 'test-pipeline',
    'embedding_config': embedding_config,
    'transform_config': transform_config,
    'data_sink_id': data_sink.id
}

pipeline = await async_client.pipelines.upsert_pipeline(request=pipeline)

TypeScript Client

import { upsertPipelineApiV1PipelinesPut } from "llama-cloud-services/api";

const pipeline = await upsertPipelineApiV1PipelinesPut({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  query: {
    project_id: "...",
  },
  body: {
    name: "pipeline",
    embedding_config: { ...},
    transform_config: { ...},
    data_sink_id: data_sink.data?.id,
  },
});

console.log(pipeline.data?.id);

Tip

See Pipeline API for full details on index (i.e. pipeline) management.

Add files to index

Python Sync Client

files = [
  {
    'file_id': file.id,
    'custom_metadata': {
      'document_type': 'INVOICE' # Optioal, an example on how to add custom metadata to your files
    }
  }
]

pipeline_files = client.pipelines.add_files_to_pipeline(pipeline.id, request=files)

Python Async Client

files = [
  {
    'file_id': file.id,
    'custom_metadata': {
      'document_type': 'INVOICE' # Optioal, an example on how to add custom metadata to your files
    }
  }
]

pipeline_files = await async_client.pipelines.add_files_to_pipeline(pipeline.id, request=files)

TypeScript Client

import { addFilesToPipelineApiApiV1PipelinesPipelineIdFilesPut } from "llama-cloud-services/api";


const files = await addFilesToPipelineApiApiV1PipelinesPipelineIdFilesPut({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  path: {
    pipeline_id: "...",
  },
  body: [
    {
      file_id: file.data?.id,
      custom_metadata: {
        document_type: 'INVOICE' // Optioal, an example on how to add custom metadata to your files
      }
    }
  ]
});

console.log(files.data?.length);

Add data sources to index

Python Sync Client

data_sources = [
  {
    'data_source_id': data_source.id,
    'sync_interval': 43200.0 # Optional, scheduled sync frequency in seconds. In this case, every 12 hours.
  }
]

pipeline_data_sources = client.pipelines.add_data_sources_to_pipeline(pipeline.id, request=data_sources)

Python Async Client

data_sources = [
  {
    'data_source_id': data_source.id,
    'sync_interval': 43200.0 # Optional, scheduled sync frequency in seconds. In this case, every 12 hours.
  }
]

pipeline_data_sources = await async_client.pipelines.add_data_sources_to_pipeline(pipeline.id, request=data_sources)

TypeScript Client

import { addDataSourcesToPipelineApiV1PipelinesPipelineIdDataSourcesPut } from "llama-cloud-services/api";


const data_sources = await addDataSourcesToPipelineApiV1PipelinesPipelineIdDataSourcesPut({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  path: {
    pipeline_id: "...",
  },
  body: [
    {
      data_source_id: data_source.data?.id,
      sync_interval: 43200.0 // Optional, scheduled sync frequency in seconds. In this case, every 12 hours.
    }
  ]
});

console.log(data_sources.data?.length);

Tip

For more details on scheduled sync, including how the sync timing works, and available sync frequencies, refer to Scheduled sync.

Add documents to index

Python Sync Client

from llama_cloud.types import CloudDocumentCreate

documents = [
CloudDocumentCreate(
text='test-text',
metadata={
'test-key': 'test-val'
}
)
]

documents = client.pipelines.create_batch_pipeline_documents(pipeline.id, request=documents)

Python Async Client

from llama_cloud.types import CloudDocumentCreate

documents = [
CloudDocumentCreate(
text='test-text',
metadata={
'test-key': 'test-val'
}
)
]

documents = await async_client.pipelines.create_batch_pipeline_documents(pipeline.id, request=documents)

TypeScript Client

import { createBatchPipelineDocumentsApiV1PipelinesPipelineIdDocumentsPost } from "llama-cloud-services/api";

const documents = await createBatchPipelineDocumentsApiV1PipelinesPipelineIdDocumentsPost({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  path: {
    pipeline_id: "...",
  },
  body: [
    {
      text: "test-text",
      metadata: {
        text_key: 'text_val'
      }
    }
  ]
});

console.log(documents.data?.length);

Observe ingestion status & history

Get index status

Python Sync Client

status = client.pipelines.get_pipeline_status(pipeline.id)

Python Async Client

status = await async_client.pipelines.get_pipeline_status(pipeline.id)

TypeScript Client

import { getPipelineStatusApiV1PipelinesPipelineIdStatusGet } from "llama-cloud-services/api";


const status = await getPipelineStatusApiV1PipelinesPipelineIdStatusGet({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  path: {
    pipeline_id: "...",
  },
});

console.log(status.data?.status);

Get ingestion job history

Python Sync Client

jobs = client.pipelines.list_pipeline_jobs(pipeline.id)

Python Async Client

jobs = await async_client.pipelines.list_pipeline_jobs(pipeline.id)

TypeScript Client

import { listPipelineJobsApiV1PipelinesPipelineIdJobsGet } from "llama-cloud-services/api";

const jobs = await listPipelineJobsApiV1PipelinesPipelineIdJobsGet({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  path: {
    pipeline_id: "...",
  },
});

console.log(jobs.data?.length);

Run search (i.e. retrieval endpoint)

Python Sync Client

results = client.pipelines.run_search(pipeline.id, query='test-query')

Python Async Client

results = await async_client.pipelines.run_search(pipeline.id, query='test-query')

TypeScript Client

import { runSearchApiV1PipelinesPipelineIdRetrievePost } from "llama-cloud-services/api";

const results = await runSearchApiV1PipelinesPipelineIdRetrievePost({
  headers: {
    Authorization:
      "Bearer llx-...",
  },
  path: {
    pipeline_id: "...",
  },
  body: {
    query: "text-query",
  }
});

console.log(results.data?.retrieval_nodes?.length);