Common API Conventions

Confidential. Do not share without explicit permission.

The RSL Platform Common API Conventions define the common request, response, authentication, versioning, pagination, and error-handling rules shared across RSL Platform APIs.

Introduction

The RSL Platform exposes multiple APIs for different participants and workflows. To keep those APIs predictable and consistent, this document defines the common conventions that apply across the platform.

Environments

RSL Platform APIs are provided in separate sandbox and production environments.

These environments are fully isolated from each other:

• API credentials issued for one environment are not valid in the other environment.
• Requests made in one environment do not affect resources or workflows in the other environment.
• Data returned by the sandbox environment is test data and is not a production record.
• Data submitted to the sandbox environment does not affect production reporting, invoicing, settlement, or other production workflows.

Each domain API specification defines the base URLs for its sandbox and production environments.

Base URLs

Each RSL Platform API defines its own base URL. Base URLs follow this general pattern:

• Production: https://api.rslcollective.org/{api}/{version}
• Sandbox: https://sandbox.api.rslcollective.org/{api}/{version}

Where:

• {api} identifies the API surface, for example partner or license
• {version} identifies the major API version, for example v1

All requests must be made over HTTPS, and insecure requests are rejected.

API versioning

RSL Platform APIs are versioned through the URL path.

For example:

https://api.rslcollective.org/license/v1

Compatible improvements may be introduced within an API version. Changes that affect compatibility are introduced only in a new API version.

Examples of compatible changes include:

• adding new endpoints
• adding new optional request parameters
• adding new optional response fields
• clarifying behavior without changing the wire contract

Examples of incompatible changes include:

• removing or renaming existing fields
• changing field meanings
• changing validation behavior in a way that breaks previously valid requests
• changing response structures incompatibly

Clients SHOULD target a specific API version and MUST NOT assume compatibility across major API versions.

Authentication

RSL Platform APIs use bearer token authentication.

Clients must provide an API Secret Key in the Authorization header:

Authorization: Bearer rsl__4eC39HqLyjWDarjtT1zdp7dc

API Secret Keys are environment-specific and are issued separately for sandbox and production.

A client may have multiple active API Secret Keys at the same time to support credential rotation and separation between different internal systems, environments, or deployment workflows.

If an API Secret Key is missing, invalid, expired, or revoked, the API returns 401 Unauthorized.

If credentials are valid but the authenticated caller is not authorized to perform the requested operation or access the requested resource, the API returns 403 Forbidden.

Request conventions

HTTPS

All API requests must use HTTPS.

Content types

Requests with a body must use:

Content-Type: application/json

unless the applicable API specification explicitly defines a different request format.

JSON responses are returned with:

Content-Type: application/json

Character encoding

JSON request and response bodies must be UTF-8 encoded.

Unknown fields

Unless an endpoint explicitly states otherwise, clients must not send unknown top-level request fields. Requests containing unknown fields may be rejected with 400 Bad Request, and clients must ignore unknown response fields unless the applicable API specification explicitly states otherwise.

Response conventions

Unless otherwise specified by the applicable API specification, successful responses return a 2xx HTTP status and a JSON response body.

Some successful operations may return an empty response body when defined by the applicable domain API specification, and some responses may include additional headers beyond those defined in this document.

Timestamps and date formats

Timestamps

Unless otherwise specified, timestamps are UTC Unix epoch seconds.

Example:

{
  "created": 1774224000
}

Calendar dates

Where an API field represents a date without a time component, the value must use the YYYY-MM-DD format.

Example:

{
  "period_start": "2026-03-01"
}

Time zone interpretation

Unless otherwise specified, all dates and timestamps are interpreted in UTC.

Request identifiers

Every API response includes a unique request identifier in the Request-Id response header.

Example:

HTTP/1.1 200 OK
Request-Id: req_8f3a71c9a4c24d6f
Content-Type: application/json

Clients should log the Request-Id value for operational troubleshooting and support, and when contacting RSL Collective support, clients should include the Request-Id value for the relevant request.

Idempotent requests

RSL Platform APIs support idempotent request semantics for operations that create resources or begin asynchronous processing workflows.

Clients may include an Idempotency-Key header when calling an endpoint that supports idempotency:

Idempotency-Key: 8f1cbe3e-61e2-4f6e-b42a-0d0bb3a1c24d

If the same request is retried with the same idempotency key, the API returns the original response rather than creating a duplicate resource or starting a duplicate workflow.

Idempotency applies only when:

• the endpoint supports idempotency
• the retried request is materially identical to the original request associated with that idempotency key

If a client reuses an idempotency key with a different request payload for the same endpoint, the API may reject the request with 409 Conflict or 400 Bad Request, as defined by the applicable API specification.

Clients should use idempotency for any retriable operation that creates a resource or initiates a workflow.

Pagination

Endpoints that return lists of objects use cursor-based pagination unless otherwise specified.

Pagination query parameters

Name	Type	Required	Description
limit	integer	No	Maximum number of objects to return. Default and maximum values are defined by the applicable API specification.
starting_after	string	No	Identifier of the last object from the previous page.

Pagination response fields

Name	Type	Description
has_more	boolean	Whether additional objects are available after the current page.

Pagination semantics

• Objects are returned in a deterministic order defined by the endpoint.
• Unless otherwise specified, list endpoints return objects in reverse chronological order.
• To retrieve the next page, the client provides the identifier of the last object from the current page as starting_after.
• If has_more is false, no additional pages are available.
• If starting_after does not identify an object in the current result set, the API returns 400 Bad Request with an invalid_request error.

Rate limiting

Standard rate limits apply to RSL Platform APIs.

If a client exceeds an applicable limit, the API returns:

• 429 Too Many Requests

Responses that return 429 MAY include a Retry-After header indicating how long the client should wait before retrying, and clients should implement backoff and retry logic for 429 responses.

The applicable API specification may define more specific rate limits or endpoint-specific limits.

Errors

RSL Platform APIs use conventional HTTP status codes and return a JSON error object.

Standard error format

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter."
}

The error value is stable and intended for programmatic handling.

The error_description value is human-readable and is not guaranteed to be stable.

Standard HTTP status usage

Status	Meaning
400	Invalid request, including missing, malformed, or unsupported parameters
401	Missing, invalid, expired, or revoked API key
403	Authenticated but not authorized
404	Resource not found or not accessible to the caller
409	Conflict
429	Rate limit exceeded
500	Internal server error
503	Service temporarily unavailable

The applicable API specification MAY define narrower meanings or additional examples for a specific endpoint or resource.

Standard API error codes

Error code	Meaning
invalid_request	The request is missing required input, contains malformed input, or violates request validation rules
unauthorized	The request did not include valid authentication credentials
forbidden	The authenticated caller is not authorized to perform the requested operation
not_found	The requested resource does not exist or is not accessible to the caller
conflict	The request conflicts with the current state of the target resource or workflow
rate_limited	The request exceeded an applicable rate limit
limit_exceeded	The request exceeds an applicable operational limit
internal_error	The request failed due to an internal server error
service_unavailable	The service is temporarily unavailable

Standard API error catalog

This catalog defines the machine-readable error codes used by this specification. API error responses use the generic Error schema defined in the OpenAPI definition.

catalog_type: rsl.common_api.error_catalog
catalog_version: 1.0.0-beta

api_errors:
  - code: invalid_request
    category: api
    retryable: false
    description: The request is missing required input, contains malformed input, or violates request validation rules.

  - code: unauthorized
    category: api
    retryable: false
    description: The request did not include valid authentication credentials.

  - code: forbidden
    category: api
    retryable: false
    description: The authenticated caller is not authorized to perform the requested operation.

  - code: not_found
    category: api
    retryable: false
    description: The requested resource does not exist or is not accessible to the caller.

  - code: conflict
    category: api
    retryable: false
    description: The request conflicts with the current state of the target resource or workflow.

  - code: rate_limited
    category: api
    retryable: true
    description: The request exceeded an applicable rate limit. Retry after the interval indicated by the Retry-After header.

  - code: limit_exceeded
    category: api
    retryable: false
    description: The request exceeds an applicable operational limit.

  - code: internal_error
    category: api
    retryable: true
    description: The request failed due to an internal server error.

  - code: service_unavailable
    category: api
    retryable: true
    description: The service is temporarily unavailable.

Retries

Clients should implement retry logic for transient failures, including:

• network interruptions
• 429 Too Many Requests
• 500 Internal Server Error
• 503 Service Unavailable

Requests that create resources or initiate workflows should use idempotency when retried.

Changelog

• 2026-03-27: Initial draft.