BelumindScience

API reference

Running it

Keys you can scope and rotate, usage you can see, limits that fail predictably rather than silently, and deployment that can sit in our infrastructure or inside yours when the data cannot leave.

REST server

https://api.belumind.com

MCP server

https://mcp.belumind.com/operations

Authentication

Every request carries a bearer token. Keys are scoped — an endpoint returns 403 if the calling key lacks the scope named in its reference entry, so an agent can be handed a key that reaches exactly one tool and nothing else.

MCP clients pass the same token as a bearer credential when connecting to the server URL above.

account:read
Header
Authorization: Bearer blm_live_7f3c…
Content-Type: application/json
GET/v1/usageaccount:read

Read usage against quota

Current period usage broken down by capability, with the quota and reset time. The same numbers the rate limiter is working from, so a client can back off before it starts getting 429s.

MCP toolget_usage

Path & query parameters

period"current" | "previous"optional
Billing period to report. Defaults to `current`.

Responses

  • 200 OKSuccess. Body as shown in the example.
  • 400 Bad RequestThe request body failed validation. The response names the offending field.
  • 401 UnauthorizedMissing, malformed, or revoked API key.
  • 403 ForbiddenThe key is valid but lacks the scope this endpoint requires.
  • 429 Too Many RequestsRate limit exceeded. `Retry-After` carries the seconds to wait; usage is readable from /v1/usage.
  • 500 Internal Server ErrorSomething failed on our side. Requests are idempotent by `Idempotency-Key`, so a retry is safe.

Request

curl -X GET https://api.belumind.com/v1/usage \
  -H "Authorization: Bearer $BELUMIND_API_KEY"

Response

application/json200 OK
{
  "period": "current",
  "resets_at": "2026-09-01T00:00:00Z",
  "usage": {
    "data-processing": {
      "pages_processed": 41208,
      "quota": 100000
    },
    "inference": {
      "predictions": 883104,
      "quota": 2000000
    }
  },
  "rate_limit": {
    "requests_per_minute": 600,
    "remaining": 587
  }
}

Try it

Send a request

Sample mode
GET https://api.belumind.com/v1/usage

The platform is in early access, so this console returns the documented example response rather than calling a live endpoint. Ask us for a key and the same console starts issuing real requests.

Errors

Errors use conventional HTTP status codes and always carry a machine-readable code alongside the human-readable message, so a client can branch on the former and log the latter. Every request is idempotent by Idempotency-Key, which makes retrying a 5xx safe.

Error shape4xx / 5xx
{
  "error": {
    "code": "invalid_parameter",
    "message": "`min_confidence` must be between 0 and 1.",
    "param": "min_confidence",
    "request_id": "req_4d91c0b7"
  }
}

Ready to call it for real?

The console returns documented examples while the platform is in early access. Tell us what you are building and we will get you a key.