API Reference

Kinetic AI OpenAI-Compatible API

The Kinetic AI API exposes EqLM and the council of Qwen2.5 specialists. All endpoints support the OpenAI-compatible chat completion format, plus optional Kinetic controls (rationality λ, solver budget, magnet strength). Auth required for all endpoints.

Authentication

Include an Authorization header with a bearer token:

Authorization: Bearer GATEWAY_SECRET

# Export as env var for curl:
export KINETIC_AUTH="Bearer $(echo -n $GATEWAY_SECRET)"
curl -H "$KINETIC_AUTH" https://kinetic.kinetic-ai.workers.dev/api/generate

Core Endpoints

/api/eqlm/generate — Single-Model Generation

Generate text with EqLM at a specified anytime depth. The model performs adaptive fixed-point solving up to the requested budget.

GET Parameters:
  • prompt (string, required): Input text to generate from.
  • depth (int, default 12): Solver budget (1–12 iterations). Controls quality/speed tradeoff.
  • max_new_tokens (int, default 48, max 48): Maximum tokens to generate.
  • device (string, default "auto"): "auto" (GPU if available), "cpu" (CPU-only).
Response:
{
  "status": "ok" | "model_not_loaded" | "error",
  "text": "generated text",
  "tokens_generated": 12,
  "depth_used": 12,
  "mean_solver_iters": 11.3,
  "error": null | "error message"
}
Example:
curl -H "$KINETIC_AUTH" \
  "https://kinetic.kinetic-ai.workers.dev/api/eqlm/generate?prompt=Hello%20world&depth=8&max_new_tokens=32"

# Response:
{
  "status": "ok",
  "text": "This is a test response.",
  "tokens_generated": 4,
  "depth_used": 8,
  "mean_solver_iters": 8.0
}

/api/eqlm/results — Architecture Results

Get EqLM single-model paradigm results (F24: parity at matched params). Includes arm configurations, BLiMP accuracy, loss, config hashes, and pre-registration status.

GET (no parameters)
curl -H "$KINETIC_AUTH" "https://kinetic.kinetic-ai.workers.dev/api/eqlm/results"

# Response includes:
{
  "paradigm_claim": "EqLM: depth, training, decoding are equilibrium computations",
  "finding": "F24: parity ratio 0.991 at 121M",
  "arms": [
    {
      "seed": 42,
      "arm": "B1",
      "kind": "anytime",
      "num_params": 120696016,
      "blimp_accuracy": 0.662,
      "final_loss": 2.800,
      "config_hash": "..."
    }
  ]
}

/health — System Health Check

Check API availability and GPU status (no auth required).

GET (no parameters)
curl "https://kinetic.kinetic-ai.workers.dev/health"

# Response:
{
  "status": "ok",
  "version": "0.1.0-phase3",
  "gpu_available": true
}

Research Endpoints (Admin Auth)

These endpoints are available to authenticated users and expose research data.

/api/leaderboard — Benchmark Ladder

Get the full benchmark ladder (Qwen2.5 variants, MMLU, ARC-Challenge, HellaSwag, GSM8K). All results trace to config hashes, seeds, and lm-eval invocations.

curl -H "$KINETIC_AUTH" "https://kinetic.kinetic-ai.workers.dev/api/leaderboard"

# Returns model scores across benchmarks with full provenance

/api/auction/traces — Token Auction Traces

Real bid/winner/payment traces from the token auction (F22). Per-token specialist selection at scoring time. Query by seed or get a sample.

curl -H "$KINETIC_AUTH" "https://kinetic.kinetic-ai.workers.dev/api/auction/traces"
curl -H "$KINETIC_AUTH" "https://kinetic.kinetic-ai.workers.dev/api/auction/traces/seed42"

# Returns auction traces with bids, winners, payments per token

/api/solve — Equilibrium Lab Solver

Solve matrix games with MMD (Magnetic Mirror Descent) or GDA (Gradient Descent Ascent). Returns trajectory and final strategies.

curl -X POST -H "$KINETIC_AUTH" -H "Content-Type: application/json" \
  -d '{
    "game": "matching_pennies",
    "method": "mmd_fixed",
    "lr": 0.1,
    "tau": 0.1,
    "steps": 100,
    "seed": 42
  }' "https://kinetic.kinetic-ai.workers.dev/api/solve"

# Returns trajectory with strategies and NashConv per step

/api/qre_path — QRE Homotopy Path

Trace the quantal response equilibrium (QRE) path as rationality λ varies. Smooth interpolation from uniform to Nash.

curl -X POST -H "$KINETIC_AUTH" -H "Content-Type: application/json" \
  -d '{
    "game": "rps",
    "lambda_min": 0.1,
    "lambda_max": 10.0,
    "n_points": 20
  }' "https://kinetic.kinetic-ai.workers.dev/api/qre_path"

# Returns path of (λ, strategy_1, strategy_2) pairs

Error Handling

All endpoints return standard HTTP status codes and JSON error responses:

  • 200 OK: Request succeeded.
  • 400 Bad Request: Invalid parameters.
  • 401 Unauthorized: Missing or invalid Authorization header.
  • 422 Unprocessable Entity: Invalid game or method name.
  • 500 Internal Server Error: Server error (check /health).

Error responses include a detail field:

{"detail": "Unknown game: invalid_game"}

Rate Limits & Quotas

  • Generation endpoints: GPU bandwidth limited (see /health for availability).
  • Solver endpoints: CPU-based, no strict limit; large steps (>5000) clamped.
  • Batch requests: One job at a time (GPU lock in research/memory/state.json).

Quick Start

#!/bin/bash
export KINETIC_AUTH="Bearer $GATEWAY_SECRET"

# Test API
curl "$API_BASE/health"

# Generate text
curl -H "$KINETIC_AUTH" \
  "https://kinetic.kinetic-ai.workers.dev/api/eqlm/generate?prompt=Hello&depth=8"

# Solve a game
curl -X POST -H "$KINETIC_AUTH" -H "Content-Type: application/json" \
  -d '{"game":"rps","method":"mmd_fixed","lr":0.1,"tau":0.1,"steps":100}' \
  "https://kinetic.kinetic-ai.workers.dev/api/solve"
Try the Interactive Demo