API Overview

The OpenScouter REST API lets you programmatically create studies, manage tests, retrieve results, and integrate with external systems. All endpoints accept and return JSON.

Base URL

https://openscouter.com/api

All paths in this reference are relative to this base.

Authentication

Every request must include an Authorization header unless the endpoint is marked None.

Method	Header format	Used by
JWT	`Authorization: Bearer <jwt>`	Authenticated user actions
Token	`Authorization: Token <token>`	Server-to-server integrations
Bearer	`Authorization: Bearer <token>`	OAuth flows and external clients
Webhook	`x-webhook-secret: <secret>`	Incoming webhook payloads
Cron	`Authorization: Bearer <cron-secret>`	Scheduled background jobs

JWTs are issued at sign-in and expire after 24 hours. Refresh tokens are valid for 30 days.

Response Envelope

Every response follows the same structure:

{
  "success": true,
  "data": { },
  "error": null,
  "metadata": {
    "page": 1,
    "limit": 20,
    "total": 142
  }
}

Field	Type	Description
`success`	boolean	`true` when the request succeeded
`data`	object \| array \| null	The response payload
`error`	string \| null	Human-readable error message, `null` on success
`metadata`	object \| null	Pagination info, present on list endpoints

On error, data is null and error contains a description:

{
  "success": false,
  "data": null,
  "error": "Session not found",
  "metadata": null
}

Pagination

List endpoints support cursor-free page-based pagination via query parameters:

GET /api/sessions?page=1&limit=20

Parameter	Default	Max
`page`	`1`	unlimited
`limit`	`20`	`100`

Pagination details are returned in metadata.page, metadata.limit, and metadata.total.

Rate Limiting

Tier	Limit
Unauthenticated	30 requests / minute
Authenticated (free)	120 requests / minute
Authenticated (pro)	600 requests / minute
Webhook ingestion	1,000 events / minute

When you exceed the limit the API returns HTTP 429 with a Retry-After header in seconds.

CORS

The API allows cross-origin requests from:

https://openscouter.com
https://*.openscouter.com
http://localhost:* (development only)

All other origins are blocked. Preflight OPTIONS requests return 200 with appropriate CORS headers.

HTTP Error Codes

Code	Meaning
`400`	Bad Request. The request body or query parameters are malformed.
`401`	Unauthorized. The `Authorization` header is missing or invalid.
`403`	Forbidden. The token is valid but lacks permission for this action.
`404`	Not Found. The requested resource does not exist.
`422`	Unprocessable Entity. Validation failed. The `error` field lists the first violation.
`429`	Too Many Requests. Rate limit exceeded. Check `Retry-After`.
`500`	Internal Server Error. Something went wrong on our end.

Versioning

The API is currently unversioned. Breaking changes are announced in the changelog with a minimum 30-day deprecation window.