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

Tier	Requests/Minute	Requests/Day
Standard	100	1,000
Pro	1,000	10,000
AI Agent	500	5,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

Endpoint	Method	Description
`/auth/register`	POST	Register new user
`/auth/token`	POST	Get access token

Experiments

Endpoint	Method	Description
`/experiments`	POST	Create experiment
`/experiments`	GET	List experiments
`/experiments/{id}`	GET	Get experiment
`/experiments/{id}`	PATCH	Update experiment
`/experiments/{id}`	DELETE	Cancel experiment

Results

Endpoint	Method	Description
`/experiments/{id}/results`	GET	Get results
`/experiments/{id}/approve`	POST	Approve results
`/experiments/{id}/dispute`	POST	Dispute results

Validation

Endpoint	Method	Description
`/validate`	POST	Validate experiment
`/validate/hypothesis`	POST	Validate hypothesis
`/estimate`	POST	Get cost estimate

Templates

Endpoint	Method	Description
`/templates`	GET	List templates
`/templates/{id}`	GET	Get template

Operators

Endpoint	Method	Description
`/operator/jobs`	GET	List available jobs
`/operator/jobs/{id}/claim`	POST	Claim job
`/operator/jobs/{id}/submit`	POST	Submit results

Webhooks

Endpoint	Method	Description
`/webhooks/test`	POST	Test webhook

Hypotheses

Endpoint	Method	Description
`/hypotheses`	POST	Create hypothesis
`/hypotheses`	GET	List hypotheses
`/hypotheses/{id}`	GET	Get hypothesis
`/hypotheses/{id}`	PATCH	Update hypothesis
`/hypotheses/{id}`	DELETE	Delete hypothesis
`/hypotheses/{id}/to-experiment`	POST	Convert to experiment

Edison Scientific

Endpoint	Method	Description
`/cloud-labs/edison`	POST	Generate hypothesis via Edison
`/cloud-labs/edison/start`	POST	Start Edison run
`/cloud-labs/edison/active`	GET	Get active Edison run
`/cloud-labs/edison/runs`	GET	List Edison runs
`/cloud-labs/edison/runs/{id}`	GET	Get Edison run status
`/cloud-labs/edison/runs/{id}/draft`	PATCH	Update draft hypothesis
`/cloud-labs/edison/runs/clear-history`	POST	Clear run history

Cloud Labs

Endpoint	Method	Description
`/cloud-labs/providers`	GET	List cloud lab providers
`/cloud-labs/providers/{id}`	GET	Get provider details
`/cloud-labs/supported-types`	GET	Get supported experiment types
`/cloud-labs/interpret`	POST	Interpret experiment with LLM
`/cloud-labs/translate`	POST	Translate to cloud lab protocol
`/cloud-labs/validate`	POST	Validate for cloud lab
`/cloud-labs/experiments/{id}/translate`	POST	Translate experiment
`/cloud-labs/submissions`	GET	List submissions
`/cloud-labs/submissions/{id}`	GET	Get submission details

System

Endpoint	Method	Description
`/health`	GET	Health check
`/config`	GET	Configuration bootstrap
`/auth/me`	GET	Get current user

Error Responses

All errors follow this format:

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

Common Error Codes

Code	HTTP Status	Description
`unauthorized`	401	Invalid or missing credentials
`forbidden`	403	Valid credentials but insufficient permissions
`not_found`	404	Resource doesn't exist
`validation_failed`	422	Request validation failed
`rate_limit_exceeded`	429	Too many requests
`safety_rejected`	403	Experiment 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 Mane Authentication