Classify with a Saved Configuration

In this example, we’ll save a reusable classify configuration and use it across multiple jobs. Instead of passing inline rules every time, you create a configuration once and reference it by ID.

This is useful when you have a standard set of classification rules that you want to reuse across multiple files or integrate into an automated pipeline.

Install

Python

pip install llama-cloud>=1.6

TypeScript

npm install @llamaindex/llama-cloud

Go

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

Java

build.gradle.kts

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

CLI

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

Create a Saved Configuration

Create a classify configuration with your rules. This returns a configuration ID that you can reuse.

The SDKs resolve the project from your API key. The REST call needs an explicit project ID — find it in the URL when viewing a project in the UI.

Python

import os
from llama_cloud import LlamaCloud

client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])

config = client.configurations.create(
    name="Invoice vs Receipt Classifier",
    parameters={
        "product_type": "classify_v2",
        "rules": [
            {
                "type": "invoice",
                "description": "Documents that contain an invoice number, invoice date, bill-to section, and line items with totals.",
            },
            {
                "type": "receipt",
                "description": "Short purchase receipts, typically from POS systems, with merchant, items and total, often a single page.",
            },
        ],
        "mode": "FAST",
    },
)

print(config.id)

TypeScript

import LlamaCloud from "@llamaindex/llama-cloud";

const client = new LlamaCloud({
  apiKey: process.env.LLAMA_CLOUD_API_KEY,
});

const config = await client.configurations.create({
  name: "Invoice vs Receipt Classifier",
  parameters: {
    product_type: "classify_v2",
    rules: [
      {
        type: "invoice",
        description:
          "Documents that contain an invoice number, invoice date, bill-to section, and line items with totals.",
      },
      {
        type: "receipt",
        description:
          "Short purchase receipts, typically from POS systems, with merchant, items and total, often a single page.",
      },
    ],
    mode: "FAST",
  },
});

console.log(config.id);

Go

package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    ctx := context.Background()
    client := llamacloud.NewClient()

    config, err := client.Configurations.New(ctx, llamacloud.ConfigurationNewParams{
        ConfigurationCreate: llamacloud.ConfigurationCreateParam{
            Name: "Invoice vs Receipt Classifier",
            Parameters: llamacloud.ConfigurationCreateParametersUnionParam{
                OfClassifyV2: &llamacloud.ClassifyV2Parameters{
                    Rules: []llamacloud.ClassifyV2ParametersRule{
                        {
                            Type:        "invoice",
                            Description: "Documents that contain an invoice number, invoice date, bill-to section, and line items with totals.",
                        },
                        {
                            Type:        "receipt",
                            Description: "Short purchase receipts, typically from POS systems, with merchant, items and total, often a single page.",
                        },
                    },
                    Mode: llamacloud.ClassifyV2ParametersModeFast,
                },
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(config.ID)
}

Java

import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;
import ai.llamaindex.llamacloud.models.configurations.ClassifyV2Parameters;
import ai.llamaindex.llamacloud.models.configurations.ConfigurationCreate;
import ai.llamaindex.llamacloud.models.configurations.ConfigurationResponse;

public class CreateClassifyConfiguration {
    public static void main(String[] args) throws Exception {
        LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

        ConfigurationResponse config = client.configurations().create(
            ConfigurationCreate.builder()
                .name("Invoice vs Receipt Classifier")
                .parameters(ClassifyV2Parameters.builder()
                    .addRule(ClassifyV2Parameters.Rule.builder()
                        .type("invoice")
                        .description("Documents that contain an invoice number, invoice date, bill-to section, and line items with totals.")
                        .build())
                    .addRule(ClassifyV2Parameters.Rule.builder()
                        .type("receipt")
                        .description("Short purchase receipts, typically from POS systems, with merchant, items and total, often a single page.")
                        .build())
                    .mode(ClassifyV2Parameters.Mode.FAST)
                    .build())
                .build());

        System.out.println(config.id());
    }
}

CLI

export LLAMA_CLOUD_API_KEY="llx-..."

CONFIG_ID=$(llp configurations create \
  --name "Invoice vs Receipt Classifier" \
  --parameters '{product_type: classify_v2, rules: [{type: invoice, description: "Documents that contain an invoice number, invoice date, bill-to section, and line items with totals."}, {type: receipt, description: "Short purchase receipts, typically from POS systems, with merchant, items and total, often a single page."}], mode: FAST}' \
  | jq -r '.id')

echo "$CONFIG_ID"

cURL

curl -X POST 'https://api.cloud.llamaindex.ai/api/v1/beta/configurations?project_id=YOUR_PROJECT_ID' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Invoice vs Receipt Classifier",
    "parameters": {
      "product_type": "classify_v2",
      "rules": [
        {
          "type": "invoice",
          "description": "Documents that contain an invoice number, invoice date, bill-to section, and line items with totals."
        },
        {
          "type": "receipt",
          "description": "Short purchase receipts, typically from POS systems, with merchant, items and total, often a single page."
        }
      ],
      "mode": "FAST"
    }
  }'

The response includes an id field — this is your configuration_id:

{
  "id": "cfg-11111111-2222-3333-4444-555555555555",
  "name": "Invoice vs Receipt Classifier",
  "product_type": "classify_v2",
  ...
}

Classify Using the Configuration ID

Now use the saved configuration to classify files — no need to pass rules inline.

Python

import os
import time
from llama_cloud import LlamaCloud

client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])

# Upload a file
file_obj = client.files.create(file="/path/to/document.pdf", purpose="classify")

# Create a classify job using the saved configuration
job = client.classify.create(
    file_id=file_obj.id,
    configuration_id="cfg-11111111-2222-3333-4444-555555555555",
)

# Poll until complete
status = client.classify.get(job.id)
while status.status == "PENDING":
    time.sleep(2)
    status = client.classify.get(job.id)

# Print result
if status.result:
    print(f"Type: {status.result.type}")
    print(f"Confidence: {status.result.confidence}")
    print(f"Reasoning: {status.result.reasoning}")
else:
    print(f"Classification failed: {status.error_message}")

TypeScript

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

const client = new LlamaCloud({
  apiKey: process.env.LLAMA_CLOUD_API_KEY,
});

// Upload a file
const fileObj = await client.files.create({
  file: fs.createReadStream("/path/to/document.pdf"),
  purpose: "classify",
});

// Create a classify job using the saved configuration
let job = await client.classify.create({
  file_id: fileObj.id,
  configuration_id: "cfg-11111111-2222-3333-4444-555555555555",
});

// Poll until complete
while (job.status === "PENDING") {
  await new Promise((r) => setTimeout(r, 2000));
  job = await client.classify.get(job.id);
}

// Print result
if (job.result) {
  console.log(`Type: ${job.result.type}`);
  console.log(`Confidence: ${job.result.confidence}`);
  console.log(`Reasoning: ${job.result.reasoning}`);
} else {
  console.log(`Classification failed: ${job.error_message}`);
}

Go

package main

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

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

func main() {
    ctx := context.Background()
    client := llamacloud.NewClient()

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

    fileObj, err := client.Files.New(ctx, llamacloud.FileNewParams{
        File:    f,
        Purpose: "classify",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Create a classify job using the saved configuration
    job, err := client.Classify.New(ctx, llamacloud.ClassifyNewParams{
        ClassifyCreateRequest: llamacloud.ClassifyCreateRequestParam{
            FileInput:       llamacloud.String(fileObj.ID),
            ConfigurationID: llamacloud.String("cfg-11111111-2222-3333-4444-555555555555"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Poll until the job reaches a terminal state
    result, err := client.Classify.Get(ctx, job.ID, llamacloud.ClassifyGetParams{})
    if err != nil {
        log.Fatal(err)
    }
    for result.Status == llamacloud.ClassifyGetResponseStatusPending ||
        result.Status == llamacloud.ClassifyGetResponseStatusRunning {
        time.Sleep(2 * time.Second)
        result, err = client.Classify.Get(ctx, job.ID, llamacloud.ClassifyGetParams{})
        if err != nil {
            log.Fatal(err)
        }
    }

    if !result.JSON.Result.Valid() {
        fmt.Printf("Classification failed: %s\n", result.ErrorMessage)
    } else {
        fmt.Printf("Type: %s\n", result.Result.Type)
        fmt.Printf("Confidence: %v\n", result.Result.Confidence)
        fmt.Printf("Reasoning: %s\n", result.Result.Reasoning)
    }
}

Java

import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;
import ai.llamaindex.llamacloud.models.classify.ClassifyCreateRequest;
import ai.llamaindex.llamacloud.models.classify.ClassifyCreateResponse;
import ai.llamaindex.llamacloud.models.classify.ClassifyGetResponse;
import ai.llamaindex.llamacloud.models.files.FileCreateParams;
import ai.llamaindex.llamacloud.models.files.FileCreateResponse;
import java.nio.file.Paths;

public class ClassifyWithSavedConfig {
    public static void main(String[] args) throws Exception {
        LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

        // Upload a file
        FileCreateResponse fileObj = client.files().create(
            FileCreateParams.builder()
                .file(Paths.get("/path/to/document.pdf"))
                .purpose("classify")
                .build());

        // Create a classify job using the saved configuration
        ClassifyCreateResponse job = client.classify().create(
            ClassifyCreateRequest.builder()
                .fileInput(fileObj.id())
                .configurationId("cfg-11111111-2222-3333-4444-555555555555")
                .build());

        // Poll until the job reaches a terminal state
        ClassifyGetResponse result = client.classify().get(job.id());
        while (result.status().equals(ClassifyGetResponse.Status.PENDING)
            || result.status().equals(ClassifyGetResponse.Status.RUNNING)) {
            Thread.sleep(2000);
            result = client.classify().get(job.id());
        }

        if (!result.result().isPresent()) {
            System.out.println("Classification failed: " + result.errorMessage().orElse(""));
        } else {
            System.out.println("Type: " + result.result().get().type().orElse(""));
            System.out.println("Confidence: " + result.result().get().confidence());
            System.out.println("Reasoning: " + result.result().get().reasoning());
        }
    }
}

CLI

export LLAMA_CLOUD_API_KEY="llx-..."

# Upload a file
FILE_ID=$(llp files create --file /path/to/document.pdf --purpose classify | jq -r '.id')

# Create a classify job using the saved configuration
JOB_ID=$(llp classify create \
  --file-input "$FILE_ID" \
  --configuration-id "cfg-11111111-2222-3333-4444-555555555555" \
  | jq -r '.id')

# Poll until the job reaches a terminal state
while true; do
  RESULT=$(llp classify get "$JOB_ID")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  [ "$STATUS" = "PENDING" ] || [ "$STATUS" = "RUNNING" ] || break
  sleep 2
done

echo "$RESULT" | jq -r '.result.type, .result.confidence, .result.reasoning'

Update a Configuration

You can update the rules or mode of an existing configuration at any time:

Python

import os
from llama_cloud import LlamaCloud

client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])

config = client.configurations.update(
    "cfg-11111111-2222-3333-4444-555555555555",
    parameters={
        "product_type": "classify_v2",
        "rules": [
            {
                "type": "invoice",
                "description": "Documents containing invoice numbers, dates, and itemized totals.",
            },
            {
                "type": "receipt",
                "description": "POS receipts with merchant name, items, and total.",
            },
            {
                "type": "purchase_order",
                "description": "Purchase orders with PO numbers, vendor details, and requested items.",
            },
        ],
        "mode": "FAST",
    },
)

print(config.version)

TypeScript

import LlamaCloud from "@llamaindex/llama-cloud";

const client = new LlamaCloud({
  apiKey: process.env.LLAMA_CLOUD_API_KEY,
});

const config = await client.configurations.update(
  "cfg-11111111-2222-3333-4444-555555555555",
  {
    parameters: {
      product_type: "classify_v2",
      rules: [
        {
          type: "invoice",
          description:
            "Documents containing invoice numbers, dates, and itemized totals.",
        },
        {
          type: "receipt",
          description: "POS receipts with merchant name, items, and total.",
        },
        {
          type: "purchase_order",
          description:
            "Purchase orders with PO numbers, vendor details, and requested items.",
        },
      ],
      mode: "FAST",
    },
  },
);

console.log(config.version);

Go

package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    ctx := context.Background()
    client := llamacloud.NewClient()

    config, err := client.Configurations.Update(ctx, "cfg-11111111-2222-3333-4444-555555555555", llamacloud.ConfigurationUpdateParams{
        Parameters: llamacloud.ConfigurationUpdateParamsParametersUnion{
            OfClassifyV2: &llamacloud.ClassifyV2Parameters{
                Rules: []llamacloud.ClassifyV2ParametersRule{
                    {
                        Type:        "invoice",
                        Description: "Documents containing invoice numbers, dates, and itemized totals.",
                    },
                    {
                        Type:        "receipt",
                        Description: "POS receipts with merchant name, items, and total.",
                    },
                    {
                        Type:        "purchase_order",
                        Description: "Purchase orders with PO numbers, vendor details, and requested items.",
                    },
                },
                Mode: llamacloud.ClassifyV2ParametersModeFast,
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(config.Version)
}

Java

import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;
import ai.llamaindex.llamacloud.models.configurations.ClassifyV2Parameters;
import ai.llamaindex.llamacloud.models.configurations.ConfigurationResponse;
import ai.llamaindex.llamacloud.models.configurations.ConfigurationUpdateParams;

public class UpdateClassifyConfiguration {
    public static void main(String[] args) throws Exception {
        LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

        ConfigurationResponse config = client.configurations().update(
            ConfigurationUpdateParams.builder()
                .configId("cfg-11111111-2222-3333-4444-555555555555")
                .parameters(ClassifyV2Parameters.builder()
                    .addRule(ClassifyV2Parameters.Rule.builder()
                        .type("invoice")
                        .description("Documents containing invoice numbers, dates, and itemized totals.")
                        .build())
                    .addRule(ClassifyV2Parameters.Rule.builder()
                        .type("receipt")
                        .description("POS receipts with merchant name, items, and total.")
                        .build())
                    .addRule(ClassifyV2Parameters.Rule.builder()
                        .type("purchase_order")
                        .description("Purchase orders with PO numbers, vendor details, and requested items.")
                        .build())
                    .mode(ClassifyV2Parameters.Mode.FAST)
                    .build())
                .build());

        System.out.println(config.version());
    }
}

CLI

export LLAMA_CLOUD_API_KEY="llx-..."

llp configurations update \
  --config-id "cfg-11111111-2222-3333-4444-555555555555" \
  --parameters '{product_type: classify_v2, rules: [{type: invoice, description: "Documents containing invoice numbers, dates, and itemized totals."}, {type: receipt, description: "POS receipts with merchant name, items, and total."}, {type: purchase_order, description: "Purchase orders with PO numbers, vendor details, and requested items."}], mode: FAST}' \
  | jq -r '.version'

cURL

curl -X PUT 'https://api.cloud.llamaindex.ai/api/v1/beta/configurations/cfg-11111111-2222-3333-4444-555555555555?project_id=YOUR_PROJECT_ID' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": {
      "product_type": "classify_v2",
      "rules": [
        {
          "type": "invoice",
          "description": "Documents containing invoice numbers, dates, and itemized totals."
        },
        {
          "type": "receipt",
          "description": "POS receipts with merchant name, items, and total."
        },
        {
          "type": "purchase_order",
          "description": "Purchase orders with PO numbers, vendor details, and requested items."
        }
      ],
      "mode": "FAST"
    }
  }'

Future classify jobs using this configuration_id will automatically use the updated rules.

Notes

• Use configuration_id instead of inline configuration when you want to reuse the same rules across multiple jobs.
• Configurations are scoped to your project — they are not shared across projects.
• You can also create and manage configurations from the LlamaCloud UI.