Skip to content
XeroML XeroML

Public API

XeroML exposes a RESTful public API that gives you full read and write access to traces, observations, scores, prompts, datasets, and more. Any operation available in the UI is also available via the API.

Base URL

https://cloud.xeroml.com/api/public/v2

For self-hosted deployments, replace with your instance URL.

Authentication

Use HTTP Basic auth with your project API keys:

Terminal window
# Public key as username, secret key as password
curl -u "pk-xm-...:sk-xm-..." \
  "https://cloud.xeroml.com/api/public/v2/traces"

API keys are available in Project Settings → API Keys.

Key Endpoints

Traces

Terminal window
# List traces with filters
GET /api/public/v2/traces?page=1&limit=50&userId=user-123&tags=feature:chat


# Get a specific trace
GET /api/public/v2/traces/{traceId}


# Create a trace (for manual ingestion)
POST /api/public/v2/traces

Scores

Terminal window
# Create a score for a trace
POST /api/public/v2/scores
{
  "traceId": "trace_abc123",
  "name": "accuracy",
  "value": 0.92,
  "dataType": "NUMERIC"
}


# List scores for a trace
GET /api/public/v2/scores?traceId=trace_abc123


# Delete a score
DELETE /api/public/v2/scores/{scoreId}

Prompts

Terminal window
# List all prompts
GET /api/public/v2/prompts


# Get a specific prompt version
GET /api/public/v2/prompts/{promptName}?label=production


# Create or update a prompt
POST /api/public/v2/prompts


# Update a prompt label
PATCH /api/public/v2/prompts/{promptName}

Datasets

Terminal window
# List datasets
GET /api/public/v2/datasets


# Get dataset items
GET /api/public/v2/datasets/{datasetName}/items


# Add an item to a dataset
POST /api/public/v2/datasets/{datasetName}/items

Metrics

Terminal window
# Get aggregated metrics
GET /api/public/v2/metrics/daily?startDate=2025-01-01&endDate=2025-01-31&groupBy=userId

Pagination

All list endpoints support pagination:

Terminal window
GET /api/public/v2/traces?page=2&limit=100

Response includes meta.total and meta.page for cursor navigation.

Rate Limits

PlanRequests/minute
Free100
Pro1,000
EnterpriseCustom

Rate limit headers are included in every response:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

OpenAPI Spec

The full API specification (OpenAPI 3.0) is available at:

https://cloud.xeroml.com/api/public/v2/openapi.json

Import it into Postman, Insomnia, or any OpenAPI-compatible client for interactive exploration.