openapi: 3.1.0
info:
  title: LlamaIndex LlamaCloud API
  description: >-
    The LlamaCloud API is the central REST API for LlamaIndex's cloud platform,
    providing programmatic access to managed document processing, indexing, and
    retrieval services. It enables developers to build production-grade LLM
    applications by leveraging cloud-hosted infrastructure for document
    ingestion, knowledge management, and agent orchestration. The API supports
    authentication via API keys and is available in both US and EU regions.
  version: '1.0'
  contact:
    name: LlamaIndex Support
    url: https://www.llamaindex.ai/contact
  termsOfService: https://www.llamaindex.ai/terms-of-service
externalDocs:
  description: LlamaCloud API Documentation
  url: https://developers.api.llamaindex.ai/
servers:
  - url: https://api.cloud.llamaindex.ai/api/v1
    description: US Production Server
  - url: https://api.cloud.llamaindex.eu/api/v1
    description: EU Production Server
tags:
  - name: Data Sources
    description: >-
      Manage data sources at the project level.
  - name: Files
    description: >-
      Upload, list, and manage files for use in pipelines and parsing jobs.
  - name: Pipeline Data Sinks
    description: >-
      Manage data sinks that receive processed data from a pipeline.
  - name: Pipeline Data Sources
    description: >-
      Manage data sources connected to a pipeline for automatic ingestion.
  - name: Pipeline Files
    description: >-
      Manage files associated with a specific pipeline.
  - name: Pipeline Jobs
    description: >-
      Monitor and manage ingestion jobs for a pipeline.
  - name: Pipelines
    description: >-
      Create, configure, sync, and manage document ingestion pipelines.
  - name: Projects
    description: >-
      Manage projects that organize pipelines, files, and other resources.
  - name: Retrieval
    description: >-
      Query and retrieve content from indexed pipelines.
security:
  - bearerAuth: []
paths:
  /projects:
    get:
      operationId: listProjects
      summary: List projects
      description: >-
        Retrieve a list of all projects associated with the authenticated
        account. Projects serve as organizational containers for pipelines,
        files, and other resources.
      tags:
        - Projects
      responses:
        '200':
          description: Successfully retrieved list of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized - invalid or missing API key
    post:
      operationId: createProject
      summary: Create a project
      description: >-
        Create a new project to organize pipelines, files, and other cloud
        resources.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Bad request - invalid project parameters
        '401':
          description: Unauthorized - invalid or missing API key
  /projects/{projectId}:
    get:
      operationId: getProject
      summary: Get a project
      description: >-
        Retrieve details of a specific project by its identifier.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Successfully retrieved project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Project not found
  /files:
    post:
      operationId: uploadFile
      summary: Upload a file
      description: >-
        Upload a file to the cloud platform using multipart form data. The file
        can then be used in pipelines, parsing jobs, or extraction workflows.
      tags:
        - Files
      parameters:
        - name: project_id
          in: query
          description: >-
            The project to associate the file with.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    The file to upload.
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '400':
          description: Bad request - invalid file or missing parameters
        '401':
          description: Unauthorized - invalid or missing API key
  /pipelines:
    get:
      operationId: listPipelines
      summary: List pipelines
      description: >-
        Retrieve a list of all pipelines for the specified project. Pipelines
        represent document ingestion workflows that process, embed, and index
        documents.
      tags:
        - Pipelines
      parameters:
        - name: project_id
          in: query
          description: >-
            Filter pipelines by project identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved list of pipelines
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pipeline'
        '401':
          description: Unauthorized - invalid or missing API key
    post:
      operationId: createPipeline
      summary: Create a pipeline
      description: >-
        Create a new document ingestion pipeline with specified configuration
        including parsing, embedding, and vector store settings.
      tags:
        - Pipelines
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePipelineRequest'
      responses:
        '201':
          description: Pipeline created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
        '400':
          description: Bad request - invalid pipeline configuration
        '401':
          description: Unauthorized - invalid or missing API key
  /pipelines/{pipelineId}:
    get:
      operationId: getPipeline
      summary: Get a pipeline
      description: >-
        Retrieve detailed information about a specific pipeline including its
        configuration, status, and associated resources.
      tags:
        - Pipelines
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      responses:
        '200':
          description: Successfully retrieved pipeline details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
    delete:
      operationId: deletePipeline
      summary: Delete a pipeline
      description: >-
        Delete a pipeline and optionally its associated resources.
      tags:
        - Pipelines
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      responses:
        '200':
          description: Pipeline deleted successfully
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
  /pipelines/{pipelineId}/sync:
    post:
      operationId: syncPipeline
      summary: Sync a pipeline
      description: >-
        Run ingestion for the pipeline by incrementally updating the data sink
        with upstream changes from data sources and files. This triggers a
        new ingestion job that processes any new or modified content.
      tags:
        - Pipelines
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      responses:
        '200':
          description: Pipeline sync initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineJob'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
  /pipelines/{pipelineId}/retrieve:
    post:
      operationId: runSearch
      summary: Run search
      description: >-
        Execute a retrieval query against the indexed content of a managed
        pipeline. Returns ranked results matching the query with configurable
        retrieval modes including fast, accurate, and advanced options.
      tags:
        - Retrieval
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrievalRequest'
      responses:
        '200':
          description: Search results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalResponse'
        '400':
          description: Bad request - invalid query parameters
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
  /pipelines/{pipelineId}/files:
    get:
      operationId: listPipelineFiles
      summary: List pipeline files
      description: >-
        Retrieve a list of files associated with a specific pipeline, including
        their processing status and metadata.
      tags:
        - Pipeline Files
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      responses:
        '200':
          description: Successfully retrieved list of pipeline files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PipelineFile'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
    put:
      operationId: addFilesToPipeline
      summary: Add files to a pipeline
      description: >-
        Add one or more previously uploaded files to a pipeline for processing.
        Files can include optional custom metadata.
      tags:
        - Pipeline Files
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PipelineFileInput'
      responses:
        '200':
          description: Files added to pipeline successfully
        '400':
          description: Bad request - invalid file references
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
  /pipelines/{pipelineId}/data-sources:
    get:
      operationId: listPipelineDataSources
      summary: List pipeline data sources
      description: >-
        Retrieve data sources connected to a specific pipeline. Data sources
        provide automatic ingestion of documents from external systems.
      tags:
        - Pipeline Data Sources
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      responses:
        '200':
          description: Successfully retrieved list of pipeline data sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataSource'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
    put:
      operationId: addDataSourcesToPipeline
      summary: Add data sources to a pipeline
      description: >-
        Connect data sources to a pipeline for automatic document ingestion.
        When data sources are connected, the pipeline will sync content from
        these sources based on the configured schedule.
      tags:
        - Pipeline Data Sources
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DataSourceInput'
      responses:
        '200':
          description: Data sources added to pipeline successfully
        '400':
          description: Bad request - invalid data source configuration
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
  /pipelines/{pipelineId}/data-sinks:
    get:
      operationId: listPipelineDataSinks
      summary: List pipeline data sinks
      description: >-
        Retrieve data sinks configured for a specific pipeline. Data sinks
        define where processed and embedded content is stored, such as
        vector databases.
      tags:
        - Pipeline Data Sinks
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      responses:
        '200':
          description: Successfully retrieved list of pipeline data sinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataSink'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
  /pipelines/{pipelineId}/jobs:
    get:
      operationId: listPipelineJobs
      summary: List pipeline jobs
      description: >-
        Retrieve a list of ingestion jobs for a specific pipeline, including
        their status and processing details.
      tags:
        - Pipeline Jobs
      parameters:
        - $ref: '#/components/parameters/pipelineId'
      responses:
        '200':
          description: Successfully retrieved list of pipeline jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PipelineJob'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Pipeline not found
  /data-sources:
    get:
      operationId: listDataSources
      summary: List data sources
      description: >-
        Retrieve a list of all data sources for the specified project.
      tags:
        - Data Sources
      parameters:
        - name: project_id
          in: query
          description: >-
            Filter data sources by project identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved list of data sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataSource'
        '401':
          description: Unauthorized - invalid or missing API key
    post:
      operationId: createDataSource
      summary: Create a data source
      description: >-
        Create a new data source that can be connected to one or more pipelines
        for automatic document ingestion.
      tags:
        - Data Sources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSourceInput'
      responses:
        '201':
          description: Data source created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
        '400':
          description: Bad request - invalid data source configuration
        '401':
          description: Unauthorized - invalid or missing API key
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        LlamaCloud API key obtained from the LlamaCloud dashboard. Include as
        a Bearer token in the Authorization header.
  parameters:
    projectId:
      name: projectId
      in: path
      description: >-
        Unique identifier of the project.
      required: true
      schema:
        type: string
    pipelineId:
      name: pipelineId
      in: path
      description: >-
        Unique identifier of the pipeline.
      required: true
      schema:
        type: string
  schemas:
    Project:
      type: object
      description: >-
        A project that organizes pipelines, files, and other cloud resources.
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the project.
        name:
          type: string
          description: >-
            Human-readable name of the project.
        created_at:
          type: string
          format: date-time
          description: >-
            Timestamp when the project was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            Timestamp when the project was last updated.
    CreateProjectRequest:
      type: object
      description: >-
        Request body for creating a new project.
      required:
        - name
      properties:
        name:
          type: string
          description: >-
            Human-readable name for the new project.
    File:
      type: object
      description: >-
        A file uploaded to the LlamaCloud platform.
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the file.
        name:
          type: string
          description: >-
            Original file name.
        project_id:
          type: string
          description: >-
            Identifier of the project the file belongs to.
        file_size:
          type: integer
          description: >-
            Size of the file in bytes.
        content_type:
          type: string
          description: >-
            MIME type of the file.
        created_at:
          type: string
          format: date-time
          description: >-
            Timestamp when the file was uploaded.
    Pipeline:
      type: object
      description: >-
        A document ingestion pipeline that processes, embeds, and indexes
        documents for retrieval.
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the pipeline.
        name:
          type: string
          description: >-
            Human-readable name of the pipeline.
        project_id:
          type: string
          description: >-
            Identifier of the project the pipeline belongs to.
        status:
          type: string
          enum:
            - active
            - syncing
            - error
            - idle
          description: >-
            Current status of the pipeline.
        sync_interval:
          type: integer
          description: >-
            Scheduled sync frequency in seconds, if configured.
        created_at:
          type: string
          format: date-time
          description: >-
            Timestamp when the pipeline was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            Timestamp when the pipeline was last updated.
    CreatePipelineRequest:
      type: object
      description: >-
        Request body for creating a new pipeline.
      required:
        - name
        - project_id
      properties:
        name:
          type: string
          description: >-
            Human-readable name for the new pipeline.
        project_id:
          type: string
          description: >-
            Identifier of the project to create the pipeline in.
        sync_interval:
          type: integer
          description: >-
            Optional scheduled sync frequency in seconds.
    PipelineFile:
      type: object
      description: >-
        A file associated with a pipeline, including processing status.
      properties:
        file_id:
          type: string
          description: >-
            Unique identifier of the file.
        name:
          type: string
          description: >-
            Original file name.
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - error
          description: >-
            Processing status of the file within the pipeline.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Custom metadata associated with the file.
    PipelineFileInput:
      type: object
      description: >-
        Input for adding a file to a pipeline.
      required:
        - file_id
      properties:
        file_id:
          type: string
          description: >-
            Identifier of the file to add to the pipeline.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Optional custom metadata to associate with the file.
    PipelineJob:
      type: object
      description: >-
        An ingestion job for a pipeline that tracks the processing of
        documents.
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the job.
        pipeline_id:
          type: string
          description: >-
            Identifier of the pipeline the job belongs to.
        status:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
          description: >-
            Current status of the job.
        created_at:
          type: string
          format: date-time
          description: >-
            Timestamp when the job was created.
        completed_at:
          type: string
          format: date-time
          description: >-
            Timestamp when the job completed, if applicable.
    DataSource:
      type: object
      description: >-
        A data source connected to a pipeline for automatic document ingestion.
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the data source.
        name:
          type: string
          description: >-
            Human-readable name of the data source.
        source_type:
          type: string
          description: >-
            Type of the data source.
        project_id:
          type: string
          description: >-
            Identifier of the project the data source belongs to.
        config:
          type: object
          additionalProperties: true
          description: >-
            Configuration specific to the data source type.
        created_at:
          type: string
          format: date-time
          description: >-
            Timestamp when the data source was created.
    DataSourceInput:
      type: object
      description: >-
        Input for creating or connecting a data source.
      required:
        - name
        - source_type
      properties:
        name:
          type: string
          description: >-
            Human-readable name for the data source.
        source_type:
          type: string
          description: >-
            Type of the data source.
        project_id:
          type: string
          description: >-
            Identifier of the project to associate the data source with.
        config:
          type: object
          additionalProperties: true
          description: >-
            Configuration specific to the data source type.
    DataSink:
      type: object
      description: >-
        A data sink that receives processed and embedded content from a
        pipeline, such as a vector database.
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the data sink.
        name:
          type: string
          description: >-
            Human-readable name of the data sink.
        sink_type:
          type: string
          description: >-
            Type of the data sink.
        config:
          type: object
          additionalProperties: true
          description: >-
            Configuration specific to the data sink type.
    RetrievalRequest:
      type: object
      description: >-
        Request body for running a retrieval query against a pipeline.
      required:
        - query
      properties:
        query:
          type: string
          description: >-
            The search query to run against the indexed content.
        mode:
          type: string
          enum:
            - fast
            - accurate
            - advanced
          description: >-
            Retrieval mode that controls the trade-off between speed and
            accuracy.
        top_k:
          type: integer
          minimum: 1
          description: >-
            Maximum number of results to return after re-ranking.
    RetrievalResponse:
      type: object
      description: >-
        Response containing retrieval results from a pipeline query.
      properties:
        results:
          type: array
          description: >-
            List of retrieval results ranked by relevance.
          items:
            $ref: '#/components/schemas/RetrievalResult'
    RetrievalResult:
      type: object
      description: >-
        A single retrieval result containing matched content and metadata.
      properties:
        text:
          type: string
          description: >-
            The retrieved text content.
        score:
          type: number
          format: float
          description: >-
            Relevance score for the result.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Metadata associated with the retrieved content.