Status & Health API

Monitor API health, check loaded cartridges, and list available models.

Health Check

GET https://api.datablocks.ai/health

Check the health status of the API service and view currently loaded cartridges. This endpoint is useful for monitoring and determining which cartridges are cached in memory.

Response Format

{
  "status": "healthy",
  "device": "cuda",
  "loaded_cartridges": [
    "rajvinder/cartridges/8moujz0r",
    "username/project/run_id"
  ]
}

Response Fields

FieldTypeDescription
statusstringAPI health status ("healthy" or "unhealthy")
devicestringCompute device being used ("cuda" for GPU, "cpu" for CPU)
loaded_cartridgesarrayList of cartridge IDs currently loaded in memory

Example Request

curl https://api.datablocks.ai/health

Python Example

import requests

response = requests.get("https://api.datablocks.ai/health")
data = response.json()

print(f"API Status: {data['status']}")
print(f"Device: {data['device']}")
print(f"Loaded Cartridges: {len(data['loaded_cartridges'])}")
for cartridge in data['loaded_cartridges']:
    print(f"  - {cartridge}")

List Models

GET /api/v1/models

List all currently loaded cartridges as models. This endpoint follows the OpenAI models API format, allowing you to enumerate available cartridges for use in chat completions.

OpenAI Compatibility: This endpoint mirrors the OpenAI /v1/models API structure, making it easy to integrate with existing OpenAI-compatible tooling and SDKs.

Response Format

{
  "object": "list",
  "data": [
    {
      "id": "rajvinder/cartridges/8moujz0r",
      "object": "model",
      "created": 1699999999,
      "owned_by": "cartridges"
    },
    {
      "id": "username/project/run_id",
      "object": "model",
      "created": 1699999999,
      "owned_by": "cartridges"
    }
  ]
}

Response Fields

FieldTypeDescription
objectstringAlways "list" for list responses
dataarrayArray of model objects
data[].idstringUnique cartridge identifier
data[].objectstringAlways "model"
data[].createdintegerUnix timestamp when model was loaded
data[].owned_bystringOrganization that owns the model (always "cartridges")

Example Request

curl /api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Example

import requests

response = requests.get(
    "/api/v1/models",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

data = response.json()
print(f"Available models: {len(data['data'])}")
for model in data['data']:
    print(f"  - {model['id']}")

Preload Cartridges

POST https://api.datablocks.ai/preload

Preload cartridges into memory before making inference requests. This is useful for warming up the cache and ensuring fast first-request latency for specific cartridges.

Performance Tip: Preloading cartridges can significantly reduce latency on the first request. Subsequent requests using the same cartridge will be fast regardless.

Request Body

Send an array of cartridge IDs to preload:

[
  "rajvinder/cartridges/8moujz0r",
  "username/project/run_id"
]

Response Format

{
  "rajvinder/cartridges/8moujz0r": "loaded",
  "username/project/run_id": "loaded"
}

If a cartridge fails to load, the value will be error: [error message] instead of loaded.

Example Request

curl https://api.datablocks.ai/preload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    "rajvinder/cartridges/8moujz0r",
    "username/project/run_id"
  ]'

Python Example

import requests

cartridge_ids = [
    "rajvinder/cartridges/8moujz0r",
    "username/project/run_id"
]

response = requests.post(
    "https://api.datablocks.ai/preload",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY"
    },
    json=cartridge_ids
)

results = response.json()
for cartridge_id, status in results.items():
    print(f"{cartridge_id}: {status}")

Common Use Cases

Health Monitoring

Use the /health endpoint in your monitoring systems to track API uptime and ensure your cartridges remain loaded in memory.

Dynamic Cartridge Discovery

Query the /v1/models endpoint to discover which cartridges are available without hardcoding IDs in your application.

Warm-up Strategy

Use /preload to warm up your most frequently used cartridges during deployment or before high-traffic periods.

Related Documentation