Noether Registry API

Stage registry with semantic search, type checking, and composition execution

Authentication

Read routes are public — no authentication needed. Write routes require an X-API-Key header when NOETHER_API_KEY is set.

curl -H "X-API-Key: your-key" -X POST https://registry.noether.dev/stages

Rate Limiting

Public routes: 100 requests per 60 seconds per IP (configurable via NOETHER_RATE_LIMIT and NOETHER_RATE_WINDOW). Rate limit headers:

X-RateLimit-Limit — maximum requests per window
X-RateLimit-Remaining — remaining requests
Retry-After — seconds until window resets (on 429)

Endpoints

GET /stages

List stages with optional filtering.

Parameter	Type	Description
`lifecycle`	string	Filter: `active` (default), `draft`, `deprecated`, `tombstone`, `all`
`tag`	string	Filter by tag (exact match)
`limit`	integer	Max results (default 50, max 200)
`offset`	integer	Pagination offset

curl https://registry.noether.dev/stages?tag=ml&limit=10

GET /stages/search?q=

Semantic search across all active stages. Uses three-index fusion (signature, description, examples).

curl "https://registry.noether.dev/stages/search?q=parse+CSV+data"

GET /stages/{id}

Get a stage by its full SHA-256 ID.

curl https://registry.noether.dev/stages/72cdbe8850ff9f60...

POST /stages

Submit a new stage. Validates hash, signature, description, and checks for near-duplicates.

curl -X POST https://registry.noether.dev/stages \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d @stage.json

DELETE /stages/{id}

Delete a stage. Removes from semantic index.

PATCH /stages/{id}/lifecycle

Update stage lifecycle. Valid transitions: Draft→Active, Active→Deprecated, Active→Tombstone.

curl -X PATCH https://registry.noether.dev/stages/{id}/lifecycle \
  -H "X-API-Key: your-key" \
  -d '{"lifecycle": "active"}'

For deprecation, include successor_id:

{"lifecycle": "deprecated", "successor_id": "new-stage-id"}

POST /compositions/run

Run or dry-run a composition graph.

curl -X POST https://registry.noether.dev/compositions/run \
  -H "X-API-Key: your-key" \
  -d '{"graph": {...}, "input": {...}, "dry_run": false}'

GET /health

Health check with store statistics.

curl https://registry.noether.dev/health

GET /docs

This page.

Response Format (ACLI)

All responses follow the ACLI protocol:

// Success
{"ok": true, "command": "stage list", "result": {...}, "meta": {"version": "0.1.0"}}

// Error
{"ok": false, "command": "stage list", "error": {"code": "NOT_FOUND", "message": "..."}, "meta": {...}}

CLI Usage

# Point CLI at this registry
export NOETHER_REGISTRY=https://registry.noether.dev

# Search for stages
noether stage search "parse CSV"

# List ML stages
noether stage list --tag ml

# Compose using registry stages
noether compose "sort a list by score and take top 3"

Stage Categories

data ai ml web infra media devtools analytics sklearn pytorch nlp csv json html visualization