Schema-driven structured data extraction from documents. Define an extraction agent with a JSON data schema, run extraction jobs against uploaded files, and retrieve typed JSON results with field-level citations and metadata.
openapi: 3.0.1
info:
title: LlamaCloud API
description: >-
REST API for the LlamaCloud managed document platform from LlamaIndex,
covering LlamaParse document parsing, managed ingestion pipelines and
indexes, document and file management, retrieval, and LlamaExtract
structured extraction. All endpoints are authenticated with a Bearer
API key.
termsOfService: https://www.llamaindex.ai/terms-of-service
contact:
name: LlamaIndex Support
email: support@llamaindex.ai
version: '1.0'
servers:
- url: https://api.cloud.llamaindex.ai/api/v1
description: LlamaCloud v1 API
security:
- bearerAuth: []
tags:
- name: Parsing
description: LlamaParse document parsing jobs and results.
- name: Pipelines
description: Managed ingestion and indexing pipelines.
- name: Documents
description: Files and pipeline documents.
- name: Retrieval
description: Query a managed index for relevant chunks.
- name: Extraction
description: LlamaExtract schema-driven structured extraction.
paths:
/parsing/upload:
post:
operationId: uploadParsingJob
tags:
- Parsing
summary: Upload a file to start a parse job
description: >-
Uploads a document and creates an asynchronous LlamaParse job. Returns
a job id used to poll status and retrieve results in Markdown or JSON.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: The document to parse (PDF, DOCX, PPTX, image, etc.).
parsing_instruction:
type: string
description: Natural-language instructions to guide parsing.
result_type:
type: string
enum: [markdown, text, json]
default: markdown
language:
type: string
description: Primary document language hint (e.g. en).
responses:
'200':
description: Parse job created.
content:
application/json:
schema:
$ref: '#/components/schemas/ParsingJob'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/parsing/job/{job_id}:
get:
operationId: getParsingJob
tags:
- Parsing
summary: Get parse job status
description: Returns the status of a parse job. Poll until status is SUCCESS.
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Parse job status.
content:
application/json:
schema:
$ref: '#/components/schemas/ParsingJob'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/parsing/job/{job_id}/result/markdown:
get:
operationId: getParsingResultMarkdown
tags:
- Parsing
summary: Get parse result as Markdown
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Markdown parse result.
content:
application/json:
schema:
$ref: '#/components/schemas/MarkdownResult'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/parsing/job/{job_id}/result/json:
get:
operationId: getParsingResultJson
tags:
- Parsing
summary: Get parse result as structured JSON
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: JSON parse result with pages, items, and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonResult'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/files:
post:
operationId: uploadFile
tags:
- Documents
summary: Upload a file
description: Uploads a file to LlamaCloud for use in pipelines or extraction.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
upload_file:
type: string
format: binary
responses:
'200':
description: File uploaded.
content:
application/json:
schema:
$ref: '#/components/schemas/File'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listFiles
tags:
- Documents
summary: List files
parameters:
- name: project_id
in: query
schema:
type: string
responses:
'200':
description: A list of files.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/File'
'401':
$ref: '#/components/responses/Unauthorized'
/pipelines:
post:
operationId: createPipeline
tags:
- Pipelines
summary: Create or upsert a pipeline
description: Creates a managed ingestion and indexing pipeline.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineCreate'
responses:
'200':
description: Pipeline created.
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
get:
operationId: listPipelines
tags:
- Pipelines
summary: List pipelines
parameters:
- name: project_id
in: query
schema:
type: string
responses:
'200':
description: A list of pipelines.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pipeline'
'401':
$ref: '#/components/responses/Unauthorized'
/pipelines/{pipeline_id}:
get:
operationId: getPipeline
tags:
- Pipelines
summary: Get a pipeline
parameters:
- $ref: '#/components/parameters/PipelineId'
responses:
'200':
description: Pipeline detail.
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/pipelines/{pipeline_id}/status:
get:
operationId: getPipelineStatus
tags:
- Pipelines
summary: Get pipeline ingestion status
parameters:
- $ref: '#/components/parameters/PipelineId'
responses:
'200':
description: Ingestion status.
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum: [NOT_STARTED, IN_PROGRESS, SUCCESS, ERROR, PARTIAL_SUCCESS]
'401':
$ref: '#/components/responses/Unauthorized'
/pipelines/{pipeline_id}/files:
post:
operationId: addFilesToPipeline
tags:
- Pipelines
summary: Add files to a pipeline
description: Attaches previously uploaded files to a pipeline for ingestion.
parameters:
- $ref: '#/components/parameters/PipelineId'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
properties:
file_id:
type: string
responses:
'200':
description: Files added to the pipeline.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PipelineFile'
'401':
$ref: '#/components/responses/Unauthorized'
/pipelines/{pipeline_id}/documents:
post:
operationId: createPipelineDocuments
tags:
- Documents
summary: Add documents to a pipeline
description: Adds raw documents directly to a pipeline's managed index.
parameters:
- $ref: '#/components/parameters/PipelineId'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Document'
responses:
'200':
description: Documents added.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Document'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listPipelineDocuments
tags:
- Documents
summary: List pipeline documents
parameters:
- $ref: '#/components/parameters/PipelineId'
responses:
'200':
description: A list of documents in the pipeline.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Document'
'401':
$ref: '#/components/responses/Unauthorized'
/pipelines/{pipeline_id}/retrieve:
post:
operationId: retrieveFromPipeline
tags:
- Retrieval
summary: Retrieve relevant chunks from a pipeline index
description: >-
Runs a retrieval query against a pipeline's managed index and returns
the most relevant nodes, with optional reranking and metadata filters.
parameters:
- $ref: '#/components/parameters/PipelineId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveRequest'
responses:
'200':
description: Retrieval results.
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/extraction/extraction-agents:
post:
operationId: createExtractionAgent
tags:
- Extraction
summary: Create an extraction agent
description: >-
Defines a LlamaExtract agent bound to a JSON data schema describing the
fields to extract from documents.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractionAgentCreate'
responses:
'200':
description: Extraction agent created.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractionAgent'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
get:
operationId: listExtractionAgents
tags:
- Extraction
summary: List extraction agents
responses:
'200':
description: A list of extraction agents.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ExtractionAgent'
'401':
$ref: '#/components/responses/Unauthorized'
/extraction/jobs:
post:
operationId: runExtractionJob
tags:
- Extraction
summary: Run an extraction job
description: >-
Runs an extraction agent against an uploaded file and returns an async
job id. Poll the job to retrieve the structured result.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractionJobCreate'
responses:
'200':
description: Extraction job created.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractionJob'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/extraction/jobs/{job_id}:
get:
operationId: getExtractionJob
tags:
- Extraction
summary: Get extraction job status
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Extraction job status.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractionJob'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/extraction/jobs/{job_id}/result:
get:
operationId: getExtractionJobResult
tags:
- Extraction
summary: Get extraction job result
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Structured extraction result.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractionResult'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: LlamaCloud API key sent as a Bearer token.
parameters:
JobId:
name: job_id
in: path
required: true
schema:
type: string
PipelineId:
name: pipeline_id
in: path
required: true
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: Request validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
ParsingJob:
type: object
properties:
id:
type: string
status:
type: string
enum: [PENDING, RUNNING, SUCCESS, ERROR, CANCELLED]
error_message:
type: string
nullable: true
MarkdownResult:
type: object
properties:
markdown:
type: string
job_metadata:
type: object
additionalProperties: true
JsonResult:
type: object
properties:
pages:
type: array
items:
type: object
properties:
page:
type: integer
text:
type: string
md:
type: string
items:
type: array
items:
type: object
additionalProperties: true
job_metadata:
type: object
additionalProperties: true
File:
type: object
properties:
id:
type: string
name:
type: string
file_size:
type: integer
file_type:
type: string
project_id:
type: string
created_at:
type: string
format: date-time
PipelineCreate:
type: object
required:
- name
properties:
name:
type: string
embedding_config:
type: object
additionalProperties: true
transform_config:
type: object
additionalProperties: true
Pipeline:
type: object
properties:
id:
type: string
name:
type: string
project_id:
type: string
pipeline_type:
type: string
enum: [MANAGED, PLAYGROUND]
created_at:
type: string
format: date-time
PipelineFile:
type: object
properties:
id:
type: string
file_id:
type: string
pipeline_id:
type: string
Document:
type: object
properties:
id:
type: string
text:
type: string
metadata:
type: object
additionalProperties: true
RetrieveRequest:
type: object
required:
- query
properties:
query:
type: string
dense_similarity_top_k:
type: integer
default: 6
sparse_similarity_top_k:
type: integer
enable_reranking:
type: boolean
default: true
rerank_top_n:
type: integer
retrieval_mode:
type: string
enum: [chunks, files_via_metadata, files_via_content, auto_routed]
filters:
type: object
additionalProperties: true
RetrieveResponse:
type: object
properties:
retrieval_nodes:
type: array
items:
type: object
properties:
node:
$ref: '#/components/schemas/Document'
score:
type: number
format: float
ExtractionAgentCreate:
type: object
required:
- name
- data_schema
properties:
name:
type: string
data_schema:
type: object
additionalProperties: true
config:
type: object
additionalProperties: true
ExtractionAgent:
type: object
properties:
id:
type: string
name:
type: string
data_schema:
type: object
additionalProperties: true
project_id:
type: string
created_at:
type: string
format: date-time
ExtractionJobCreate:
type: object
required:
- extraction_agent_id
- file_id
properties:
extraction_agent_id:
type: string
file_id:
type: string
ExtractionJob:
type: object
properties:
id:
type: string
extraction_agent_id:
type: string
status:
type: string
enum: [PENDING, RUNNING, SUCCESS, ERROR, CANCELLED]
error_message:
type: string
nullable: true
ExtractionResult:
type: object
properties:
data:
type: object
additionalProperties: true
extraction_metadata:
type: object
additionalProperties: true
Error:
type: object
properties:
detail:
type: string