API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrievers

Create Retriever

$ llamacloud-prod retrievers create

POST/api/v1/retrievers

Upsert Retriever

$ llamacloud-prod retrievers upsert

PUT/api/v1/retrievers

List Retrievers

$ llamacloud-prod retrievers list

GET/api/v1/retrievers

Get Retriever

$ llamacloud-prod retrievers get

GET/api/v1/retrievers/{retriever_id}

Update Retriever

$ llamacloud-prod retrievers update

PUT/api/v1/retrievers/{retriever_id}

Delete Retriever

$ llamacloud-prod retrievers delete

DELETE/api/v1/retrievers/{retriever_id}

Direct Retrieve

$ llamacloud-prod retrievers search

POST/api/v1/retrievers/retrieve

ModelsExpand Collapse

composite_retrieval_mode: "routing" or "full"

Enum for the mode of composite retrieval.

"routing"

"full"

composite_retrieval_result: object { image_nodes, nodes, page_figure_nodes }

Deprecatedimage_nodes: optional array of PageScreenshotNodeWithScore { node, score, class_name }

The image nodes retrieved by the pipeline for the given query. Deprecated - will soon be replaced with ‘page_screenshot_nodes’.

node: object { file_id, image_size, page_index, metadata }

file_id: string

The ID of the file that the page screenshot was taken from

image_size: number

The size of the image in bytes

page_index: number

The index of the page for which the screenshot is taken (0-indexed)

metadata: optional map[unknown]

Metadata for the screenshot

score: number

The score of the screenshot node

class_name: optional string

nodes: optional array of object { node, class_name, score }

The retrieved nodes from the composite retrieval.

node: object { id, end_char_idx, pipeline_id, 5 more }

id: string

The ID of the retrieved node.

end_char_idx: number

The end character index of the retrieved node in the document

pipeline_id: string

The ID of the pipeline this node was retrieved from.

retriever_id: string

The ID of the retriever this node was retrieved from.

retriever_pipeline_name: string

The name of the retrieval pipeline this node was retrieved from.

start_char_idx: number

The start character index of the retrieved node in the document

text: string

The text of the retrieved node.

metadata: optional map[unknown]

Metadata associated with the retrieved node.

class_name: optional string

score: optional number

page_figure_nodes: optional array of PageFigureNodeWithScore { node, score, class_name }

The page figure nodes retrieved by the pipeline for the given query.

node: object { confidence, figure_name, figure_size, 4 more }

confidence: number

The confidence of the figure

figure_name: string

The name of the figure

figure_size: number

The size of the figure in bytes

file_id: string

The ID of the file that the figure was taken from

page_index: number

The index of the page for which the figure is taken (0-indexed)

is_likely_noise: optional boolean

Whether the figure is likely to be noise

metadata: optional map[unknown]

Metadata for the figure

score: number

The score of the figure node

class_name: optional string

re_rank_config: object { top_n, type }

top_n: optional number

The number of nodes to retrieve after reranking over retrieved nodes from all retrieval tools.

type: optional "system_default" or "llm" or "cohere" or 3 more

The type of reranker to use.

"system_default"

"llm"

"cohere"

"bedrock"

"score"

"disabled"

retriever: object { id, name, project_id, 3 more }

An entity that retrieves context nodes from several sub RetrieverTools.

id: string

Unique identifier

name: string

A name for the retriever tool. Will default to the pipeline name if not provided.

project_id: string

The ID of the project this retriever resides in.

created_at: optional string

Creation datetime

pipelines: optional array of RetrieverPipeline { description, name, pipeline_id, preset_retrieval_parameters }

The pipelines this retriever uses.

description: string

A description of the retriever tool.

name: string

A name for the retriever tool. Will default to the pipeline name if not provided.

pipeline_id: string

The ID of the pipeline this tool uses.

preset_retrieval_parameters: optional object { alpha, class_name, dense_similarity_cutoff, 11 more }

Parameters for retrieval configuration.

alpha: optional number

Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.

class_name: optional string

dense_similarity_cutoff: optional number

Minimum similarity score wrt query for retrieval

dense_similarity_top_k: optional number

Number of nodes for dense retrieval.

enable_reranking: optional boolean

Enable reranking for retrieval

files_top_k: optional number

Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).

rerank_top_n: optional number

Number of reranked nodes for returning.

retrieval_mode: optional "chunks" or "files_via_metadata" or "files_via_content" or "auto_routed"

The retrieval mode for the query.

"chunks"

"files_via_metadata"

"files_via_content"

"auto_routed"

Deprecatedretrieve_image_nodes: optional boolean

Whether to retrieve image nodes.

retrieve_page_figure_nodes: optional boolean

Whether to retrieve page figure nodes.

retrieve_page_screenshot_nodes: optional boolean

Whether to retrieve page screenshot nodes.

search_filters: optional object { filters, condition }

Metadata filters for vector stores.

filters: array of object { key, value, operator } or MetadataFilters { filters, condition }

MetadataFilter: object { key, value, operator }

Comprehensive metadata filter for vector stores to support more operators.

Value uses Strict types, as int, float and str are compatible types and were all converted to string before.

See: https://docs.pydantic.dev/latest/usage/types/#strict-types

key: string

value: number or string or array of string or 2 more

union_member_0: number

union_member_1: string

union_member_2: array of string

union_member_3: array of number

union_member_4: array of number

operator: optional "==" or ">" or "<" or 11 more

Vector store filter operator.

"=="

">"

"<"

"!="

">="

"<="

"in"

"nin"

"any"

"all"

"text_match"

"text_match_insensitive"

"contains"

"is_empty"

metadata_filters

condition: optional "and" or "or" or "not"

Vector store filter conditions to combine different filters.

"and"

"or"

"not"

search_filters_inference_schema: optional map[map[unknown] or array of unknown or string or 2 more]

JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.

union_member_0: map[unknown]

union_member_1: array of unknown

union_member_2: string

union_member_3: number

union_member_4: boolean

sparse_similarity_top_k: optional number

Number of nodes for sparse retrieval.

updated_at: optional string

Update datetime

retriever_create: object { name, pipelines }

name: string

A name for the retriever tool. Will default to the pipeline name if not provided.

pipelines: optional array of RetrieverPipeline { description, name, pipeline_id, preset_retrieval_parameters }

The pipelines this retriever uses.

description: string

A description of the retriever tool.

name: string

A name for the retriever tool. Will default to the pipeline name if not provided.

pipeline_id: string

The ID of the pipeline this tool uses.

preset_retrieval_parameters: optional object { alpha, class_name, dense_similarity_cutoff, 11 more }

Parameters for retrieval configuration.

alpha: optional number

Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.

class_name: optional string

dense_similarity_cutoff: optional number

Minimum similarity score wrt query for retrieval

dense_similarity_top_k: optional number

Number of nodes for dense retrieval.

enable_reranking: optional boolean

Enable reranking for retrieval

files_top_k: optional number

Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).

rerank_top_n: optional number

Number of reranked nodes for returning.

retrieval_mode: optional "chunks" or "files_via_metadata" or "files_via_content" or "auto_routed"

The retrieval mode for the query.

"chunks"

"files_via_metadata"

"files_via_content"

"auto_routed"

Deprecatedretrieve_image_nodes: optional boolean

Whether to retrieve image nodes.

retrieve_page_figure_nodes: optional boolean

Whether to retrieve page figure nodes.

retrieve_page_screenshot_nodes: optional boolean

Whether to retrieve page screenshot nodes.

search_filters: optional object { filters, condition }

Metadata filters for vector stores.

filters: array of object { key, value, operator } or MetadataFilters { filters, condition }

MetadataFilter: object { key, value, operator }

Comprehensive metadata filter for vector stores to support more operators.

Value uses Strict types, as int, float and str are compatible types and were all converted to string before.

See: https://docs.pydantic.dev/latest/usage/types/#strict-types

key: string

value: number or string or array of string or 2 more

union_member_0: number

union_member_1: string

union_member_2: array of string

union_member_3: array of number

union_member_4: array of number

operator: optional "==" or ">" or "<" or 11 more

Vector store filter operator.

"=="

">"

"<"

"!="

">="

"<="

"in"

"nin"

"any"

"all"

"text_match"

"text_match_insensitive"

"contains"

"is_empty"

metadata_filters

condition: optional "and" or "or" or "not"

Vector store filter conditions to combine different filters.

"and"

"or"

"not"

search_filters_inference_schema: optional map[map[unknown] or array of unknown or string or 2 more]

JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.

union_member_0: map[unknown]

union_member_1: array of unknown

union_member_2: string

union_member_3: number

union_member_4: boolean

sparse_similarity_top_k: optional number

Number of nodes for sparse retrieval.

retriever_pipeline: object { description, name, pipeline_id, preset_retrieval_parameters }

description: string

A description of the retriever tool.

name: string

A name for the retriever tool. Will default to the pipeline name if not provided.

pipeline_id: string

The ID of the pipeline this tool uses.

preset_retrieval_parameters: optional object { alpha, class_name, dense_similarity_cutoff, 11 more }

Parameters for retrieval configuration.

alpha: optional number

Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.

class_name: optional string

dense_similarity_cutoff: optional number

Minimum similarity score wrt query for retrieval

dense_similarity_top_k: optional number

Number of nodes for dense retrieval.

enable_reranking: optional boolean

Enable reranking for retrieval

files_top_k: optional number

Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).

rerank_top_n: optional number

Number of reranked nodes for returning.

retrieval_mode: optional "chunks" or "files_via_metadata" or "files_via_content" or "auto_routed"

The retrieval mode for the query.

"chunks"

"files_via_metadata"

"files_via_content"

"auto_routed"

Deprecatedretrieve_image_nodes: optional boolean

Whether to retrieve image nodes.

retrieve_page_figure_nodes: optional boolean

Whether to retrieve page figure nodes.

retrieve_page_screenshot_nodes: optional boolean

Whether to retrieve page screenshot nodes.

search_filters: optional object { filters, condition }

Metadata filters for vector stores.

filters: array of object { key, value, operator } or MetadataFilters { filters, condition }

MetadataFilter: object { key, value, operator }

Comprehensive metadata filter for vector stores to support more operators.

Value uses Strict types, as int, float and str are compatible types and were all converted to string before.

See: https://docs.pydantic.dev/latest/usage/types/#strict-types

key: string

value: number or string or array of string or 2 more

union_member_0: number

union_member_1: string

union_member_2: array of string

union_member_3: array of number

union_member_4: array of number

operator: optional "==" or ">" or "<" or 11 more

Vector store filter operator.

"=="

">"

"<"

"!="

">="

"<="

"in"

"nin"

"any"

"all"

"text_match"

"text_match_insensitive"

"contains"

"is_empty"

metadata_filters

condition: optional "and" or "or" or "not"

Vector store filter conditions to combine different filters.

"and"

"or"

"not"

search_filters_inference_schema: optional map[map[unknown] or array of unknown or string or 2 more]

JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.

union_member_0: map[unknown]

union_member_1: array of unknown

union_member_2: string

union_member_3: number

union_member_4: boolean

sparse_similarity_top_k: optional number

Number of nodes for sparse retrieval.

RetrieversRetriever

Retrieve

$ llamacloud-prod retrievers:retriever search

POST/api/v1/retrievers/{retriever_id}/retrieve