openapi: 3.1.0
info:
  title: LlamaIndex LlamaCloud Data Sources Parsing 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
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
security:
- bearerAuth: []
tags:
- name: Parsing
  description: Parse documents into structured formats using AI-powered extraction. Supports multiple tiers for different quality and speed trade-offs.
paths:
  /parse:
    post:
      operationId: parseDocument
      summary: Parse a document
      description: Submit a document for parsing using a JSON request body. Accepts either a file_id referencing a previously uploaded file or a source_url to fetch the document from. Exactly one of file_id or source_url must be provided. The tier parameter determines the parsing mode. Jobs are processed asynchronously and results are retrieved via the job status endpoint.
      tags:
      - Parsing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseRequest'
      responses:
        '200':
          description: Parse job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseJobCreated'
        '400':
          description: Bad request - invalid parameters or missing required fields
        '401':
          description: Unauthorized - invalid or missing API key
  /parse/upload:
    post:
      operationId: parseDocumentUpload
      summary: Parse a document via file upload
      description: Submit a document for parsing using multipart file upload. The file is uploaded directly along with parsing configuration. The tier parameter determines the parsing mode. Jobs are processed asynchronously and results are retrieved via the job status endpoint.
      tags:
      - Parsing
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ParseUploadRequest'
      responses:
        '200':
          description: Parse job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseJobCreated'
        '400':
          description: Bad request - invalid file or missing parameters
        '401':
          description: Unauthorized - invalid or missing API key
components:
  schemas:
    ParseRequest:
      type: object
      description: Request body for parsing a document via JSON. Exactly one of file_id or source_url must be provided.
      required:
      - tier
      - version
      properties:
        file_id:
          type: string
          description: Identifier of a previously uploaded file to parse. Mutually exclusive with source_url.
        source_url:
          type: string
          format: uri
          description: URL of a document to fetch and parse. Mutually exclusive with file_id.
        http_proxy:
          type: string
          format: uri
          description: Optional HTTP proxy to use when fetching the document from source_url.
        tier:
          type: string
          enum:
          - fast
          - cost_effective
          - agentic
          - agentic_plus
          description: Parsing tier that determines the quality and speed trade-off. Fast outputs spatial text only. Cost-effective is optimized for text-heavy documents. Agentic handles images and diagrams. Agentic plus provides maximum fidelity for complex layouts.
        version:
          type: string
          description: API version to use. Use "latest" for the most recent version, or a specific version date string for production stability.
        target_pages:
          type: string
          description: Page range to parse using 1-based indexing (e.g., "1-5", "3,7,10").
        agentic_options:
          type: object
          description: Additional options for the agentic and agentic_plus tiers. Not supported by the fast tier.
          additionalProperties: true
    ParseUploadRequest:
      type: object
      description: Multipart form data request for uploading and parsing a document.
      required:
      - file
      - configuration
      properties:
        file:
          type: string
          format: binary
          description: The document file to upload and parse.
        configuration:
          type: string
          description: JSON string containing the parsing configuration including tier, version, and other options.
    ParseJobCreated:
      type: object
      description: Response returned when a parse job is successfully created.
      properties:
        id:
          type: string
          description: Unique identifier of the created parse job.
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          description: Initial status of the parse job.
  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.
externalDocs:
  description: LlamaCloud API Documentation
  url: https://developers.api.llamaindex.ai/