REST API Reference

The RunRL REST API exposes every feature available in the product UI, allowing you to automate training runs, manage files and tools, deploy models, and integrate RunRL into your own workflows.

Base URL

https://runrl.com/api/v1

Authentication

Every request must include an API key generated from Settings → API Keys. Present the key in the Authorization header using the Bearer scheme.

Authorization: Bearer rl_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

📌 Tip: Create separate keys for automation, CI, or teammates. Keys can be scoped to read, write, or admin permissions.

Quick Health Check

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://runrl.com/api/v1/health

API Keys

Create API Key

• Endpoint: POST /keys
• Scope Required: write

curl -X POST \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline",
    "scopes": ["read", "write"],
    "requests_per_hour": 5000
  }' \
  https://runrl.com/api/v1/keys

List / Inspect API Keys

• Endpoints:
  • GET /keys (list)
  • GET /keys/{id}/usage (usage statistics)
• Scope Required: read

Update / Delete API Keys

• Endpoints:
  • PUT /keys/{id} (rename, toggle active, adjust scopes/limits)
  • DELETE /keys/{id}
• Scope Required: write

Files

Files drive training runs. You can manage prompts, reward/environment code, and SFT datasets directly via the API.

List Files

• Endpoint: GET /files
• Scope: read

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://runrl.com/api/v1/files?type=prompt&search=chatbot"

Filters: type (prompt, reward_function, environment, sft), search, page, per_page, sort, direction.

Upload (Multipart)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@prompt.jsonl" \
  -F "type=prompt" \
  -F "name=Support Prompts" \
  https://runrl.com/api/v1/files

Create from Content (Reward / Environment Code)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reward_function",
    "name": "Latency Reward",
    "content": "def reward_fn(prompt, response):\n    return 1 - response.latency"
  }' \
  https://runrl.com/api/v1/files

Retrieve, Preview, and Download

• GET /files/{fileId} – metadata
• GET /files/{fileId}/preview – first lines or truncated code preview
• GET /files/{fileId}/content – raw text content (prompt/SFT JSONL, Python code)
• GET /files/{fileId}/download – download the original file

Update or Delete

• PUT /files/{fileId} to rename or update reward/environment code
• DELETE /files/{fileId} to remove an unused file (fails if active runs still reference it)
• Scope: write

Runs

Runs encapsulate RL training jobs. The API now exposes the same end-to-end control found in the UI.

List Runs

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://runrl.com/api/v1/runs?status=RUNNING&per_page=10"

Create Run

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B",
    "prompt_file_id": "PROMPT_UUID",
    "reward_file_id": "REWARD_UUID",
    "sft_file_id": "SFT_UUID",
    "type": "reward_function",
    "completion_length": 2048,
    "epochs": 3,
    "learning_rate_multiplier": 1.2,
    "package_requirements": ["wandb==0.17.4"],
    "tool_ids": [12, 18]
  }' \
  https://runrl.com/api/v1/runs

Parameters mirror the run creation modal, including SFT datasets, package requirements, Hugging Face tokens, and tool attachments.

Inspect & Control

• GET /runs/{id} – detailed run state (including tools, files, hf_name)
• GET /runs/{id}/history – status timeline
• GET /runs/{id}/logs – paginated logs with redaction support
• GET /runs/{id}/logs/stream – Server-Sent Events stream for real-time logs
• GET /runs/{id}/metrics – W&B metrics proxy
• GET /runs/{id}/completions – completions captured in W&B
• POST /runs/{id}/cancel – cancel in-progress runs

Deployments

Deploy trained checkpoints to managed infrastructure directly via the API.

• GET /deployments – list your deployments
• GET /deployments/{id} – details (linked run info, status)
• POST /deployments/check – validate a run is deployable (HF checkpoint exists, not already deployed, etc.)
• POST /deployments – trigger deployment (requires positive balance & active API key)
• DELETE /deployments/{id} – remove deployment records

All deployment endpoints require the write scope.

Validation

RunRL ships built-in validators for prompt, SFT, and reward code.

• POST /validation/reward-function
• POST /validation/prompt
• POST /validation/sft

Each endpoint accepts the same payloads as the UI validation modals and returns structured validation feedback (valid, errors, counts, etc.).

Tools

Manage MCP tools via the API.

• GET /tools – list public tools + your private tools (filter with search, verified, etc.)
• POST /tools – register a new tool (requires unique name per owner)
• GET /tools/{id} – tool metadata
• PUT /tools/{id} – update name/description/visibility
• DELETE /tools/{id} – remove a tool (owner or admin)
• POST /tools/test-mcp – ping an MCP server URL and receive handshake diagnostics

Shared Configurations

Shared configurations capture reusable training setups.

• GET /shared-configurations – configurations you own
• GET /shared-configurations/browse – discover public/unlisted configurations (filter by model, reward mode, visibility)
• GET /shared-configurations/{uuid} – detail view (requires owner or shared visibility)
• GET /shared-configurations/{uuid}/data – includes prompt preview & reward code snippets
• POST /shared-configurations – save the current run recipe (files are copied if they belong to another user)
• POST /shared-configurations/{uuid}/copy – clone to your account (copies files & configuration)
• POST /shared-configurations/{uuid}/like – toggle like state
• PUT /shared-configurations/{uuid} – rename, edit description, toggle visibility
• DELETE /shared-configurations/{uuid} – remove configuration you own

Search

The global search endpoint mirrors the in-app quick search.

• Endpoint: GET /search
• Scope: read

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://runrl.com/api/v1/search?q=reward+function"

Returns matching runs, tools, and files in a single response.

Response Format

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}

Errors follow a similar schema with success: false, an error code, descriptive message, and optional details.

Rate Limiting

API keys enforce hourly request quotas (default: 10,000/hour). Limit information is reported in headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9987
X-RateLimit-Reset: 1732315200

Scopes

Error Codes

Need a new endpoint? Something missing from the docs? Let us know at support@runrl.com and we’ll take it from there.