# Split

## Create Split Job

`$ llp split create`

**post** `/api/v1/split/jobs`

Create a document split job.

### Parameters

- `--file-input: string`

  Body param: File ID or parse job ID

- `--organization-id: optional string`

  Query param

- `--project-id: optional string`

  Query param

- `--configuration: optional object { categories, splitting_strategy }`

  Body param: Split configuration with categories and splitting strategy.

- `--configuration-id: optional string`

  Body param: Saved configuration ID

- `--transaction-id: optional string`

  Body param: Idempotency key scoped to the project. Reusing a key returns the original job; the new request body is ignored.

- `--webhook-configuration-id: optional array of string`

  Body param: IDs of saved webhook configurations to notify for this job.

- `--webhook-configuration: optional array of object { webhook_events, webhook_headers, webhook_output_format, 2 more }`

  Body param: Outbound webhook endpoints to notify on job status changes

### Returns

- `SplitNewResponse: 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 object { segments }`

    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

```cli
llp split create \
  --api-key 'My API Key' \
  --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

`$ llp split list`

**get** `/api/v1/split/jobs`

List document split jobs.

### 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-id: 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)

### Returns

- `SplitJobQueryResponse: object { items, next_page_token, total_size }`

  Paginated list of split jobs.

  - `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 object { segments }`

      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

```cli
llp split list \
  --api-key 'My 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

`$ llp split get`

**get** `/api/v1/split/jobs/{split_job_id}`

Get a document split job.

### Parameters

- `--split-job-id: string`

- `--organization-id: optional string`

- `--project-id: optional string`

### Returns

- `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 object { segments }`

    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

```cli
llp split get \
  --api-key 'My API Key' \
  --split-job-id split_job_id
```

#### 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

`$ llp split delete`

**delete** `/api/v1/split/jobs/{split_job_id}`

Delete a split job and its results.

### Parameters

- `--split-job-id: string`

- `--organization-id: optional string`

- `--project-id: optional string`

### Returns

- `SplitDeleteResponse: unknown`

### Example

```cli
llp split delete \
  --api-key 'My API Key' \
  --split-job-id split_job_id
```

#### Response

```json
{}
```

## Cancel Split Job

`$ llp split cancel`

**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.

### Parameters

- `--split-job-id: string`

- `--organization-id: optional string`

- `--project-id: optional string`

### Returns

- `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 object { segments }`

    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

```cli
llp split cancel \
  --api-key 'My API Key' \
  --split-job-id split_job_id
```

#### 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"
}
```