Docs — Crawltic API, SDKs, CLI, and MCP reference

// 01 · quickstart

First experiment in three steps

Install the CLI, authenticate once, and create an experiment. Every step below is also a single REST call, so you can run the same flow from CI.

1
Install
Homebrew, npm, pip, or a static binary for Linux and Windows.
brew install crawltic/tap/crawltic
2
Authenticate
Opens a browser once and stores a scoped key in your OS keychain. In CI, set CRAWLTIC_API_KEY.
crawltic login
3
Create and assign
Define variants and the metric that decides the winner, then request an assignment for any user key.
crawltic experiments create ...

zsh — quickstart

// 02 · rest api

REST API reference

Base URL https://api.crawltic.com/v1. Authenticate with Authorization: Bearer <key>. All bodies are JSON, all timestamps are RFC 3339, and every write accepts an Idempotency-Key header.

endpoints — 12 of 38 shown · p50 measured live

Method	Path	Description	p50
POST	/experiments	Create an experiment with variants, metric, and allocation	18ms
GET	/experiments	List experiments, filterable by status and tag	9ms
GET	/experiments/{id}	Fetch configuration and current status	6ms
PATCH	/experiments/{id}	Update allocation, pause, or resume	14ms
DELETE	/experiments/{id}	Archive an experiment and freeze its results	12ms
GET	/assign	Deterministic, sticky variant assignment for a user key	3.8ms
POST	/events	Log a conversion or any custom metric value	5.1ms
POST	/events/batch	Up to 5,000 events per request, gzip accepted	22ms
GET	/experiments/{id}/results	Posteriors, p-values, lift, and the current decision	11.6ms
POST	/experiments/{id}/ship	Promote a variant, optionally as a staged ramp	31ms
POST	/webhooks	Subscribe an endpoint to experiment lifecycle events	16ms
DELETE	/webhooks/{id}	Remove a subscription and rotate its secret	10ms

Create an experiment and assign a variant POST /experiments · GET /assign

create-experiment

curl https://api.crawltic.com/v1/experiments \
  -H "Authorization: Bearer $CRAWLTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "checkout-button",
    "metric": "revenue_per_visitor",
    "variants": ["control", "v2"],
    "traffic_allocation": 1.0
  }'

# then assign a user
curl "https://api.crawltic.com/v1/assign?experiment=checkout-button&user=usr_8821" \
  -H "Authorization: Bearer $CRAWLTIC_API_KEY"

import { Crawltic } from "@crawltic/sdk";

const ct = new Crawltic({ apiKey: process.env.CRAWLTIC_API_KEY });

const exp = await ct.experiments.create({
  name: "checkout-button",
  metric: "revenue_per_visitor",
  variants: ["control", "v2"],
  trafficAllocation: 1.0,
});

const { variant } = await ct.assign(exp.id, { user: "usr_8821" });
// variant === "v2", sticky for this user

from crawltic import Crawltic

ct = Crawltic()  # reads CRAWLTIC_API_KEY

exp = ct.experiments.create(
    name="checkout-button",
    metric="revenue_per_visitor",
    variants=["control", "v2"],
    traffic_allocation=1.0,
)

variant = ct.assign(exp.id, user="usr_8821").variant
# "v2", sticky for this user

client := crawltic.NewClient(os.Getenv("CRAWLTIC_API_KEY"))

exp, err := client.Experiments.Create(ctx, &crawltic.ExperimentParams{
    Name:              "checkout-button",
    Metric:            "revenue_per_visitor",
    Variants:          []string{"control", "v2"},
    TrafficAllocation: 1.0,
})
if err != nil {
    log.Fatal(err)
}

a, _ := client.Assign(ctx, exp.ID, "usr_8821")
// a.Variant == "v2"

Log a metric and read results POST /events · GET /results

track-and-read

curl -X POST https://api.crawltic.com/v1/events \
  -H "Authorization: Bearer $CRAWLTIC_API_KEY" \
  -d '{"experiment":"checkout-button","user":"usr_8821","metric":"order_value","value":84.20}'

curl https://api.crawltic.com/v1/experiments/checkout-button/results \
  -H "Authorization: Bearer $CRAWLTIC_API_KEY"
# { "v2": { "mean": 48.80, "prob_to_beat": 0.962 }, "decision": "ship" }

await ct.track({
  experiment: "checkout-button",
  user: "usr_8821",
  metric: "order_value",
  value: 84.2,
});

const r = await ct.results("checkout-button");
console.log(r.variants.v2.probToBeat, r.decision); // 0.962 "ship"

ct.track(
    experiment="checkout-button",
    user="usr_8821",
    metric="order_value",
    value=84.20,
)

r = ct.results("checkout-button")
print(r.variants["v2"].prob_to_beat, r.decision)  # 0.962 ship

_ = client.Track(ctx, crawltic.Event{
    Experiment: "checkout-button",
    User:       "usr_8821",
    Metric:     "order_value",
    Value:      84.20,
})

r, _ := client.Results(ctx, "checkout-button")
fmt.Println(r.Variants["v2"].ProbToBeat, r.Decision) // 0.962 ship

Rate limits: 5,000 requests per minute per key, returned in X-RateLimit-Remaining. Assignment calls are served from the edge and do not count against the limit.

// 03 · graphql

GraphQL and live subscriptions

Every REST resource is mirrored at /v1/graphql. Subscriptions stream result updates over WebSocket the moment new evidence lands, so dashboards never poll.

POST /v1/graphql

query Results {
  experiment(name: "checkout-button") {
    status
    variants { key mean n probToBeat }
    decision { action confidence }
  }
}

subscription Live {
  experimentUpdated(name: "checkout-button") {
    variant
    mean
    n
    probToBeat
  }
}

subscription Livestreaming

v2 · mean control · mean

// 04 · sdks

Typed SDKs with local evaluation

SDKs sync experiment config in the background and bucket users in-process, so assignment never waits on the network. Events are batched and flushed on an interval or on shutdown.

TypeScript 2.4.1

npm i @crawltic/sdk

Python 2.4.0

pip install crawltic

Go 2.3.2

go get crawltic.com/go

Ruby 2.3.0

gem install crawltic

Swift 1.8.4

.package(url: "crawltic/swift")

Kotlin 1.8.1

implementation("com.crawltic:sdk")

sdk.localEval — in-process bucketing

Assigned · A

Assigned · B

Eval time

0.04ms

// 05 · cli

The crawltic CLI

Every command maps 1:1 to an API endpoint and supports --format json, so experiment logic drops straight into CI pipelines, cron jobs, and release scripts.

zsh — release pipeline

crawltic loginAuthenticate and store a scoped key

crawltic experiments createDefine variants, metric, allocation

crawltic assignResolve a variant for a user key

crawltic trackSend an event or metric value

crawltic results --watchStream posteriors to the terminal

crawltic quota setConfigure decision thresholds

crawltic ship --rampPromote a winner in stages

crawltic rollbackRevert to control instantly

Install with brew, npm i -g @crawltic/cli, or a static binary. Exit codes are stable, so crawltic results --fail-under 0.95 can gate a deploy.

// 06 · mcp server

MCP server for AI agents

Add Crawltic to Claude, Cursor, or any MCP client, and your agent can create, monitor, and ship experiments in plain language, with the same permissions as the key you give it.

claude_desktop_config.json

{
  "mcpServers": {
    "crawltic": {
      "command": "npx",
      "args": ["-y", "@crawltic/mcp-server"],
      "env": {
        "CRAWLTIC_API_KEY": "sk_live_..."
      }
    }
  }
}

create_experimentassign_variantlog_metricget_resultsship_winnerpause_experimentset_decision_rules

Read-only keys expose only the query tools
Every tool call is written to the audit log with the agent name
Ship and rollback tools honor your guardrails and quotas

agent session — crawltic mcp · 7 tools

// 07 · webhooks

Signed, retried webhooks

Every lifecycle event is signed with HMAC-SHA256 in the Crawltic-Signature header. Non-2xx responses are retried with exponential backoff for up to 24 hours, and every attempt is visible in the delivery log.

deliveries.live — https://hooks.orbital.dev/crawltic

Event

experiment.shipped

Signed payload

HMAC-SHA256

Your endpoint

POST /hooks/crawltic

200 OK

awaiting

retry scheduled

{
  "type": "experiment.shipped",
  "experiment": "checkout-button",
  "variant": "v2",
  "lift": 0.184,
  "confidence": 0.962
}

Attempts

First-try rate

// 08 · decision rules

Declarative decision rules

Commit a crawltic.yaml next to your code. The engine re-evaluates every minute and ships, pauses, or rolls back once confidence, lift, and sample quotas all clear.

crawltic rules apply

# crawltic.yaml
experiment: checkout-button
metric: epc
decision:
  auto_ship:
    min_lift: 0.10
    confidence: 0.95
  quotas:
    min_visitors_per_variant: 1000
    min_conversions: 100
  guardrails:
    - metric: p95_latency_ms
      max_regression: 0.05
    - metric: refund_rate
      max_regression: 0.02
  on_breach: rollback
  ramp: [10, 50, 100]

Is Variant B worth shipping? metric: EPC

+18.4%

min_lift 10% cleared · confidence 96.2% of 95%

min_visitors_per_variant · A1,000/1,000

min_visitors_per_variant · B1,000/1,000

min_conversions84/100

guardrail · p95_latency_ms+1.2% / 5%

Evaluated every 60s · ships the moment min_conversions clears

Every experiment is
one call away.

First experiment in three steps

Install

Authenticate

Create and assign

REST API reference

Create an experiment and assign a variant POST /experiments · GET /assign

Log a metric and read results POST /events · GET /results

GraphQL and live subscriptions

Typed SDKs with local evaluation

The crawltic CLI

MCP server for AI agents

Signed, retried webhooks

Declarative decision rules

Your first experiment is one request away.

Every experiment isone call away.

First experiment in three steps

Install

Authenticate

Create and assign

REST API reference

Create an experiment and assign a variant POST /experiments · GET /assign

Log a metric and read results POST /events · GET /results

GraphQL and live subscriptions

Typed SDKs with local evaluation

The crawltic CLI

MCP server for AI agents

Signed, retried webhooks

Declarative decision rules

Your first experiment is one request away.

Every experiment is
one call away.