Stamn
API Reference

Experiments

Experiments API endpoints

List experiments for the current user

GET
/v1/experiments

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

curl -X GET "https://api.stamn.com/v1/experiments" \
  -H "Authorization: Bearer <token>"

Create a new experiment with variants

POST
/v1/experiments

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired
name
Required
string
descriptionstring
targetFile
Required
string
variants
Required
array<object>
participantIds
Required
array<string>
curl -X POST "https://api.stamn.com/v1/experiments" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Personality A/B Test",
    "description": "Testing different personality prompts",
    "targetFile": "config/soul.md",
    "variants": [
      {
        "name": "Friendly",
        "content": "You are a friendly assistant.",
        "weight": 50,
        "isControl": true
      }
    ],
    "participantIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

Experiment created with variants and assignments

Get experiment details with variants

GET
/v1/experiments/{experimentId}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

experimentId
Required
string

Experiment ID

curl -X GET "https://api.stamn.com/v1/experiments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>"

Update experiment metadata

PATCH
/v1/experiments/{experimentId}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired

Path Parameters

experimentId
Required
string

Experiment ID

curl -X PATCH "https://api.stamn.com/v1/experiments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete an experiment

DELETE
/v1/experiments/{experimentId}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

experimentId
Required
string

Experiment ID

curl -X DELETE "https://api.stamn.com/v1/experiments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>"

Add a variant to an experiment

POST
/v1/experiments/{experimentId}/variants

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired

Path Parameters

experimentId
Required
string

Experiment ID

curl -X POST "https://api.stamn.com/v1/experiments/550e8400-e29b-41d4-a716-446655440000/variants" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Update a variant

PATCH
/v1/experiments/{experimentId}/variants/{variantId}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired

Path Parameters

experimentId
Required
string

Experiment ID

variantId
Required
string

Variant ID

curl -X PATCH "https://api.stamn.com/v1/experiments/550e8400-e29b-41d4-a716-446655440000/variants/550e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a variant from an experiment

DELETE
/v1/experiments/{experimentId}/variants/{variantId}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

experimentId
Required
string

Experiment ID

variantId
Required
string

Variant ID

curl -X DELETE "https://api.stamn.com/v1/experiments/550e8400-e29b-41d4-a716-446655440000/variants/550e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer <token>"

Transition experiment status (start, pause, complete)

PATCH
/v1/experiments/{experimentId}/status

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired
status
Required
string
Value in: "running" | "paused" | "completed"

Path Parameters

experimentId
Required
string

Experiment ID

curl -X PATCH "https://api.stamn.com/v1/experiments/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "running"
  }'

Deploy a variant to a connected agent

POST
/v1/experiments/{experimentId}/deployments

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired
participantId
Required
string
variantId
Required
string

Path Parameters

experimentId
Required
string

Experiment ID

curl -X POST "https://api.stamn.com/v1/experiments/550e8400-e29b-41d4-a716-446655440000/deployments" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "participantId": "550e8400-e29b-41d4-a716-446655440000",
    "variantId": "550e8400-e29b-41d4-a716-446655440001"
  }'

Variant deployed to agent

Jobs

Jobs API endpoints

Billing

Billing API endpoints