search

API reference

The Leoma API is a centralized service for validators and the dashboard. Base URL is configurable (e.g. set by the deployment). All routes below are relative to that base.

Authentication: Endpoints that require validator identity use signature auth. Send:

  • X-Validator-Hotkey — SS58 address

  • X-Signature — Hex signature (optional 0x prefix)

  • X-Timestamp — Unix timestamp (string)

Message signed: SHA256(request_body_hex):timestamp (UTF-8), signed with the validator’s keypair. Timestamp must be within the allowed window (e.g. 5 minutes). Blacklisted hotkeys are rejected.

hashtag
Health

hashtag
GET /health

Returns API health.

Response: HealthResponse

  • status — e.g. "healthy" or "degraded"

  • version — API version

  • database — boolean

  • metagraph_synced — boolean

  • last_sync — optional datetime

hashtag
Miners

Prefix: /miners

hashtag
GET /miners/list

Public. List all miners (valid and invalid) for dashboard.

Response: MinersListResponse

  • miners — list of MinerResponse (uid, hotkey, model_name, model_revision, model_hash, chute_id, chute_slug, is_valid, invalid_reason, block, last_validated_at)

  • total, valid_count

hashtag
GET /miners/valid

Auth required. List only miners that passed validation.

Response: Same as /miners/list.

hashtag
GET /miners/uid/{uid}

Public. Get miner by UID.

Response: MinerResponse

hashtag
GET /miners/{miner_hotkey}

Public. Get miner by hotkey. Alias: GET /miners/info/{miner_hotkey}.

Response: MinerResponse

hashtag
GET /miners/{miner_hotkey}/tasks

Public. List tasks for a miner with stake-weighted pass/fail and latency. Query: none (hotkey in path).

Response: List of MinerTaskEntry: task_id, passed, latency_ms, updated.

hashtag
Samples

Prefix: /samples

All write operations and some read operations require signature auth.

hashtag
POST /samples

Auth required. Submit a single sample.

Body: SampleSubmission

  • task_id (optional), sample_id (legacy, required if no task_id)

  • miner_hotkey, prompt

  • s3_bucket, s3_prefix

  • passed (boolean)

  • Optional: confidence, reasoning, latency_ms, original_artifacts, generated_artifacts, presentation_order, evaluation_signature

Response: SampleResponse (id, sample_id, validator_hotkey, miner_hotkey, prompt, s3_bucket, s3_prefix, passed, confidence, reasoning, evaluated_at, task_id, latency_ms).

hashtag
POST /samples/batch

Auth required. Submit up to 100 samples. Body: { "signature": "optional hex", "samples": [ SampleSubmission, ... ] }. If signature is set, all samples must have the same task_id. The API stores the signature and may upload evaluation result JSON to S3.

Response: List of SampleResponse.

hashtag
GET /samples/list

Public. Recent samples (for dashboard). Query: limit (default 200).

Response: List of SampleResponse.

hashtag
GET /samples/task

Public. Samples for one task. Query: validator_hotkey, sample_id.

Response: List of SampleResponse.

hashtag
GET /samples/validator/{validator_hotkey}

Auth required. Samples submitted by a validator. Query: limit (default 100).

Response: List of SampleResponse.

hashtag
GET /samples/miner/{miner_hotkey}

Auth required. Samples for a miner across validators. Query: limit (default 100).

Response: List of SampleResponse.

hashtag
Scores

Prefix: /scores

All score/rank endpoints are public.

hashtag
GET /scores

Public. Aggregated scores across validators (per-miner score aggregates).

Response: AggregatedScoreResponse (scores dict, total_validators, updated_at).

hashtag
GET /scores/validators

Public. Validator summaries for dashboard (total_samples, total_passed, avg_score, pass_rate, last_updated per validator).

Response: List of ValidatorSummaryResponse.

hashtag
GET /scores/rank

Public. Miner rank list (dominance algorithm, updated periodically). Each entry: miner_hotkey, uid, rank, passed_count, pass_rate, block, eligible (completeness ≥ 0.8).

Response: RankResponse: { "ranks": [ MinerRankEntry, ... ] }.

hashtag
GET /scores/stats

Public. Aggregate stats: total_validators, total_miners, total_samples, total_score_entries, overall_pass_rate.

Response: ScoreStatsResponse.

hashtag
GET /scores/miner/{miner_hotkey}

Public. Per-validator and aggregated scores for one miner.

Response: MinerScoresResponse: by_validator (list of ValidatorScoreDetail), aggregated (total_samples, total_passed, avg_score, pass_rate, validator_count).

hashtag
GET /scores/validator/{validator_hotkey}

Public. All miner scores from one validator.

Response: ValidatorScoresResponse: validator_hotkey, scores (list of MinerScoreEntry), total_miners.

hashtag
Tasks

Prefix: /tasks

hashtag
GET /tasks/latest

Public. Latest sampled task id (for validators). Returns { "task_id": number } or 404.

hashtag
GET /tasks

Public. List tasks for a miner (stake-weighted pass/fail, latency, updated). Query: miner_hotkey (required).

Response: List of MinerTaskEntry: task_id, passed, latency_ms, updated.

hashtag
GET /tasks/{task_id}/miner/{miner_hotkey}

Public. Task detail for a miner: description, s3_prefix, paths for first_frame, original_clip, generated_video, optional presigned URLs (first_frame_url, original_clip_url, generated_video_url), validators (list of validator result: passed, stake, evaluated_at, confidence, reasoning), final_passed (stake-weighted), latency_ms.

Response: TaskMinerDetailResponse.

hashtag
Weights

Prefix: /weights

hashtag
GET /weights

Public. For validators to set on-chain weights. Returns winner_uid and per-miner list (miner_hotkey, uid, pass_rate, weight). Weight is derived from the current rank output; if no winner, winner_uid is 0 (burn).

Response: WeightsResponse: winner_uid, miners (list of MinerWeightEntry).

hashtag
Blacklist

Prefix: /blacklist

hashtag
GET /blacklist

Public. List blacklisted hotkeys (and reason, added_by, created_at).

hashtag
GET /blacklist/miners

Public. List of blacklisted miner hotkeys (strings).

hashtag
GET /blacklist/{hotkey}

Public. Blacklist entry for one hotkey.

hashtag
POST /blacklist

Admin auth required. Add hotkey to blacklist. Body: { "hotkey": "...", "reason": "optional" }.

hashtag
DELETE /blacklist/{hotkey}

Admin auth required. Remove hotkey from blacklist.

hashtag
Summary table

Method
Path
Auth
Description

GET

/health

—

Health check

GET

/miners/list

—

All miners

GET

/miners/valid

Validator

Valid miners only

GET

/miners/uid/{uid}

—

Miner by UID

GET

/miners/{hotkey}

—

Miner by hotkey

GET

/miners/{hotkey}/tasks

—

Miner task list

POST

/samples

Validator

Submit one sample

POST

/samples/batch

Validator

Submit batch (≤100)

GET

/samples/list

—

Recent samples

GET

/samples/task

—

Samples by task

GET

/samples/validator/{hotkey}

Validator

Samples by validator

GET

/samples/miner/{hotkey}

Validator

Samples by miner

GET

/scores

—

Aggregated scores

GET

/scores/validators

—

Validator summaries

GET

/scores/rank

—

Miner rank list

GET

/scores/stats

—

Score statistics

GET

/scores/miner/{hotkey}

—

Miner scores

GET

/scores/validator/{hotkey}

—

Validator scores

GET

/tasks/latest

—

Latest task id

GET

/tasks

—

Miner tasks (query: miner_hotkey)

GET

/tasks/{id}/miner/{hotkey}

—

Task-miner detail

GET

/weights

—

Weights for on-chain

GET/POST/DELETE

/blacklist/...

— / Admin

Blacklist CRUD

For exact request/response schemas (field types, optional vs required), see the Leoma API OpenAPI spec or the source in leoma/api/models/requests.py and route modules.

PreviousStorage (Hippius S3)

Last updated