---
title: Getting Started | Developer Documentation
description: Guide on how to use the Split REST API/SDK for automatically segmenting PDFs into logical document sections.
---

## Quickstart

### Upload a document

First, upload a PDF using the [Files API](https://developers.llamaindex.ai/reference/resources/files/).

- [Python](#tab-panel-1155)
- [TypeScript](#tab-panel-1156)
- [Go](#tab-panel-1157)
- [Java](#tab-panel-1158)
- [CLI](#tab-panel-1159)
- [cURL](#tab-panel-1160)

Install the Python SDK if you haven’t already:

Terminal window

```
pip install llama-cloud>=2.8
```

Then upload your file:

```
from llama_cloud import LlamaCloud


client = LlamaCloud(api_key="LLAMA_CLOUD_API_KEY")


file_obj = client.files.create(file="path/to/your/file.pdf", purpose="split")
print(file_obj.id)
```

Install the TypeScript SDK if you haven’t already:

Terminal window

```
npm install @llamaindex/llama-cloud
```

Then upload your file:

```
import fs from "fs";
import { LlamaCloud } from "@llamaindex/llama-cloud";


const client = new LlamaCloud({
  apiKey: "LLAMA_CLOUD_API_KEY",
});


const fileObj = await client.files.create({
  file: fs.createReadStream('path/to/your/file.pdf'),
  purpose: 'split',
});
console.log(fileObj.id);
```

Install the Go SDK if you haven’t already:

Terminal window

```
go get github.com/run-llama/llama-parse-go
```

Then upload your file:

```
package main


import (
  "context"
  "fmt"
  "log"
  "os"


  llamacloud "github.com/run-llama/llama-parse-go"
)


func main() {
  client := llamacloud.NewClient()


  f, err := os.Open("path/to/your/file.pdf")
  if err != nil {
    log.Fatal(err)
  }
  defer f.Close()


  fileObj, err := client.Files.New(context.TODO(), llamacloud.FileNewParams{
    File:    f,
    Purpose: "split",
  })
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(fileObj.ID)
}
```

Install the Java SDK if you haven’t already:

```
implementation("ai.llamaindex:llama-cloud:1.3.0")
```

Then upload your file:

```
import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;
import ai.llamaindex.llamacloud.models.files.FileCreateParams;
import ai.llamaindex.llamacloud.models.files.FileCreateResponse;
import java.nio.file.Paths;


LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();


FileCreateResponse fileObj = client.files().create(
    FileCreateParams.builder()
        .file(Paths.get("path/to/your/file.pdf"))
        .purpose("split")
        .build()
);
System.out.println(fileObj.id());
```

Install the CLI if you haven’t already:

Terminal window

```
go install github.com/run-llama/llama-parse-cli/cmd/llp@latest
```

Then upload your file:

Terminal window

```
llp files create \
  --file path/to/your/file.pdf \
  --purpose split
```

Terminal window

```
curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/files' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -F 'purpose=split' \
  -F 'file=@/path/to/your/file.pdf;type=application/pdf'
```

Save the returned `id` as your `FILE_ID`.

### Create a split job

Create a split job with your file ID and category definitions:

- [Python](#tab-panel-1161)
- [TypeScript](#tab-panel-1162)
- [Go](#tab-panel-1163)
- [Java](#tab-panel-1164)
- [CLI](#tab-panel-1165)
- [cURL](#tab-panel-1166)

```
job = client.beta.split.create(
  document_input={"type": "file_id", "value": file_obj.id},
  configuration={
    "categories": [
      {
        "name": "invoice",
        "description": "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
      },
      {
        "name": "contract",
        "description": "A legal agreement between parties outlining terms, conditions, obligations, and signatures"
      }
    ]
  },
)
```

```
const job = await client.beta.split.create({
  document_input: { type: "file_id", value: fileObj.id },
  configuration: {
    categories: [
      {
        name: "invoice",
        description: "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
      },
      {
        name: "contract",
        description: "A legal agreement between parties outlining terms, conditions, obligations, and signatures"
      }
    ]
  },
});
```

```
job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  DocumentInput: llamacloud.SplitDocumentInputParam{
    Type:  "file_id",
    Value: fileObj.ID,
  },
  Configuration: llamacloud.BetaSplitNewParamsConfiguration{
    Categories: []llamacloud.SplitCategoryParam{
      {
        Name:        "invoice",
        Description: llamacloud.String("A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"),
      },
      {
        Name:        "contract",
        Description: llamacloud.String("A legal agreement between parties outlining terms, conditions, obligations, and signatures"),
      },
    },
  },
})
if err != nil {
  log.Fatal(err)
}
```

```
import ai.llamaindex.llamacloud.models.beta.split.SplitCategory;
import ai.llamaindex.llamacloud.models.beta.split.SplitCreateParams;
import ai.llamaindex.llamacloud.models.beta.split.SplitCreateResponse;
import ai.llamaindex.llamacloud.models.beta.split.SplitDocumentInput;


SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        .documentInput(
            SplitDocumentInput.builder()
                .type("file_id")
                .value(fileObj.id())
                .build())
        .configuration(
            SplitCreateParams.Configuration.builder()
                .addCategory(
                    SplitCategory.builder()
                        .name("invoice")
                        .description("A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms")
                        .build())
                .addCategory(
                    SplitCategory.builder()
                        .name("contract")
                        .description("A legal agreement between parties outlining terms, conditions, obligations, and signatures")
                        .build())
                .build())
        .build()
);
```

Terminal window

```
llp beta:split create \
  --document-input "{type: file_id, value: $FILE_ID}" \
  --configuration '{categories: [{name: invoice, description: "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"}, {name: contract, description: "A legal agreement between parties outlining terms, conditions, obligations, and signatures"}]}'
```

Terminal window

```
curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "document_input": {
      "type": "file_id",
      "value": "YOUR_FILE_ID"
    },
    "configuration": {
      "categories": [
        {
          "name": "invoice",
          "description": "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
        },
        {
          "name": "contract",
          "description": "A legal agreement between parties outlining terms, conditions, obligations, and signatures"
        }
      ]
    }
  }'
```

The response includes the job ID and initial status:

```
{
  "id": "spl-abc123...",
  "status": "pending"
}
```

### Poll for job completion

Jobs are processed asynchronously. Poll the status until it reaches a terminal state — `completed`, `failed`, or `cancelled`:

- [Python](#tab-panel-1167)
- [TypeScript](#tab-panel-1168)
- [Go](#tab-panel-1169)
- [Java](#tab-panel-1170)
- [CLI](#tab-panel-1171)
- [cURL](#tab-panel-1172)

```
completed_job = client.beta.split.wait_for_completion(
    job.id,
    polling_interval=1.0,
    verbose=True,
)
```

```
const completedJob = await client.beta.split.waitForCompletion(
  job.id,
  { pollingInterval: 1.0, verbose: true, }
);
```

```
completedJob, err := client.Beta.Split.Get(context.TODO(), job.ID, llamacloud.BetaSplitGetParams{})
if err != nil {
  log.Fatal(err)
}
for completedJob.Status != "completed" &&
  completedJob.Status != "failed" &&
  completedJob.Status != "cancelled" {
  time.Sleep(2 * time.Second)
  completedJob, err = client.Beta.Split.Get(context.TODO(), job.ID, llamacloud.BetaSplitGetParams{})
  if err != nil {
    log.Fatal(err)
  }
}
```

```
import ai.llamaindex.llamacloud.models.beta.split.SplitGetResponse;


SplitGetResponse completedJob = client.beta().split().get(job.id());
while (!completedJob.status().equals("completed")
    && !completedJob.status().equals("failed")
    && !completedJob.status().equals("cancelled")) {
    Thread.sleep(2000);
    completedJob = client.beta().split().get(job.id());
}
```

Terminal window

```
while true; do
  STATUS=$(llp beta:split get "$JOB_ID" | jq -r '.status')
  case "$STATUS" in
    completed|failed|cancelled) break ;;
  esac
  sleep 2
done


llp beta:split get "$JOB_ID"
```

Terminal window

```
curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs/YOUR_JOB_ID' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"
```

### Get the results

When the job completes successfully, the response includes the segmentation results:

```
{
  "id": "spl-abc123...",
  "status": "completed",
  "result": {
    "segments": [
      {
        "category": "invoice",
        "pages": [1, 2, 3],
        "confidence_category": "high"
      },
      {
        "category": "contract",
        "pages": [4, 5, 6, 7, 8],
        "confidence_category": "high"
      }
    ]
  }
}
```

Each segment contains:

- `category`: The assigned category name
- `pages`: Array of page numbers (1-indexed) belonging to this segment
- `confidence_category`: Confidence level (`high`, `medium`, or `low`)

## Advanced Options

### Uncategorized pages

By default, pages that don’t match any defined category are grouped as `uncategorized` and included in the results. You can control this behavior with the `allow_uncategorized` option in `splitting_strategy`:

| Value                 | Behavior                                                                                       |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `"include"` (default) | Pages that don’t match any category will be grouped as `uncategorized` and included in results |
| `"forbid"`            | All pages must be assigned to a defined category                                               |
| `"omit"`              | Pages that don’t match any category will not appear in results                                 |

For example, to exclude uncategorized pages from results:

- [Python](#tab-panel-1173)
- [TypeScript](#tab-panel-1174)
- [Go](#tab-panel-1175)
- [Java](#tab-panel-1176)
- [CLI](#tab-panel-1177)
- [cURL](#tab-panel-1178)

```
job = client.beta.split.create(
  document_input={"type": "file_id", "value": file_obj.id},
  configuration={
    "categories": [
      {
        "name": "invoice",
        "description": "A commercial document requesting payment for goods or services"
      }
    ],
    "splitting_strategy": {"allow_uncategorized": "omit"}
  },
)
```

```
const job = await client.beta.split.create({
  document_input: { type: "file_id", value: fileObj.id },
  configuration: {
    categories: [
      {
        name: "invoice",
        description: "A commercial document requesting payment for goods or services"
      }
    ],
    splitting_strategy: { allow_uncategorized: "omit" }
  },
});
```

```
job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  DocumentInput: llamacloud.SplitDocumentInputParam{
    Type:  "file_id",
    Value: fileObj.ID,
  },
  Configuration: llamacloud.BetaSplitNewParamsConfiguration{
    Categories: []llamacloud.SplitCategoryParam{
      {
        Name:        "invoice",
        Description: llamacloud.String("A commercial document requesting payment for goods or services"),
      },
    },
    SplittingStrategy: llamacloud.BetaSplitNewParamsConfigurationSplittingStrategy{
      AllowUncategorized: "omit",
    },
  },
})
if err != nil {
  log.Fatal(err)
}
```

```
SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        .documentInput(
            SplitDocumentInput.builder()
                .type("file_id")
                .value(fileObj.id())
                .build())
        .configuration(
            SplitCreateParams.Configuration.builder()
                .addCategory(
                    SplitCategory.builder()
                        .name("invoice")
                        .description("A commercial document requesting payment for goods or services")
                        .build())
                .splittingStrategy(
                    SplitCreateParams.Configuration.SplittingStrategy.builder()
                        .allowUncategorized(
                            SplitCreateParams.Configuration.SplittingStrategy.AllowUncategorized.OMIT)
                        .build())
                .build())
        .build()
);
```

Terminal window

```
llp beta:split create \
  --document-input "{type: file_id, value: $FILE_ID}" \
  --configuration '{categories: [{name: invoice, description: "A commercial document requesting payment for goods or services"}], splitting_strategy: {allow_uncategorized: omit}}'
```

Terminal window

```
curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "document_input": {
      "type": "file_id",
      "value": "YOUR_FILE_ID"
    },
    "configuration": {
      "categories": [
        {
          "name": "invoice",
          "description": "A commercial document requesting payment for goods or services"
        }
      ],
      "splitting_strategy": {
        "allow_uncategorized": "omit"
      }
    }
  }'
```

With `"omit"`, pages that don’t match `invoice` will not appear in the response. To force all pages into defined categories instead, set `allow_uncategorized` to `"forbid"`.

### Using project IDs

If you’re working within a specific project, include the `project_id` query parameter:

- [Python](#tab-panel-1179)
- [TypeScript](#tab-panel-1180)
- [Go](#tab-panel-1181)
- [Java](#tab-panel-1182)
- [CLI](#tab-panel-1183)
- [cURL](#tab-panel-1184)

```
job = client.beta.split.create(
  ...,
  project_id="YOUR_PROJECT_ID"
)
```

```
const job = await client.beta.split.create({
  ...,
  project_id: "YOUR_PROJECT_ID"
});
```

```
job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  // ...
  ProjectID: llamacloud.String("YOUR_PROJECT_ID"),
})
```

```
SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        // ...
        .projectId("YOUR_PROJECT_ID")
        .build()
);
```

Terminal window

```
llp beta:split create \
  --project-id YOUR_PROJECT_ID \
  ...
```

Terminal window

```
curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs?project_id=YOUR_PROJECT_ID' \
  ...
```

## Full API Documentation

This is a subset of the available endpoints to help you get started.

You can see all available endpoints in our [full API documentation](https://developers.llamaindex.ai/reference/resources/beta/subresources/split/).