API & webhook reference

Integrate ClawSplit into your CI/CD pipeline, trigger experiments from code, and receive real-time notifications when results are ready. Everything you need to automate data-driven prompt optimization.

Quickstart tutorial

First experiment in 5 minutes

Statistics explainer

p-values in plain language

Optimization playbook

Systematic SOUL.md improvement

Authentication

All API requests require a Bearer token. Generate an API key from your ClawSplit dashboard under Settings → API Keys. Keys are scoped to your workspace and can be revoked at any time.

Authorization: Bearer cs_live_your_api_key_here

Keep your API key secret. Never commit it to version control. Use environment variables (e.g., CLAWSPLIT_API_KEY) in CI/CD pipelines.

API quickstart

Create an experiment, let it run, and fetch results — three API calls is all it takes.

Create an experiment

POST /v1/experiments

curl

curl -X POST https://api.clawsplit.com/v1/experiments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "concise-vs-verbose-soulmd",
    "variants": [
      {
        "name": "control",
        "soul_md": "You are a helpful assistant..."
      },
      {
        "name": "concise",
        "soul_md": "Be concise and direct..."
      }
    ],
    "sample_size": 200,
    "primary_metric": "task_completion",
    "confidence": 0.95
  }'

JavaScript

const res = await fetch("https://api.clawsplit.com/v1/experiments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "concise-vs-verbose-soulmd",
    variants: [
      { name: "control", soul_md: "You are a helpful assistant..." },
      { name: "concise", soul_md: "Be concise and direct..." },
    ],
    sample_size: 200,
    primary_metric: "task_completion",
    confidence: 0.95,
  }),
});

const experiment = await res.json();
console.log(experiment.id); // "exp_abc123"

Fetch results

GET /v1/experiments/:id/results

curl

curl https://api.clawsplit.com/v1/experiments/exp_abc123/results \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.clawsplit.com/v1/experiments/exp_abc123/results",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const results = await res.json();
// {
//   status: "significant",
//   winner: "concise",
//   p_value: 0.003,
//   variants: { control: { completion: 0.82 }, concise: { completion: 0.91 } }
// }

Webhook events

Configure a webhook URL in your dashboard to receive real-time notifications. ClawSplit sends a POST request with a JSON payload for each event. All webhooks include an X-ClawSplit-Signature header for verification (HMAC-SHA256).

experiment.started

Fired when an experiment begins accepting traffic. Use this to confirm your CI pipeline triggered successfully.

experiment.sample_reached

Fired when the experiment hits its target sample size. Analysis begins automatically.

experiment.winner_declared

Fired when statistical significance is reached and a winner is declared. Includes full results.

experiment.no_winner

Fired when the experiment completes but no statistically significant difference was found.

experiment.stopped

Fired when an experiment is manually stopped or hits a guardrail (e.g., variant performing significantly worse).

variant.promoted

Fired when a winning variant is promoted to production via the API or dashboard.

Example webhook payload

Here is what the experiment.winner_declared event looks like:

// POST to your configured webhook URL
{
  "event": "experiment.winner_declared",
  "experiment_id": "exp_abc123",
  "experiment_name": "concise-vs-verbose-soulmd",
  "winner": "concise",
  "p_value": 0.003,
  "confidence": 0.95,
  "variants": {
    "control": { "task_completion": 0.82, "avg_cost": 0.0034 },
    "concise": { "task_completion": 0.91, "avg_cost": 0.0021 }
  },
  "timestamp": "2026-03-25T14:30:00Z"
}

Rate limits

Starter60 requests/minute

Pro300 requests/minute

Team600 requests/minute

EnterpriseCustom — contact us

Ready to integrate?