Datablocks API

Train, manage, and deploy datablocks for efficient long-context inference.

Overview

The Datablocks API allows you to create, train, and manage pre-computed context blocks. Datablocks dramatically reduce inference costs and latency by pre-processing large amounts of context into compact KV cache representations.

Training Datablocks

POST /api/v1/datablocks/train

Train a new datablock from your uploaded files. First, upload your flat file data (CSV, JSON, TXT, PDF, etc.) using the Files API, then reference the file ID in your training request. The training process compresses your context into a highly efficient KV cache format.

Note: Files are stored in per-user storage and can only be accessed with your API key. You can reference multiple files by using the training_files array parameter.

Managing Datablocks

List Datablocks

GET /v1/datablocks

Get Datablock

GET /v1/datablocks/{datablock_id}

Delete Datablock

DELETE /v1/datablocks/{datablock_id}

Best Practices

Optimize Document Size

For best results, train datablocks with 10K-100K tokens of context per document.

Reuse Datablocks

Once trained, datablocks can be reused across millions of queries with zero additional cost.

import requests

# Step 1: Upload your data file
with open("my_data.txt", "rb") as f:
    file_response = requests.post(
        "/api/v1/files",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": f},
        data={"purpose": "cartridge-training"}
    )
file_id = file_response.json()["id"]

# Step 2: Train a datablock using the uploaded file
response = requests.post(
    "/api/v1/datablocks/train",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY"
    },
    json={
        "training_file": file_id,
        "model": "qwen",
        "datablock_name": "my-datablock"
    }
)

data = response.json()
print(f"Datablock ID: {data['datablock_id']}")