openapi: 3.0.3
info:
  title: Llama Platform Agent Data Classify API
  version: 0.1.0
tags:
- name: Classify
paths:
  /api/v2/classify:
    post:
      tags:
      - Classify
      summary: Create Classify Job
      description: 'Create a classify job.


        Classifies a document against a set of rules. Set `file_input`

        to a file ID (`dfl-...`) or parse job ID (`pjb-...`), and provide

        either inline `configuration` with rules or a `configuration_id`

        referencing a saved preset.


        Each rule has a `type` (the label to assign) and a `description`

        (natural language criteria). The classifier returns the best

        matching rule with a confidence score.


        The job runs asynchronously. Poll `GET /classify/{job_id}` to

        check status and retrieve results.'
      operationId: create_classify_job_api_v2_classify_post
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
      - name: session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassifyV2JobCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyV2JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Classify
      summary: List Classify Jobs
      description: 'List classify jobs with optional filtering and pagination.


        Filter by `status`, `configuration_id`, specific `job_ids`,

        or creation date range.'
      operationId: list_classify_jobs_api_v2_classify_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 100
            minimum: 1
          - type: 'null'
          description: Number of items per page
          title: Page Size
        description: Number of items per page
      - name: page_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Token for pagination
          title: Page Token
        description: Token for pagination
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - PENDING
            - RUNNING
            - COMPLETED
            - FAILED
            type: string
          - type: 'null'
          description: Filter by job status
          title: Status
        description: Filter by job status
      - name: job_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by specific job IDs
          title: Job Ids
        description: Filter by specific job IDs
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
      - name: configuration_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by configuration ID
          examples:
          - cfg-11111111-2222-3333-4444-555555555555
          title: Configuration Id
        description: Filter by configuration ID
      - name: created_at_on_or_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Include items created at or after this timestamp (inclusive)
          title: Created At On Or After
        description: Include items created at or after this timestamp (inclusive)
      - name: created_at_on_or_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Include items created at or before this timestamp (inclusive)
          title: Created At On Or Before
        description: Include items created at or before this timestamp (inclusive)
      - name: session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Session
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyV2JobQueryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/classify/{job_id}:
    get:
      tags:
      - Classify
      summary: Get Classify Job
      description: 'Get a classify job by ID.


        Returns the job status, configuration, and classify result

        when complete. The result includes the matched document type,

        confidence score, and reasoning.'
      operationId: get_classify_job_api_v2_classify__job_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
      - name: session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Session
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyV2JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/classify/{job_id}/cancel:
    post:
      tags:
      - Classify
      summary: Cancel Classify Job
      description: 'Cancel a running classify job.


        Stops processing and marks the job as CANCELLED. Returns the updated job. Jobs already in a terminal state (COMPLETED, FAILED, CANCELLED) cannot be cancelled.'
      operationId: cancel_classify_job_api_v2_classify__job_id__cancel_post
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
      - name: session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Session
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyV2JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ClassifyV2Rule:
      properties:
        type:
          type: string
          maxLength: 50
          minLength: 1
          title: Type
          description: Document type to assign when rule matches
          examples:
          - invoice
          - receipt
          - contract
          - report
          - proposal
        description:
          type: string
          maxLength: 500
          minLength: 10
          title: Description
          description: Natural language criteria for matching this rule
          examples:
          - contains invoice number, line items, and total amount
          - purchase receipt with transaction info and merchant details
          - legal contract with terms, conditions, and signatures
      type: object
      required:
      - type
      - description
      title: ClassifyV2Rule
      description: A rule for classifying documents.
    ClassifyV2JobQueryResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ClassifyV2JobResponse'
          type: array
          title: Items
          description: The list of items.
        next_page_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Page Token
          description: A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
        total_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Size
          description: The total number of items available. This is only populated when specifically requested. The value may be an estimate and can be used for display purposes only.
      type: object
      required:
      - items
      title: ClassifyV2JobQueryResponse
      description: Response schema for paginated classify job queries.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WebhookConfiguration:
      properties:
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
          description: URL to receive webhook POST notifications
          examples:
          - https://example.com/webhooks/llamacloud
        webhook_headers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Webhook Headers
          description: Custom HTTP headers sent with each webhook request (e.g. auth tokens)
          examples:
          - Authorization: Bearer sk-...
        webhook_events:
          anyOf:
          - items:
              type: string
              enum:
              - extract.pending
              - extract.success
              - extract.error
              - extract.partial_success
              - extract.cancelled
              - parse.pending
              - parse.running
              - parse.success
              - parse.error
              - parse.partial_success
              - parse.cancelled
              - classify.pending
              - classify.running
              - classify.success
              - classify.error
              - classify.partial_success
              - classify.cancelled
              - sheets.pending
              - sheets.success
              - sheets.error
              - sheets.partial_success
              - sheets.cancelled
              - unmapped_event
            type: array
          - type: 'null'
          title: Webhook Events
          description: Events to subscribe to (e.g. 'parse.success', 'extract.error'). If null, all events are delivered.
          examples:
          - - parse.success
            - parse.error
        webhook_output_format:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Output Format
          description: 'Response format sent to the webhook: ''string'' (default) or ''json'''
          examples:
          - json
      type: object
      title: WebhookConfiguration
      description: Configuration for a single outbound webhook endpoint.
    ClassifyV2JobResponse:
      properties:
        id:
          anyOf:
          - type: string
          - type: string
            format: uuid
          title: Id
          description: Unique identifier
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: Creation datetime
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: Update datetime
        file_input:
          type: string
          title: File Input
          description: ID of the input file or parse job
        project_id:
          type: string
          title: Project Id
          description: Project this job belongs to
        user_id:
          type: string
          title: User Id
          description: User who created this job
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          title: Status
          description: 'Current job status: PENDING, RUNNING, COMPLETED, or FAILED'
        document_input_type:
          type: string
          enum:
          - url
          - file_id
          - parse_job_id
          title: Document Input Type
          description: Whether the input was a file or parse job (FILE or PARSE_JOB)
        configuration:
          $ref: '#/components/schemas/ClassifyV2Configuration'
          description: Classify configuration used for this job
        result:
          anyOf:
          - $ref: '#/components/schemas/ClassifyV2Result'
          - type: 'null'
          description: Classify result — available when status is COMPLETED
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
          description: Error message if job failed
        configuration_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Configuration Id
          description: Product configuration ID
        transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Transaction Id
          description: Idempotency key
        parse_job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parse Job Id
          description: Associated parse job ID
      type: object
      required:
      - id
      - file_input
      - project_id
      - user_id
      - status
      - document_input_type
      - configuration
      title: ClassifyV2JobResponse
      description: Response for a classify job.
    ClassifyV2Result:
      properties:
        reasoning:
          type: string
          title: Reasoning
          description: Why the document matched (or didn't match) the returned rule
        confidence:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Confidence
          description: Confidence score between 0.0 and 1.0
        type:
          anyOf:
          - type: string
          - type: 'null'
          title: Type
          description: Matched rule type, or null if no rule matched
      type: object
      required:
      - reasoning
      - confidence
      - type
      title: ClassifyV2Result
      description: Result of classifying a document.
    ClassifyV2Configuration:
      properties:
        rules:
          items:
            $ref: '#/components/schemas/ClassifyV2Rule'
          type: array
          minItems: 1
          title: Rules
          description: Classify rules to evaluate against the document (at least one required)
        mode:
          type: string
          const: FAST
          title: Mode
          description: Classify execution mode
          default: FAST
        parsing_configuration:
          anyOf:
          - $ref: '#/components/schemas/ClassifyV2ParsingConfiguration'
          - type: 'null'
          description: Parsing configuration for controlling which pages are read
      type: object
      required:
      - rules
      title: ClassifyV2Configuration
      description: Configuration for a classify job.
    ClassifyV2JobCreateRequest:
      properties:
        webhook_configurations:
          anyOf:
          - items:
              $ref: '#/components/schemas/WebhookConfiguration'
            type: array
          - type: 'null'
          title: Webhook Configurations
          description: Outbound webhook endpoints to notify on job status changes
        configuration_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Configuration Id
          description: Saved configuration ID
          examples:
          - cfg-11111111-2222-3333-4444-555555555555
        configuration:
          anyOf:
          - $ref: '#/components/schemas/ClassifyV2Configuration'
          - type: 'null'
          description: Inline classify configuration (required if configuration_id is not provided)
        file_input:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: File Input
          description: File ID or parse job ID to classify
          examples:
          - dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: 'Deprecated: use file_input instead'
          deprecated: true
          examples:
          - dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        parse_job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parse Job Id
          description: 'Deprecated: use file_input instead'
          deprecated: true
          examples:
          - pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Transaction Id
          description: Idempotency key scoped to the project
          examples:
          - tx-unique-idempotency-key
      type: object
      title: ClassifyV2JobCreateRequest
      description: Request to create a classify job.
    ClassifyV2ParsingConfiguration:
      properties:
        lang:
          type: string
          title: Lang
          description: ISO 639-1 language code for the document
          default: en
          examples:
          - en
          - es
          - zh
        target_pages:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Pages
          description: Comma-separated page numbers or ranges to process (1-based). Omit to process all pages.
          examples:
          - 1,3,5-7
          - 1-3,8-10
        max_pages:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Pages
          description: Maximum number of pages to process. Omit for no limit.
          examples:
          - 10
      type: object
      title: ClassifyV2ParsingConfiguration
      description: Parsing configuration for classify jobs.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer