Caliper provides a REST API alongside its MCP interface. If your application isn’t using MCP, you can call Caliper directly over HTTP.

This guide walks you through making your first REST API call.

What you’ll need

• An HTTP client (curl, Python requests, fetch, etc.)
• A USDC wallet on Base for paid endpoints

Step 1: Check the service

Verify Caliper is running:

curl https://caliper.fit/health

{"ok": true}

Step 2: Detect a file format (free)

The format detection endpoint is free — no payment needed:

curl -X POST https://caliper.fit/tools/caliper_detect_format \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://raw.githubusercontent.com/mikedh/trimesh/main/models/featuretype.STL"
  }'

This returns the detected format and basic file information.

Step 3: Analyze a file with auto-detection

The caliper_auto_stats endpoint auto-detects the file format and returns full metadata:

curl -X POST https://caliper.fit/tools/caliper_auto_stats \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://raw.githubusercontent.com/mikedh/trimesh/main/models/featuretype.STL"
  }'

Handling x402 payment

Paid endpoints return HTTP 402 if payment is required. The 402 response includes:

• A payment address (USDC on Base)
• The required amount
• Instructions for submitting payment proof

After paying, retry the request with the x402 payment proof header. The exact header format follows the x402 protocol specification.

Example flow:

1. POST /tools/caliper_auto_stats → 402 Payment Required
   Response includes: payment address, amount, payment instructions

2. Send USDC payment on Base to the specified address

3. Retry POST /tools/caliper_auto_stats with payment proof header
   → 200 OK with metadata results

Step 4: Use base64 for small files

For files under 200 KB, you can send them inline as base64:

import requests
import base64

with open("model.stl", "rb") as f:
    file_b64 = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://caliper.fit/tools/caliper_auto_stats",
    json={
        "file_b64": file_b64,
        "filename": "model.stl"
    }
)

print(response.json())

When using base64, include the filename field so Caliper can use the extension for format hints.

Step 5: Batch processing

Process up to 10 files in a single request:

curl -X POST https://caliper.fit/tools/caliper_batch_stats \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {"file_url": "https://example.com/model1.stl"},
      {"file_url": "https://example.com/model2.obj"},
      {"file_url": "https://example.com/scene.glb", "filename": "scene.glb"}
    ]
  }'

One payment covers the entire batch.

API endpoints

All tool endpoints accept POST requests with JSON bodies.

Endpoint	Description
POST /tools/caliper_detect_format	Format detection (free)
POST /tools/caliper_auto_stats	Auto-detect format, return metadata
POST /tools/caliper_stl_stats	STL analysis
POST /tools/caliper_obj_stats	OBJ analysis
POST /tools/caliper_ply_stats	PLY analysis
POST /tools/caliper_pcd_stats	PCD analysis
POST /tools/caliper_las_stats	LAS/LAZ analysis
POST /tools/caliper_gltf_stats	glTF/GLB analysis
POST /tools/caliper_batch_stats	Batch analysis (up to 10 files)

Request body

All stats endpoints accept the same request schema:

{
  "file_url": "https://example.com/model.stl",
  "file_b64": "base64-encoded-content",
  "filename": "model.stl"
}

• Provide either file_url or file_b64 (not both)
• filename is optional but helps with format detection when using base64
• File URLs must be HTTP/HTTPS and the file must be under 100 MB
• Base64 content must decode to under 200 KB

Discovery endpoints

Endpoint	Description
GET /health	Service health check
GET /openapi.json	OpenAPI 3.0 specification
GET /docs	Swagger UI (interactive API docs)
GET /mcp/manifest	MCP tool manifest
GET /AGENTS.md	Agent-facing documentation
GET /llms.txt	LLM summary

Next steps

• MCP Getting Started — connect via MCP for agent integration
• API Reference — interactive Swagger UI
• OpenAPI Spec — for code generation