API Reference
Overview

API Reference

The Litmus Science REST API enables programmatic submission of experiment requests, status tracking, and results retrieval.

Base URL

https://api.litmus.science

Authentication

All endpoints require authentication via Bearer token or API key:

# Bearer token
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.litmus.science/experiments
 
# API key
curl -H "X-API-Key: lk_your_api_key" https://api.litmus.science/experiments

See Authentication for details.

Rate Limits

TierRequests/MinuteRequests/Day
Standard1001,000
Pro1,00010,000
AI Agent5005,000

Rate limit headers are included in all responses:

  • X-RateLimit-Limit: Your limit
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when limit resets

Endpoints Overview

Authentication

EndpointMethodDescription
/auth/registerPOSTRegister new user
/auth/tokenPOSTGet access token

Experiments

EndpointMethodDescription
/experimentsPOSTCreate experiment
/experimentsGETList experiments
/experiments/{id}GETGet experiment
/experiments/{id}PATCHUpdate experiment
/experiments/{id}DELETECancel experiment

Results

EndpointMethodDescription
/experiments/{id}/resultsGETGet results
/experiments/{id}/approvePOSTApprove results
/experiments/{id}/disputePOSTDispute results

Validation

EndpointMethodDescription
/validatePOSTValidate experiment
/validate/hypothesisPOSTValidate hypothesis
/estimatePOSTGet cost estimate

Templates

EndpointMethodDescription
/templatesGETList templates
/templates/{id}GETGet template

Operators

EndpointMethodDescription
/operator/jobsGETList available jobs
/operator/jobs/{id}/claimPOSTClaim job
/operator/jobs/{id}/submitPOSTSubmit results

Webhooks

EndpointMethodDescription
/webhooks/testPOSTTest webhook

Error Responses

All errors follow this format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable message",
    "details": {}
  }
}

Common Error Codes

CodeHTTP StatusDescription
unauthorized401Invalid or missing credentials
forbidden403Valid credentials but insufficient permissions
not_found404Resource doesn't exist
validation_failed422Request validation failed
rate_limit_exceeded429Too many requests
safety_rejected403Experiment rejected for safety reasons

OpenAPI Specification

The complete OpenAPI 3.1 specification is available at:

  • Interactive docs: https://api.litmus.science/docs
  • ReDoc: https://api.litmus.science/redoc
  • Raw spec: https://api.litmus.science/openapi.json
Negative Results: Lion's ManeAuthentication