LlamaParse Sheets API
The Sheets API from LlamaParse — 3 operation(s) for sheets.
OpenAPI Specification
openapi: 3.0.3
info:
title: Llama Platform Agent Data Sheets API
version: 0.1.0
tags:
- name: Sheets
paths:
/api/v1/beta/sheets/jobs:
post:
tags:
- Sheets
summary: Create Spreadsheet Job
description: 'Create a spreadsheet parsing job.
Provide at most one of `configuration` (an inline parsing configuration) or `configuration_id` (a saved configuration preset). If neither is provided, a default configuration is used. Optionally include `webhook_configurations` to receive `sheets.*` status notifications.
Experimental: not production-ready and subject to change.'
operationId: create_spreadsheet_job_api_v1_beta_sheets_jobs_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/SpreadsheetJobCreate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SpreadsheetJob'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Sheets
summary: List Spreadsheet Jobs
description: 'List spreadsheet parsing jobs. Experimental: not production-ready and subject to change.'
operationId: list_spreadsheet_jobs_api_v1_beta_sheets_jobs_get
security:
- HTTPBearer: []
parameters:
- name: include_results
in: query
required: false
schema:
type: boolean
default: false
title: Include Results
- name: status
in: query
required: false
schema:
anyOf:
- enum:
- PENDING
- SUCCESS
- ERROR
- PARTIAL_SUCCESS
- CANCELLED
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: configuration_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by saved configuration ID
title: Configuration Id
description: Filter by saved configuration 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: page_size
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Page Size
- name: page_token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Page Token
- 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/PaginatedResponse_SpreadsheetJob_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/beta/sheets/jobs/{spreadsheet_job_id}:
get:
tags:
- Sheets
summary: Get Spreadsheet Job
description: 'Get a spreadsheet parsing job. When `include_results=True` (default), embeds extracted regions and results if complete, skipping the separate `/results` call. Experimental: not production-ready and subject to change.'
operationId: get_spreadsheet_job_api_v1_beta_sheets_jobs__spreadsheet_job_id__get
security:
- HTTPBearer: []
parameters:
- name: spreadsheet_job_id
in: path
required: true
schema:
type: string
title: Spreadsheet Job Id
- name: include_results
in: query
required: false
schema:
type: boolean
default: true
title: Include Results
- name: expand
in: query
required: false
schema:
type: array
items:
type: string
description: 'Optional fields to populate on the response. Valid values: metadata_state_transitions.'
title: Expand
description: 'Optional fields to populate on the response. Valid values: metadata_state_transitions.'
- 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/SpreadsheetJob'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Sheets
summary: Delete Spreadsheet Job
description: 'Delete a spreadsheet parsing job and its associated data. Experimental: not production-ready and subject to change.'
operationId: delete_spreadsheet_job_api_v1_beta_sheets_jobs__spreadsheet_job_id__delete
security:
- HTTPBearer: []
parameters:
- name: spreadsheet_job_id
in: path
required: true
schema:
type: string
title: Spreadsheet 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: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/beta/sheets/jobs/{spreadsheet_job_id}/regions/{region_id}/result/{region_type}:
get:
tags:
- Sheets
summary: Get Result Region
description: 'Generate a presigned URL to download a specific extracted region. Experimental: not production-ready and subject to change.'
operationId: get_result_region_api_v1_beta_sheets_jobs__spreadsheet_job_id__regions__region_id__result__region_type__get
security:
- HTTPBearer: []
parameters:
- name: spreadsheet_job_id
in: path
required: true
schema:
type: string
title: Spreadsheet Job Id
- name: region_id
in: path
required: true
schema:
type: string
title: Region Id
- name: region_type
in: path
required: true
schema:
$ref: '#/components/schemas/SpreadsheetResultType'
- name: expires_at_seconds
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Expires At Seconds
- 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/PresignedUrl'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
SpreadsheetJob:
properties:
id:
type: string
title: Id
description: The ID of the job
user_id:
type: string
title: User Id
description: The ID of the user
project_id:
type: string
format: uuid
title: Project Id
description: The ID of the project
configuration:
$ref: '#/components/schemas/SpreadsheetParsingConfig'
description: Configuration applied to the parsing job (inline or resolved from a saved preset).
config:
anyOf:
- $ref: '#/components/schemas/SpreadsheetParsingConfig'
- type: 'null'
description: 'Deprecated: use `configuration` instead.'
deprecated: true
status:
type: string
enum:
- PENDING
- SUCCESS
- ERROR
- PARTIAL_SUCCESS
- CANCELLED
title: Status
description: The status of the parsing job
parameters:
$ref: '#/components/schemas/SpreadsheetJobParameters'
description: Job-time parameters such as webhook configurations.
configuration_id:
anyOf:
- type: string
- type: 'null'
title: Configuration Id
description: The saved product configuration ID used at create time, if any.
metadata_state_transitions:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata State Transitions
description: Per-status entry timestamps. Returned only when requested via `?expand=metadata_state_transitions`.
created_at:
type: string
title: Created At
description: When the job was created
updated_at:
type: string
title: Updated At
description: When the job was last updated
success:
anyOf:
- type: boolean
- type: 'null'
title: Success
description: Whether the job completed successfully
regions:
items:
$ref: '#/components/schemas/ExtractedRegionSummary'
type: array
title: Regions
description: All extracted regions (populated when job is complete)
worksheet_metadata:
items:
$ref: '#/components/schemas/WorksheetMetadata'
type: array
title: Worksheet Metadata
description: Metadata for each processed worksheet (populated when job is complete)
errors:
items:
type: string
type: array
title: Errors
description: Any errors encountered
file_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: File Id
description: The ID of the input file
file:
anyOf:
- $ref: '#/components/schemas/File'
- type: 'null'
description: '[DEPRECATED] The file that was parsed. Use file_id instead.'
deprecated: true
type: object
required:
- id
- user_id
- project_id
- configuration
- status
- created_at
- updated_at
- file_id
title: SpreadsheetJob
description: A spreadsheet parsing job.
SpreadsheetParsingConfig:
properties:
sheet_names:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Sheet Names
description: The names of the sheets to extract regions from. If empty, all sheets will be processed.
include_hidden_cells:
type: boolean
title: Include Hidden Cells
description: Whether to include hidden cells when extracting regions from the spreadsheet.
default: true
extraction_range:
anyOf:
- type: string
- type: 'null'
title: Extraction Range
description: A1 notation of the range to extract a single region from. If None, the entire sheet is used.
generate_additional_metadata:
type: boolean
title: Generate Additional Metadata
description: Whether to generate additional metadata (title, description) for each extracted region.
default: true
use_experimental_processing:
type: boolean
title: Use Experimental Processing
description: Enables experimental processing. Accuracy may be impacted.
default: false
flatten_hierarchical_tables:
type: boolean
title: Flatten Hierarchical Tables
description: Return a flattened dataframe when a detected table is recognized as hierarchical.
default: false
table_merge_sensitivity:
type: string
enum:
- strong
- weak
title: Table Merge Sensitivity
description: Influences how likely similar-looking regions are merged into a single table. Useful for spreadsheets that either have sparse tables (strong merging) or many distinct tables close together (weak merging).
default: strong
specialization:
anyOf:
- type: string
- type: 'null'
title: Specialization
description: 'Optional specialization mode for domain-specific extraction. Supported values: ''financial-standard'', ''financial-enhanced'', ''financial-precise''. Default None uses the general-purpose pipeline.'
type: object
title: SpreadsheetParsingConfig
description: Configuration for spreadsheet parsing and region extraction
File:
properties:
id:
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
name:
type: string
maxLength: 3000
minLength: 1
title: Name
external_file_id:
anyOf:
- type: string
- type: 'null'
title: External File Id
description: The ID of the file in the external system
file_size:
anyOf:
- type: integer
minimum: 0.0
- type: 'null'
title: File Size
description: Size of the file in bytes
file_type:
anyOf:
- type: string
maxLength: 3000
minLength: 1
- type: 'null'
title: File Type
description: File type (e.g. pdf, docx, etc.)
project_id:
type: string
format: uuid
title: Project Id
description: The ID of the project that the file belongs to
last_modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Modified At
description: The last modified time of the file
resource_info:
anyOf:
- additionalProperties:
anyOf:
- additionalProperties: true
type: object
- items: {}
type: array
- type: string
- type: integer
- type: number
- type: boolean
- type: 'null'
type: object
- type: 'null'
title: Resource Info
description: Resource information for the file
permission_info:
anyOf:
- additionalProperties:
anyOf:
- additionalProperties: true
type: object
- items: {}
type: array
- type: string
- type: integer
- type: number
- type: boolean
- type: 'null'
type: object
- type: 'null'
title: Permission Info
description: Permission information for the file
data_source_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Data Source Id
description: The ID of the data source that the file belongs to
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
description: The expiration date for the file. Files past this date can be deleted.
purpose:
anyOf:
- type: string
- type: 'null'
title: Purpose
description: The intended purpose of the file (e.g., 'user_data', 'parse', 'extract', 'split', 'classify')
type: object
required:
- id
- name
- project_id
title: File
description: Schema for a file.
SpreadsheetJobParameters:
properties:
webhook_configurations:
anyOf:
- items:
$ref: '#/components/schemas/WebhookConfiguration'
type: array
- type: 'null'
title: Webhook Configurations
description: Webhook configurations for job status notifications.
type: object
title: SpreadsheetJobParameters
description: Job-time parameters returned on a spreadsheet job response.
PresignedUrl:
properties:
url:
type: string
minLength: 1
format: uri
title: Url
description: A presigned URL for IO operations against a private file
expires_at:
type: string
format: date-time
title: Expires At
description: The time at which the presigned URL expires
form_fields:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Form Fields
description: Form fields for a presigned POST request
type: object
required:
- url
- expires_at
title: PresignedUrl
description: Schema for a presigned URL.
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.
SpreadsheetJobCreate:
properties:
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/SpreadsheetParsingConfig'
- type: 'null'
description: Inline configuration
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
config:
anyOf:
- $ref: '#/components/schemas/SpreadsheetParsingConfig'
- type: 'null'
description: 'Deprecated: use `configuration` instead.'
deprecated: true
file_id:
type: string
format: uuid
title: File Id
description: The ID of the file to parse
type: object
required:
- file_id
title: SpreadsheetJobCreate
description: 'Request to create a spreadsheet parsing job.
Provide at most one of `configuration` (inline) or `configuration_id`
(saved preset). If neither is provided, a default inline configuration is
used.'
PaginatedResponse_SpreadsheetJob_:
properties:
items:
items:
$ref: '#/components/schemas/SpreadsheetJob'
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: PaginatedResponse[SpreadsheetJob]
SpreadsheetResultType:
type: string
enum:
- table
- extra
- cell_metadata
title: SpreadsheetResultType
ExtractedRegionSummary:
properties:
region_id:
type: string
title: Region Id
description: Unique identifier for this region within the file
sheet_name:
type: string
title: Sheet Name
description: Worksheet name where region was found
location:
type: string
title: Location
description: Location of the region in the spreadsheet
region_type:
type: string
title: Region Type
description: Type of the extracted region
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: Generated title for the region
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Generated description for the region
type: object
required:
- sheet_name
- location
- region_type
title: ExtractedRegionSummary
description: A summary of a single extracted region from a spreadsheet
WorksheetMetadata:
properties:
sheet_name:
type: string
title: Sheet Name
description: Name of the worksheet
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: Generated title for the worksheet
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Generated description of the worksheet
type: object
required:
- sheet_name
title: WorksheetMetadata
description: Metadata about a worksheet in a spreadsheet
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer