API Reference

REST API reference for the ZenRay backend. Query runs, steps, and candidates programmatically.

Base URL: https://api.xray.dev

Health & Status

GET /health Check if the backend is running

Returns the health status and current timestamp.

Request

curl https://api.xray.dev/health

Response

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Runs

GET /runs List all pipeline runs

Returns a paginated list of pipeline runs with optional filters.

Query Parameters

Parameter	Type	Description
`pipeline_name`	string	Filter by pipeline name
`status`	string	SUCCESS, FAILED, RUNNING
`limit`	number	Max results (default 100)
`offset`	number	Pagination offset

Request

curl "https://api.xray.dev/runs?limit=10"

Response

[
  {
    "run_id": "run-abc123",
    "pipeline_name": "search",
    "version": "v1.0",
    "status": "SUCCESS",
    "started_at": "2024-01-15T10:30:00.000Z",
    "ended_at": "2024-01-15T10:30:01.234Z",
    "duration_ms": 1234,
    "tags": { "user_id": "123" },
    "step_count": 5
  }
]

GET /runs/:runId Get run details with steps

Returns detailed information about a specific run.

Request

curl https://api.xray.dev/runs/run-abc123

Response

{
  "run": {
    "run_id": "run-abc123",
    "pipeline_name": "search",
    "status": "SUCCESS"
  },
  "steps": [
    {
      "step_id": "step-xyz789",
      "kind": "FILTER",
      "name": "filter_by_score",
      "input_count": 100,
      "output_count": 45
    }
  ]
}

GET /runs/:runId/trace Trace a candidate through the pipeline

Search for a specific candidate and trace its journey through every step.

Query Parameters

Parameter	Type	Description
`q`	string	Search term to find in candidate data

Request

curl "https://api.xray.dev/runs/run-abc123/trace?q=product-456"

Response

{
  "query": "product-456",
  "run_id": "run-abc123",
  "found": true,
  "journey": [
    {
      "step_id": "step-1",
      "step_name": "retrieve",
      "status": "kept"
    },
    {
      "step_id": "step-2",
      "step_name": "filter_by_score",
      "status": "dropped",
      "drop_reason": "low_score"
    }
  ]
}

Steps

GET /steps/:stepId Get step details with candidates

Returns detailed information about a step including candidates, artifacts, and metrics.

Request

curl https://api.xray.dev/steps/step-xyz789

Response

{
  "step": {
    "step_id": "step-xyz789",
    "kind": "FILTER",
    "input_count": 100,
    "output_count": 45
  },
  "candidate_set": {
    "reason_histogram": {
      "low_score": 40,
      "duplicate": 10
    }
  },
  "artifacts": [
    { "type": "prompt", "content": "..." }
  ]
}

Compare

GET /compare Compare two runs side-by-side

Compare two pipeline runs to identify differences.

Query Parameters

Parameter	Type	Description
`run_a`	string	First run ID
`run_b`	string	Second run ID

Request

curl "https://api.xray.dev/compare?run_a=run-abc&run_b=run-xyz"

Response

{
  "run_a": { ... },
  "run_b": { ... },
  "step_comparisons": [
    {
      "step_name": "filter",
      "a_output": 45,
      "b_output": 38,
      "delta": -7
    }
  ]
}

Ingest

POST /ingest Ingest run and step data

Ingest data from the SDK. Called automatically.

Request Body

{
  "schema_version": "1.0",
  "runs": [ ... ],
  "steps": [ ... ]
}

Request

curl -X POST https://api.xray.dev/ingest -H "Content-Type: application/json" -d @payload.json

Response

{
  "accepted_runs": 1,
  "accepted_steps": 5,
  "queued": true,
  "errors": []
}