About the BlueRound API

The BlueRound API is a RESTful HTTP interface for managing users, handling OAuth 2.0 authentication, and automating documentation workflows. All resources are served over HTTPS and represented as JSON.

Note

Current stable version: v1.2.0 — see API Versioning for the upgrade policy and deprecation timeline.

API Versioning

BlueRound uses semantic versioning. The version is embedded in every base URL (e.g., /v1/). Breaking changes are introduced only in a new major version prefix; minor and patch releases are always backward-compatible.

Version status
Version	Status	Notes
`v1`	✅ Stable	Current production version. All new features are added here.
`v2`	🚧 Preview	Opt-in beta. Breaking changes possible. Contact support to join.
`v0`	❌ Deprecated	Sunset date: 2026-09-01. Migrate to `v1` before that date.

Deprecated since version 0.9: /v0/ endpoints are deprecated and will be removed on 2026-09-01. All v0 paths have direct equivalents in v1.

Base URLs

All API requests must be made over HTTPS. Plain HTTP requests are rejected with 301 Moved Permanently.

Environment	Base URL
Production	`https://api.blueround.com/v1`
Staging	`https://api.blueround.dev/v1`
Local mock	`http://localhost:4010/v1` (run `npx @stoplight/prism-cli mock openapi.yaml`)

Tip

Use the staging environment for integration testing. It mirrors production data structures but operates on an isolated dataset that resets nightly at 02:00 UTC.

Authentication

Every request must include a valid Bearer token in the Authorization header:

GET /v1/users HTTP/1.1
Host: api.blueround.com
Authorization: Bearer <your_access_token>
Accept: application/json

Tokens are obtained via the OAuth 2.0 flow described in OAuth 2.0 Authentication. Access tokens expire after 3 600 seconds (1 hour). Use the refresh token endpoint to obtain a new one without re-authenticating.

Request Format

Header	Required value
`Content-Type`	`application/json` for `POST`, `PUT`, and `PATCH` requests.
`Accept`	`application/json` (optional but recommended).
`Authorization`	`Bearer <access_token>` — required on all endpoints.
`X-Request-ID`	Optional UUID. Echoed back in the response; useful for tracing.

All request bodies must be valid JSON. Dates and timestamps follow ISO 8601 (e.g., 2026-04-30T09:00:00Z). Numeric IDs are strings prefixed by resource type (e.g., usr_98765).

Response Format

Every response body is a JSON object. Success responses wrap the primary payload in a data key. Error responses use the error key:

{
  "data": { /* primary payload */ },
  "meta": {
    "request_id": "req_a1b2c3",
    "version":    "1.2.0"
  }
}

{
  "error": {
    "code":    "RESOURCE_NOT_FOUND",
    "message": "User usr_00000 does not exist.",
    "docs":    "https://docs.blueround.com/api/errors#RESOURCE_NOT_FOUND"
  }
}

See Errors & Status Codes for the complete list of error codes and handling guidance.

Pagination

List endpoints return paginated results using cursor-based pagination. Pass limit and offset query parameters to control page size and starting position.

GET /v1/users?limit=25&offset=50 HTTP/1.1

The response meta object includes total, limit, and offset fields so clients can calculate whether further pages exist:

{
  "data": [ /* array of resource objects */ ],
  "meta": {
    "total":  1250,
    "limit":  25,
    "offset": 50
  }
}

Note

Maximum limit is 100. Requests exceeding this are clamped to 100 without returning an error.

Rate Limiting

The API enforces per-token rate limits to ensure fair usage.

Default rate limits
Plan	Requests / minute	Burst (requests / second)
Free	60	10
Pro	600	50
Enterprise	Custom	Custom

When a rate limit is exceeded, the API returns 429 Too Many Requests. Inspect the response headers to determine when to retry:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the window resets.
`Retry-After`	Seconds to wait before retrying (present on 429 responses only).

Warning

Automated scripts that ignore Retry-After will have their tokens temporarily suspended after repeated violations.

SDK & Client Libraries

Official SDKs are available for the most common languages. All SDKs handle token refresh, retries, and pagination automatically.

Language	Install	Repository
Python	`pip install blueround-sdk`	github.com/blueround/python-sdk
Node.js	`npm install @blueround/sdk`	github.com/blueround/node-sdk
Go	`go get github.com/blueround/go-sdk`	github.com/blueround/go-sdk
Java	Maven: `com.blueround:sdk:1.2.0`	github.com/blueround/java-sdk

Service Status

Real-time uptime and incident history are published at status.blueround.com. Subscribe to the status page to receive email or webhook notifications for incidents and scheduled maintenance.

Contact & Support

Developer portal	developer.blueround.com
Help center	help.blueround.com
Support tickets	support.blueround.com/tickets
Status page	status.blueround.com

For critical production issues, include your X-Request-ID and the affected token's client_id when opening a support ticket — this allows the support team to locate your request in server logs immediately.