BelumindScience

API reference

Agent tooling

Every capability is published as an MCP server, so an agent can discover it, read its schema, and call it without glue code. Point Claude, or any MCP-capable client, at the endpoint and document processing and inference become tools it already knows how to use.

REST server

https://api.belumind.com

MCP server

https://mcp.belumind.com

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.

mcp:read
Header
Authorization: Bearer blm_live_7f3c…
Content-Type: application/json
GET/v1/mcp/toolsmcp:read

List the tools a key can reach

Returns the tool schemas an MCP client would discover at connect time, filtered to the scopes on the calling key. Useful for checking what an agent will actually be able to do before you hand it a key.

MCP toollist_tools

Path & query parameters

capabilitystringoptional
Filter to one capability, e.g. `data-processing`. Omit for every tool the key can reach.

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/mcp/tools \
  -H "Authorization: Bearer $BELUMIND_API_KEY"

Response

application/json200 OK
{
  "tools": [
    {
      "name": "parse_document",
      "capability": "data-processing",
      "description": "Parse a document at a URL into structured blocks with tables preserved.",
      "input_schema": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "fast",
              "accurate"
            ]
          }
        },
        "required": [
          "url"
        ]
      }
    },
    {
      "name": "predict",
      "capability": "inference",
      "description": "Run a single synchronous prediction against a named model version.",
      "input_schema": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "input": {
            "type": "object"
          }
        },
        "required": [
          "model",
          "input"
        ]
      }
    }
  ]
}

Try it

Send a request

Sample mode
GET https://api.belumind.com/v1/mcp/tools

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.