Skip to main content

​
Overview

The BitRobot API allows you to interact with the BitRobot platform, including event tracking, task management, and points distribution.

OpenAPI Specification

View the complete OpenAPI specification file

​
Authentication

All requests require authentication using an API key. You can generate API keys from the API Keys page in your subnet’s settings on the BitRobot dashboard — see Get and manage your API key for creating, scoping, and revoking keys. Include your API key in the Authorization header:
Your API key starts with brb_ and is only shown once when created — store it securely.

​
Identifiers

All resource identifiers in the API use the ULID format (Universally Unique Lexicographically Sortable Identifier). ULIDs are 26-character strings like: 01ARZ3NDEKTSV4RRFFQ69G5FAV

​
Base URLs

  • Production: https://api.bitrobot.ai
  • Staging: https://api-stage.bitrobot.ai

​
Event Types

The API supports six types of events: In addition to event ingestion, the integration API also provides subnet-scoped read endpoints for balances, points history, and conversion history, and a Connect endpoint for confirming a user’s subnet wallet.

​
Retries and idempotency

All mutating endpoints (POST requests) accept an optional Idempotency-Key header for safe retries:
  • The first request with a given key is processed normally and its response is cached.
  • A retry with the same key and identical payload replays the cached response (the reply includes Idempotency-Replayed: true).
  • A retry with the same key and a different payload returns 409 Conflict.
  • A retry while the first request is still in flight returns 409 Conflict with a Retry-After header.
  • Keys expire after a fixed TTL; reuse a fresh key per logical operation.
This is independent of the per-event client_ref field, which deduplicates points_grant and points_revoke server-side regardless of the header. Use Idempotency-Key for transport-level retries (network failures, timeouts) on any event type, and client_ref to bind a grant or revocation to a record in your own system.

​
Error Handling

The API uses standard HTTP status codes and returns error responses in JSON format:
Common error codes:
  • 401 - Unauthorized (invalid or missing API key)
  • 422 - Unprocessable Entity (invalid event data or unknown event type)