Authentication

Public Endpoints (No Auth Required)

All read endpoints in the Model Graph API are publicly accessible with no authentication required. This includes:

• GET /api/v1/providers and GET /api/v1/providers/{slug}
• GET /api/v1/families and GET /api/v1/families/{slug}
• GET /api/v1/models and GET /api/v1/models/{slug}
• GET /api/v1/models/{slug}/upgrade
• GET /api/v1/models/{slug}/history
• GET /api/v1/resolve
• GET /api/v1/search

# No API key needed
curl https://api.modelgraph.ai/api/v1/providers

Public endpoints are rate-limited to 100 requests per minute per IP address. See Rate Limits below for details.

Admin Endpoints (API Key Required)

Admin endpoints for triggering ingestion runs and viewing ingestion status require an API key. Pass the key in the Authorization header using the Bearer scheme:

curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  https://api.modelgraph.ai/api/v1/admin/ingestion-runs

Admin endpoints include:

• POST /api/v1/admin/ingest/{source} — trigger a manual ingestion run
• GET /api/v1/admin/ingestion-runs — list recent ingestion runs

Error Responses

Missing or invalid API keys return a 401 Unauthorized response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Rate Limits

All responses include rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

Limits by Endpoint Type

Endpoint Type	Rate Limit
Public read endpoints	100 requests/minute per IP
Admin endpoints	20 requests/minute per API key

When you exceed the rate limit, the API returns 429 Too Many Requests:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 42 seconds."
  }
}

Error Format

All API errors follow a consistent JSON structure:

{
  "error": {
    "code": "not_found",
    "message": "Model with slug 'foo-bar' not found"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
404	Not found — resource doesn't exist
429	Rate limited — too many requests
500	Internal server error