Reference

API Reference

Base URL: https://api.superplane.com/v1

All requests require a Bearer token. Responses are JSON. Rate limit: 1000 req/min per org.

Authentication

All API requests must include your organization token as a Bearer token.

Authorization header 
Authorization: Bearer spl_tok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate tokens in your dashboard under Settings → API tokens. Tokens are scoped to read or read+write. Revoke at any time.

Runs

GET /runs List pipeline runs

Returns a paginated list of pipeline runs for your organization, sorted by created_at descending.

Response 200 
{
  "runs": [{
    "id": "run_9x8f2k",
    "commit_sha": "a7f3c21",
    "status": "passed",
    "tests_selected": 112,
    "tests_total": 847,
    "duration_ms": 43210
  }],
  "page": 1,
  "total": 241
}
GET /runs/:run_id Get a single run

Returns full run details including per-test selection decisions and confidence scores.

Response 200 
{
  "id": "run_9x8f2k",
  "decisions": [{
    "test_path": "api/export_test.py",
    "selected": true,
    "confidence": 0.97
  }]
}
POST /runs Trigger a pipeline run

Trigger a new run for a specific commit. Returns the run object with initial status.

Request body 
{
  "repo_id": "repo_4k2m9p",
  "commit_sha": "a7f3c21",
  "policy_ref": ".superplane/policy.yml"
}

Test Selection

POST /selection Get AI test selection for a commit

Submit a commit diff and receive the AI-selected test list. Used by the CI action internally; you can also call this directly for custom integration.

Request body 
{
  "repo_id": "repo_4k2m9p",
  "commit_sha": "a7f3c21",
  "confidence_threshold": 0.85
}

Webhooks

Configure webhook endpoints in your dashboard. SuperPlane sends POST requests with JSON payloads for these events:

run.started Fired when a pipeline run begins AI selection
run.passed All selected tests passed
run.failed One or more selected tests failed
canary.rollback Canary rollout triggered automatic rollback

Organizations

GET /org Get organization details

Returns your organization's plan, seat count, connected repos, and usage for the current billing period.

GET /org/repos List connected repositories

Returns all repositories connected to this organization with their connection status and policy file path.

Need something not listed here?

The API is still growing. If you need an endpoint that isn't documented, reach out and we'll add it.

Contact the team