Skip to main content

​
Overview

All access to the Boomerang Developer API is via HTTPS at:
  • https://gateway.bmrg.app/vN/
The API is:
  • GET-only
  • JSON-only
  • Versioned in the URL
  • Designed for predictable, idempotent read operations
This page describes how requests must be structured and how responses are formatted, so that clients behave consistently across all modules.

​
Transport and protocol

  • Only HTTPS is supported; plain HTTP is not accepted.
  • All requests must target a versioned path (for example, /v1/, /v2/).
  • The API is stateless: each request is authenticated and processed independently.

​
Header requirements

​
Header requirements summary

Required headers:
  • Authorization: Bearer [token] – Authentication credential for the server-scoped token.
Optional headers (recommended):
  • Accept: application/json – Recommended for and future compatibility.
  • User-Agent: ServerID-IntegrationName/Version (AuthorDiscordUserID) – Recommended for client identification, troubleshooting, and abuse detection.
  • X-Request-Id – Client-provided , echoed in responses if supplied; otherwise server-generated.
Rejected headers:
  • Content-Type – Not applicable for GET-only endpoints.
    • If a client sends a Content-Type header, the request is rejected with 400 Bad Request and VALIDATION_FAILED.

​
Request format

Key expectations for requests:
  • Only HTTP GET is supported.
  • Request parameters are supplied via:
    • Path segments (for identifiers); and
    • Query parameters (for filtering, pagination, and options).
  • Request bodies are not accepted and are ignored or rejected.
Behaviour:
  • Requests that use unsupported methods (such as POST, PUT, DELETE) are rejected.
  • Requests with malformed query parameters are treated as validation failures, as described on the Errors page.

​
Response format

​
Content type and encoding

All successful responses:
  • Use content type: application/json; charset=utf-8.
  • Are encoded as standard JSON objects or arrays.
  • May be compressed with gzip if the client sends Accept-Encoding: gzip.
Clients should:
  • Send Accept-Encoding: gzip if they can handle compressed responses.
  • Always check the Content-Type header before parsing the response body.

​
Envelope structure

Non-paginated endpoints return a wrapped response: 
{
  "data": {
    "id": "example-1"
    // Resource fields…
  }
}
Paginated endpoints follow the structure described on the Pagination page, typically:
  • A top-level items array; and
  • A pagination object containing page metadata.

​
Timestamps and common fields

Across the API:
  • Timestamps are represented as Unix epoch timestamps in milliseconds.
  • Identifier and field conventions are documented per endpoint.
Clients must not assume implicit semantics for fields that are not documented.

​
Error responses

All non-2xx responses:
  • Use a standard JSON error format with fields such as status, code, http_status, timestamp, trace_id, and details.
  • Use HTTP status codes consistent with the Errors documentation.
For full details, including error codes and structure, see the Errors page. trace_id in the error body is the primary identifier for server-side investigation. X-Request-Id, where supplied, can be used as an additional reference in your own logs.

​
Example requests

The examples below illustrate a typical authenticated GET request using the required headers and JSON response format. 
curl -X GET "https://gateway.bmrg.app/vN/example/resource?id=example-1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json" \
  -H "User-Agent: 123456789012345678-MyIntegration/1.0 (123456789012345678)" \
  -H "X-Request-Id: 9d2f7a1c-4f0a-4a71-9dd2-7fd9c1a3b210" \
  -H "Accept-Encoding: gzip"
Example success response (non-paginated): 
{
  "data": {
    "id": "example-1",
    "name": "Example Resource",
    "created_at": 1763205835591
  }
}

​
Client behaviour expectations

To ensure stable and predictable integrations:
  • Check HTTP status first Always inspect the status code before using the response body. Treat 4xx and 5xx responses as failures that require handling.
  • Treat requests as idempotent All GET endpoints are designed to be . Do not rely on undocumented side effects.
  • Use back-off and retry responsibly
    • Retry only idempotent GET requests, and only when appropriate (for example, transient network issues or 5xx errors).
    • Respect rate limits and error guidance. Do not retry in tight loops.
  • Log identifiers Log X-Request-Id (your ID) and trace_id (server ID from error responses) for all calls. This enables reliable troubleshooting and correlation with Boomerang’s logs if needed.
  • Stay within documented patterns Avoid sending unsupported headers, HTTP methods, or bodies. Behaviour is only guaranteed for documented usage.
Following these conventions ensures your integration behaves consistently with the rest of the ecosystem and remains compatible as the API evolves.