Authentication

To start making authenticated requests, you need an API key. You can create and manage API keys from your SkillRouter dashboard.

1. Navigate to Dashboard → API Keys in your dashboard.
2. Click Create New Key and give it a descriptive name (e.g., "Production Backend" or "Dev Testing").
3. Choose the appropriate scope — read-only for discovery or full-access for discovery and execution.
4. Copy your key immediately. For security, the full key is only shown once.

All API requests must include your API key in the Authorization header using the Bearer scheme.

cURL Example

curl -X POST https://api.skillrouter.dev/v1/discover \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "send an email"}'

Python SDK

The Python SDK handles authentication automatically. Pass your key during initialization or let it read from the environment.

from skillrouter import SkillRouter

# Option 1: Pass the API key directly
sr = SkillRouter(api_key="sk_live_your_api_key_here")

# Option 2: Use an environment variable (recommended)
# Set SKILLROUTER_API_KEY in your environment, then:
sr = SkillRouter()  # Automatically reads from env

Hardcoding API keys is a security risk. Instead, store them as environment variables and let your application read them at runtime.

Using a .env File

# .env
SKILLROUTER_API_KEY=sk_live_your_api_key_here

# Never commit this file to version control!
# Add .env to your .gitignore

Loading from Environment

import os
from skillrouter import SkillRouter

# The SDK automatically reads SKILLROUTER_API_KEY from the environment
sr = SkillRouter()

# Or explicitly load from env
sr = SkillRouter(api_key=os.environ["SKILLROUTER_API_KEY"])

API requests are rate limited to ensure fair usage and platform stability. Limits vary by plan and are applied per API key.

Rate Limit Headers

Every API response includes headers indicating your current rate limit status.

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1709942400
X-RateLimit-Window: 60

Handling 429 Errors

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header. The SDK handles retries automatically with exponential backoff, but you can also handle this manually.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "retry_after": 30
  }
}