# Split ## Create Split Job **post** `/api/v1/split/jobs` Create a document split job. ### Query Parameters - `organization_id: optional string` - `project_id: optional string` ### Cookie Parameters - `session: optional string` ### Body Parameters - `file_input: string` File ID or parse job ID - `configuration: optional object { categories, splitting_strategy }` Split configuration with categories and splitting strategy. - `categories: array of SplitCategory` Categories to split documents into. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy for splitting documents. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `configuration_id: optional string` Saved configuration ID - `transaction_id: optional string` Idempotency key scoped to the project. Reusing a key returns the original job; the new request body is ignored. - `webhook_configuration_ids: optional array of string` IDs of saved webhook configurations to notify for this job. - `webhook_configurations: optional array of object { webhook_events, webhook_headers, webhook_output_format, 2 more }` Outbound webhook endpoints to notify on job status changes - `webhook_events: optional array of "batch.cancelled" or "batch.error" or "batch.pending" or 30 more` Events to subscribe to (e.g. 'parse.success', 'extract.error'). If null, all events are delivered. - `"batch.cancelled"` - `"batch.error"` - `"batch.pending"` - `"batch.running"` - `"batch.success"` - `"classify.cancelled"` - `"classify.error"` - `"classify.partial_success"` - `"classify.pending"` - `"classify.running"` - `"classify.success"` - `"extract.cancelled"` - `"extract.error"` - `"extract.partial_success"` - `"extract.pending"` - `"extract.success"` - `"parse.cancelled"` - `"parse.error"` - `"parse.partial_success"` - `"parse.pending"` - `"parse.running"` - `"parse.success"` - `"sheets.cancelled"` - `"sheets.error"` - `"sheets.partial_success"` - `"sheets.pending"` - `"sheets.success"` - `"split.cancelled"` - `"split.error"` - `"split.pending"` - `"split.processing"` - `"split.success"` - `"unmapped_event"` - `webhook_headers: optional map[string]` Custom HTTP headers sent with each webhook request (e.g. auth tokens) - `webhook_output_format: optional string` Response format sent to the webhook: 'string' (default) or 'json' - `webhook_signing_secret: optional string` Shared signing secret used to sign webhook deliveries. When set, each request includes an HMAC-SHA256 signature of the request body in the 'LC-Signature' header (value 'sha256='). Recompute the HMAC over the raw request body with this secret to verify the delivery is authentic. - `webhook_url: optional string` URL to receive webhook POST notifications ### Returns - `id: string` Unique identifier for the split job. - `categories: array of SplitCategory` Categories used for splitting. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` File ID or parse job ID - `project_id: string` Project this job belongs to. - `status: string` Current job status. Valid values are: pending, processing, completed, failed, cancelled. - `user_id: string` User who created this job. - `configuration_id: optional string` Split configuration ID used for this job. - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if the job failed. - `result: optional SplitResultResponse` Result of a completed split job. - `segments: array of SplitSegmentResponse` List of document segments. - `category: string` Category name this split belongs to. - `confidence_category: string` Categorical confidence level. Valid values are: high, medium, low. - `pages: array of number` 1-indexed page numbers in this split. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy used for splitting. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `transaction_id: optional string` Idempotency key scoped to the project, if one was provided. - `updated_at: optional string` Update datetime ### Example ```http curl https://api.cloud.llamaindex.ai/api/v1/split/jobs \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \ -d '{ "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }' ``` #### Response ```json { "id": "id", "categories": [ { "name": "x", "description": "x" } ], "document_input_type": "file_id", "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "project_id": "project_id", "status": "status", "user_id": "user_id", "configuration_id": "configuration_id", "created_at": "2019-12-27T18:11:19.117Z", "error_message": "error_message", "result": { "segments": [ { "category": "category", "confidence_category": "confidence_category", "pages": [ 0 ] } ] }, "splitting_strategy": { "allow_uncategorized": "forbid", "custom_instructions": "Start a new segment at every signature page.", "min_pages_per_split": 1 }, "transaction_id": "transaction_id", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## List Split Jobs **get** `/api/v1/split/jobs` List document split jobs. ### Query Parameters - `created_at_on_or_after: optional string` Include items created at or after this timestamp (inclusive) - `created_at_on_or_before: optional string` Include items created at or before this timestamp (inclusive) - `job_ids: optional array of string` Filter by specific job IDs - `organization_id: optional string` - `page_size: optional number` - `page_token: optional string` - `project_id: optional string` - `status: optional "cancelled" or "completed" or "failed" or 2 more` Filter by job status (pending, processing, completed, failed, cancelled) - `"cancelled"` - `"completed"` - `"failed"` - `"pending"` - `"processing"` ### Cookie Parameters - `session: optional string` ### Returns - `items: array of object { id, categories, document_input_type, 11 more }` The list of items. - `id: string` Unique identifier for the split job. - `categories: array of SplitCategory` Categories used for splitting. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` File ID or parse job ID - `project_id: string` Project this job belongs to. - `status: string` Current job status. Valid values are: pending, processing, completed, failed, cancelled. - `user_id: string` User who created this job. - `configuration_id: optional string` Split configuration ID used for this job. - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if the job failed. - `result: optional SplitResultResponse` Result of a completed split job. - `segments: array of SplitSegmentResponse` List of document segments. - `category: string` Category name this split belongs to. - `confidence_category: string` Categorical confidence level. Valid values are: high, medium, low. - `pages: array of number` 1-indexed page numbers in this split. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy used for splitting. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `transaction_id: optional string` Idempotency key scoped to the project, if one was provided. - `updated_at: optional string` Update datetime - `next_page_token: optional string` 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: optional number` 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. ### Example ```http curl https://api.cloud.llamaindex.ai/api/v1/split/jobs \ -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" ``` #### Response ```json { "items": [ { "id": "id", "categories": [ { "name": "x", "description": "x" } ], "document_input_type": "file_id", "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "project_id": "project_id", "status": "status", "user_id": "user_id", "configuration_id": "configuration_id", "created_at": "2019-12-27T18:11:19.117Z", "error_message": "error_message", "result": { "segments": [ { "category": "category", "confidence_category": "confidence_category", "pages": [ 0 ] } ] }, "splitting_strategy": { "allow_uncategorized": "forbid", "custom_instructions": "Start a new segment at every signature page.", "min_pages_per_split": 1 }, "transaction_id": "transaction_id", "updated_at": "2019-12-27T18:11:19.117Z" } ], "next_page_token": "next_page_token", "total_size": 0 } ``` ## Get Split Job **get** `/api/v1/split/jobs/{split_job_id}` Get a document split job. ### Path Parameters - `split_job_id: string` ### Query Parameters - `organization_id: optional string` - `project_id: optional string` ### Cookie Parameters - `session: optional string` ### Returns - `id: string` Unique identifier for the split job. - `categories: array of SplitCategory` Categories used for splitting. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` File ID or parse job ID - `project_id: string` Project this job belongs to. - `status: string` Current job status. Valid values are: pending, processing, completed, failed, cancelled. - `user_id: string` User who created this job. - `configuration_id: optional string` Split configuration ID used for this job. - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if the job failed. - `result: optional SplitResultResponse` Result of a completed split job. - `segments: array of SplitSegmentResponse` List of document segments. - `category: string` Category name this split belongs to. - `confidence_category: string` Categorical confidence level. Valid values are: high, medium, low. - `pages: array of number` 1-indexed page numbers in this split. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy used for splitting. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `transaction_id: optional string` Idempotency key scoped to the project, if one was provided. - `updated_at: optional string` Update datetime ### Example ```http curl https://api.cloud.llamaindex.ai/api/v1/split/jobs/$SPLIT_JOB_ID \ -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" ``` #### Response ```json { "id": "id", "categories": [ { "name": "x", "description": "x" } ], "document_input_type": "file_id", "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "project_id": "project_id", "status": "status", "user_id": "user_id", "configuration_id": "configuration_id", "created_at": "2019-12-27T18:11:19.117Z", "error_message": "error_message", "result": { "segments": [ { "category": "category", "confidence_category": "confidence_category", "pages": [ 0 ] } ] }, "splitting_strategy": { "allow_uncategorized": "forbid", "custom_instructions": "Start a new segment at every signature page.", "min_pages_per_split": 1 }, "transaction_id": "transaction_id", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## Delete Split Job **delete** `/api/v1/split/jobs/{split_job_id}` Delete a split job and its results. ### Path Parameters - `split_job_id: string` ### Query Parameters - `organization_id: optional string` - `project_id: optional string` ### Cookie Parameters - `session: optional string` ### Example ```http curl https://api.cloud.llamaindex.ai/api/v1/split/jobs/$SPLIT_JOB_ID \ -X DELETE \ -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" ``` #### Response ```json {} ``` ## Cancel Split Job **post** `/api/v1/split/jobs/{split_job_id}/cancel` Cancel a running split job. Requests cancellation; the job transitions to CANCELLED asynchronously once processing stops. Returns the job, which may still be in its current non-terminal state. Jobs already in a terminal state (COMPLETED, FAILED, CANCELLED) cannot be cancelled. ### Path Parameters - `split_job_id: string` ### Query Parameters - `organization_id: optional string` - `project_id: optional string` ### Cookie Parameters - `session: optional string` ### Returns - `id: string` Unique identifier for the split job. - `categories: array of SplitCategory` Categories used for splitting. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` File ID or parse job ID - `project_id: string` Project this job belongs to. - `status: string` Current job status. Valid values are: pending, processing, completed, failed, cancelled. - `user_id: string` User who created this job. - `configuration_id: optional string` Split configuration ID used for this job. - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if the job failed. - `result: optional SplitResultResponse` Result of a completed split job. - `segments: array of SplitSegmentResponse` List of document segments. - `category: string` Category name this split belongs to. - `confidence_category: string` Categorical confidence level. Valid values are: high, medium, low. - `pages: array of number` 1-indexed page numbers in this split. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy used for splitting. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `transaction_id: optional string` Idempotency key scoped to the project, if one was provided. - `updated_at: optional string` Update datetime ### Example ```http curl https://api.cloud.llamaindex.ai/api/v1/split/jobs/$SPLIT_JOB_ID/cancel \ -X POST \ -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" ``` #### Response ```json { "id": "id", "categories": [ { "name": "x", "description": "x" } ], "document_input_type": "file_id", "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "project_id": "project_id", "status": "status", "user_id": "user_id", "configuration_id": "configuration_id", "created_at": "2019-12-27T18:11:19.117Z", "error_message": "error_message", "result": { "segments": [ { "category": "category", "confidence_category": "confidence_category", "pages": [ 0 ] } ] }, "splitting_strategy": { "allow_uncategorized": "forbid", "custom_instructions": "Start a new segment at every signature page.", "min_pages_per_split": 1 }, "transaction_id": "transaction_id", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## Domain Types ### Split Create Response - `SplitCreateResponse object { id, categories, document_input_type, 11 more }` A split job. - `id: string` Unique identifier for the split job. - `categories: array of SplitCategory` Categories used for splitting. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` File ID or parse job ID - `project_id: string` Project this job belongs to. - `status: string` Current job status. Valid values are: pending, processing, completed, failed, cancelled. - `user_id: string` User who created this job. - `configuration_id: optional string` Split configuration ID used for this job. - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if the job failed. - `result: optional SplitResultResponse` Result of a completed split job. - `segments: array of SplitSegmentResponse` List of document segments. - `category: string` Category name this split belongs to. - `confidence_category: string` Categorical confidence level. Valid values are: high, medium, low. - `pages: array of number` 1-indexed page numbers in this split. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy used for splitting. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `transaction_id: optional string` Idempotency key scoped to the project, if one was provided. - `updated_at: optional string` Update datetime ### Split List Response - `SplitListResponse object { id, categories, document_input_type, 11 more }` A split job. - `id: string` Unique identifier for the split job. - `categories: array of SplitCategory` Categories used for splitting. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` File ID or parse job ID - `project_id: string` Project this job belongs to. - `status: string` Current job status. Valid values are: pending, processing, completed, failed, cancelled. - `user_id: string` User who created this job. - `configuration_id: optional string` Split configuration ID used for this job. - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if the job failed. - `result: optional SplitResultResponse` Result of a completed split job. - `segments: array of SplitSegmentResponse` List of document segments. - `category: string` Category name this split belongs to. - `confidence_category: string` Categorical confidence level. Valid values are: high, medium, low. - `pages: array of number` 1-indexed page numbers in this split. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy used for splitting. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `transaction_id: optional string` Idempotency key scoped to the project, if one was provided. - `updated_at: optional string` Update datetime ### Split Get Response - `SplitGetResponse object { id, categories, document_input_type, 11 more }` A split job. - `id: string` Unique identifier for the split job. - `categories: array of SplitCategory` Categories used for splitting. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` File ID or parse job ID - `project_id: string` Project this job belongs to. - `status: string` Current job status. Valid values are: pending, processing, completed, failed, cancelled. - `user_id: string` User who created this job. - `configuration_id: optional string` Split configuration ID used for this job. - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if the job failed. - `result: optional SplitResultResponse` Result of a completed split job. - `segments: array of SplitSegmentResponse` List of document segments. - `category: string` Category name this split belongs to. - `confidence_category: string` Categorical confidence level. Valid values are: high, medium, low. - `pages: array of number` 1-indexed page numbers in this split. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy used for splitting. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `transaction_id: optional string` Idempotency key scoped to the project, if one was provided. - `updated_at: optional string` Update datetime ### Split Delete Response - `SplitDeleteResponse = unknown` ### Split Cancel Response - `SplitCancelResponse object { id, categories, document_input_type, 11 more }` A split job. - `id: string` Unique identifier for the split job. - `categories: array of SplitCategory` Categories used for splitting. - `name: string` Name of the category. - `description: optional string` Optional description of what content belongs in this category. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` File ID or parse job ID - `project_id: string` Project this job belongs to. - `status: string` Current job status. Valid values are: pending, processing, completed, failed, cancelled. - `user_id: string` User who created this job. - `configuration_id: optional string` Split configuration ID used for this job. - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if the job failed. - `result: optional SplitResultResponse` Result of a completed split job. - `segments: array of SplitSegmentResponse` List of document segments. - `category: string` Category name this split belongs to. - `confidence_category: string` Categorical confidence level. Valid values are: high, medium, low. - `pages: array of number` 1-indexed page numbers in this split. - `splitting_strategy: optional object { allow_uncategorized, custom_instructions, min_pages_per_split }` Strategy used for splitting. - `allow_uncategorized: optional "forbid" or "include" or "omit"` Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results. - `"forbid"` - `"include"` - `"omit"` - `custom_instructions: optional string` Free-form guidance for where segment boundaries are placed. - `min_pages_per_split: optional number` Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging. - `transaction_id: optional string` Idempotency key scoped to the project, if one was provided. - `updated_at: optional string` Update datetime