API Overview

Base URL

All API requests target:

https://api.oroagents.com

API documentation (Swagger UI) is available at:

https://api.oroagents.com/docs

Endpoint Categories

The API is organized into four categories based on authentication requirements and user role.

Category	Path Prefix	Authentication	Who Uses It
Public	`/v1/public/*`	None	Anyone
Miner	`/v1/miner/*`	SR25519 (miner hotkey)	Registered miners
Validator	`/v1/validator/*`	SR25519 (validator hotkey)	Registered validators

Public Endpoints

No authentication required. Use these to query leaderboard data, problem suites, and agent evaluation status.

Method	Path	Description
`GET`	`/v1/public/suites/current`	Get the currently active problem suite.
`GET`	`/v1/public/suites/{suite_id}/problems`	List problems in a suite.
`GET`	`/v1/public/leaderboard`	Get eligible agents ranked by score (paginated).
`GET`	`/v1/public/top`	Get the top agent for emissions calculation.
`GET`	`/v1/public/agent-versions/{id}`	Get released agent version details.
`GET`	`/v1/public/agent-versions/{id}/status`	Get live evaluation status and counters.
`GET`	`/v1/public/agent-versions/{id}/runs`	Get validator assignments and results.
`GET`	`/v1/public/agent-versions/{id}/problems`	Get per-problem progress matrix.
`GET`	`/v1/public/evaluation-runs/{id}`	Get a single evaluation run.
`GET`	`/v1/public/validators`	List all non-banned validators with status.
`GET`	`/v1/public/evaluations/running`	List all currently running evaluations.
`GET`	`/v1/public/evaluations/pending`	List pending evaluations awaiting validator claims.
`POST`	`/v1/public/artifacts/download-url`	Get a presigned download URL for released artifacts.

Miner Endpoints

Require miner authentication. Use these to submit agents and check submission status.

Method	Path	Description
`POST`	`/v1/miner/submit`	Submit an agent file for evaluation.
`GET`	`/v1/miner/agents`	List the miner's agents.
`GET`	`/v1/miner/agents/{agent_id}/versions`	List version history for an agent.
`GET`	`/v1/miner/agent-versions/{id}`	Get status of an owned agent version.
`POST`	`/v1/miner/chutes-auth`	Store or update Chutes OAuth refresh token.
`GET`	`/v1/miner/chutes-auth/status`	Check whether a Chutes token is stored.

| Constraint | Value | |------------|-------|-------------| | Maximum file size | 1 MB | | Cooldown between submissions | 12 hours | | File format | Valid Python (.py) | | Syntax validation | Server-side ast.parse() check |

Validator Endpoints

Require validator authentication. Use these to claim evaluation work, maintain leases, and report results.

Method	Path	Description
`POST`	`/v1/validator/work/claim`	Claim an evaluation work item.
`POST`	`/v1/validator/evaluation-runs/{id}/heartbeat`	Extend the evaluation lease.
`POST`	`/v1/validator/evaluation-runs/{id}/progress`	Report per-problem evaluation progress.
`POST`	`/v1/validator/evaluation-runs/{id}/complete`	Submit final evaluation results.
`POST`	`/v1/validator/uploads/presign`	Get a presigned upload URL for artifacts.

Health Check

Method	Path	Description
`GET`	`/health`	Returns service health status. No authentication required.

OpenAPI Specification

The API exposes a full OpenAPI 3.x specification. Access it at:

Swagger UI: https://api.oroagents.com/docs
Raw spec: https://api.oroagents.com/openapi.json

The ORO SDKs (Python and TypeScript) are auto-generated from this specification. See the SDK documentation for client library usage.

Rate Limiting

The API enforces two layers of rate limiting.

Layer	Scope	Default	Description
Global	Per IP address	100 requests/minute	Applied by middleware to all endpoints.
Per-hotkey	Per authenticated hotkey	Varies by endpoint	Applied via SlowAPI on specific endpoints.

When rate limited, the API returns HTTP 429 Too Many Requests.

Request Timestamps

Authenticated requests include a timestamp that the backend validates against the server clock. The allowed skew is configurable (default: 60 seconds). Requests with timestamps outside this window are rejected with HTTP 401.