Evolution API

The Evolution API (Level 1.5) exposes Rotifer’s public gene registry and arena data to external systems. Use it to build recommendation layers, monitoring dashboards, or custom tooling on top of Rotifer’s evolutionary infrastructure.

Base URL

https://api.rotifer.dev/v1

Current access model

All public endpoints are read-only GET endpoints. Each request must send an API key with the read scope in the X-API-Key header:

curl -H "X-API-Key: YOUR_KEY" https://api.rotifer.dev/v1/genes

Key management

Keys are created and managed from the CLI:

rotifer login
rotifer api-key create --name "My Read Key"
rotifer api-key list
rotifer api-key revoke --prefix rk_abcd12

Rate limits

Rate limits are stored per API key. The default create flow uses 30/min, but individual keys can be provisioned with a different per-minute limit.

Endpoints

GET /v1/genes

Search and discover genes with arena ranking data.

Parameter	Type	Default	Description
domain	string	—	Filter by gene domain, for example content.qa
fidelity	string	—	Filter by Wrapped, Hybrid, or Native
sort	string	fitness	Sort by fitness, reputation, or downloads
limit	integer	20	Results per page, max 50
offset	integer	0	Pagination offset

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.rotifer.dev/v1/genes?domain=content.qa&sort=fitness&limit=5"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "doc-retrieval",
      "domain": "content.qa",
      "fidelity": "Hybrid",
      "description": "Document retrieval with semantic search",
      "fitness_score": 0.92,
      "reputation_score": 0.85,
      "owner": "alice",
      "downloads": 342,
      "arena_rank": 1,
      "arena_history": [
        {
          "fitness_value": 0.92,
          "evaluated_at": "2026-03-24T00:00:00Z",
          "total_calls": 1500
        }
      ]
    }
  ],
  "total": 12,
  "limit": 5,
  "offset": 0
}

GET /v1/genes/{id}/phenotype

Fetch the complete public phenotype for a specific gene, including install instructions and compatibility info.

Parameter	Type	Description
id	UUID (path)	Gene UUID

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.rotifer.dev/v1/genes/550e8400-e29b-41d4-a716-446655440000/phenotype"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "doc-retrieval",
  "domain": "content.qa",
  "fidelity": "Hybrid",
  "phenotype": {
    "input": { "type": "object", "properties": { "query": { "type": "string" } } },
    "output": { "type": "object", "properties": { "results": { "type": "array" } } }
  },
  "fitness_score": 0.92,
  "reputation_score": 0.85,
  "install_command": "npx @rotifer/playground install doc-retrieval",
  "compatibility": {
    "min_playground_version": "0.7.0",
    "required_fidelity": "Hybrid"
  }
}

GET /v1/arena/insights

Get evolution health metrics for a domain. This endpoint is useful for monitoring ecosystem diversity and gene competition dynamics.

Parameter	Type	Description
domain	string (required)	Domain to analyze

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.rotifer.dev/v1/arena/insights?domain=content.qa"

Response

{
  "domain": "content.qa",
  "gene_count": 8,
  "shannon_diversity": 2.322,
  "turnover_rate": 0.2,
  "top_genes": [
    { "name": "doc-retrieval", "fitness": 0.92, "trend": "stable" },
    { "name": "answer-synth", "fitness": 0.87, "trend": "rising" }
  ],
  "avg_fitness": 0.65,
  "total_arena_evaluations": 4200
}

Metrics explained

Metric	Description
shannon_diversity	Shannon entropy H'. Higher values indicate healthier competition.
turnover_rate	Fraction of top-5 genes replaced in the last 30 days.
trend	Fitness trajectory based on recent arena evaluations: rising, stable, or declining.

Error responses

All errors use a consistent shape:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

HTTP Status	Code	Description
400	INVALID_ID / MISSING_PARAM	Malformed request
401	UNAUTHORIZED	Invalid or missing API key
404	NOT_FOUND	Resource not found
405	METHOD_NOT_ALLOWED	Only GET is supported
429	RATE_LIMITED	Rate limit exceeded
502	DB_ERROR	Upstream database error

Protocol alignment

API endpoint	Protocol interface	Spec section
GET /v1/genes	GeneRegistry.query() + SemanticDiscovery.discoverByNeed()	§8.2
GET /v1/arena/insights	Arena Data Transparency + ArenaSummary	§9.7.1, §41.2
GET /v1/genes/{id}/phenotype	Phenotype Public tier	§4.2

These endpoints are tagged nonstandard per §25.4 because they are specific to the Cloud Binding implementation.