API & Clients

This guide highlights the core workflow.

tip

See full API reference here.

App setup

Python 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>')

TypeScript Client

Install API client package

npm install @llamaindex/cloud

Import and configure client

import { LlamaCloudApiClient } from '@llamaindex/cloud';

const client = new LlamaCloudApiClient({
  token: apiKey
});

Create new index

Upload files

Python Client

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

TypeScript Client

import fs from "fs"

const filePath = "node_modules/llamaindex/examples/abramov.txt";

file = client.files.uploadFile(project.id, fs.createReadStream(filePath))

tip

See Files API for full details on file management.

Configure data sources

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

TypeScript Client

const s3 = {
    'name': 's3',
    'sourceType': 'S3', 
    'component': {
        'bucket': 'test-bucket'
    }
}
data_source = await client.dataSources.createDataSource({
  projectId: projectId,
  body: s3
})

tip

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

See full list of data sources and specifications.

Configure data sinks

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

TypeScript Client

const pinecone = {
    'name': 'pinecone',
    'sinkType': 'PINECONE', 
    'component': {
        'api_key': 'test-key',
        'index_name': 'test-index'
    }
}
data_sink = client.dataSinks.createDataSink({
  projectId: projectId,
  body: pinecone
})

tip

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

See full list of data sinks and specifications.

Create index (i.e. pipeline)

Python Client

pipeline = {
  'name': 'test-pipeline',
  'configured_transformations': [
      {
          'configurable_transformation_type': 'SENTENCE_AWARE_NODE_PARSER',
          'component': {
              'chunk_size': 1024,
              'chunk_overlap': 20,
          }
      },
      {
          'configurable_transformation_type': 'OPENAI_EMBEDDING',
          'component': {
              'model_name': 'text-embedding-ada-002',
              'api_key': 'sk-...',
          }
      }
  ],
  'data_sink_id': data_sink.id
}

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

TypeScript Client

const pipeline = {
    'name': 'test-pipeline',
    'configuredTransformations': [
        {
            'configurableTransformationType': 'SENTENCE_AWARE_NODE_PARSER',
            'component': {
                'chunk_size': 1024,
                'chunk_overlap': 20,
            }
        },
        {
            'configurableTransformationType': 'OPENAI_EMBEDDING',
            'component': {
                'model_name': 'text-embedding-ada-002',
                'api_key': 'sk-...',
            }
        }
    ],
    'dataSinkId': data_sink.id
}

await client.pipelines.upsertPipeline({
  projectId: projectId,
  body: pipeline
})

tip

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

Add files to index

Python Client

files = [
  {'file_id': file.id}
]

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

TypeScript Client

const files = [
    {'file_id': file.id}
]


pipeline_files = client.pipelines.addFilesToPipeline(pipeline.id, files) 

Add data sources to index

Python Client

data_sources = [
  {'data_source_id': data_source.id}
]

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

TypeScript Client

const data_sources = [
    {'data_source_id': data_source.id}
]


pipeline_data_sources = client.pipelines.addDataSourcesToPipeline(pipeline.id, data_sources)

Add documents to index

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

TypeScript Client

const documents = [
    {
        'text': 'test-text',
        'metadata': {
            'test-key': 'test-val'
        }
    }
]

documents = client.pipelines.createBatchPipelineDocuments(pipeline.id, documents)

Observe ingestion status & history

Get index status

Python Client

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

TypeScript Client

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

Get ingestion job history

Python Client

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

TypeScript Client

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

Run search (i.e. retrieval endpoint)

Python Client

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

TypeScript Client

results = client.pipelines.runSearch(pipeline.id, {
  query: 'test-query'
})