HTTP API transport

#Overview

The HTTP API is one of two transports for ONBF Tools. It exposes the exact same registry as MCP: same credentials, scopes and behavior, with a simpler request/response wire format.

Every tool is one POST, and the response body is the tool's structured result — no envelope to unwrap. That means a response can be handed straight back into an OpenAI or LangChain function-calling loop.

#Authentication

Send an ONBF credential as a standard bearer token: Authorization: Bearer <token>. The credential decides which tools you can call.

# In-message auth mode: authenticate with your STATIC agent credential
# and pass the run's session token in the X-ONBF-Session header.
# (Over MCP the same value travels as a "session" tool argument — over HTTP it's
# a header, so the request body stays exactly the tool's documented schema.)
curl "https://onbf.ai/api/passport/v1/tools/post_reply" \
  -H "Authorization: Bearer onbf_agent_YOUR_CREDENTIAL" \
  -H "X-ONBF-Session: onbf_sess_FROM_THE_USER_MESSAGE" \
  -H "Content-Type: application/json" \
  -d '{"message":"Working on it…"}'

#Calling a tool

Tool names are the canonical snake_case ONBF Tool identifiers, with a 1:1 mapping to MCP. A tool with no required arguments accepts no body or an empty JSON object. See ONBF Tools for shared contracts.

# One tool = one POST. The response IS the tool's structured result.
curl "https://onbf.ai/api/passport/v1/tools/get_identity" \
  -H "Authorization: Bearer onbf_sess_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

# → {"userId":"…","displayName":"Ada Lovelace","handle":"ada", … }

# Arguments go in the body, exactly as the tool documents them:
curl "https://onbf.ai/api/passport/v1/tools/post_reply" \
  -H "Authorization: Bearer onbf_sess_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Here is your summary…"}'

// A complete run handler with no MCP client — plain fetch.
// The webhook already handed you mcp.token; use it as the bearer.
const BASE = "https://onbf.ai/api/passport/v1";

async function callTool(token, name, args = {}) {
  const res = await fetch(`${BASE}/tools/${name}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(args),
  });

  // Errors are { error: { code, message } }, discriminated by status.
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${name} failed [${error.code}]: ${error.message}`);
  }
  return res.json(); // the bare structured result
}

export async function onRunCreated(event) {
  const token = event.mcp.token;
  const { displayName } = await callTool(token, "get_identity");
  const { entries } = await callTool(token, "get_conversation_history", {
    limit: 50,
  });

  await callTool(token, "post_reply", {
    message: `Hi ${displayName} — I read the ${entries.length} prior turns…`,
    idempotencyKey: `reply:${event.run.id}:1`,
  });
}

#Discovery

GET /tools is the HTTP equivalent of MCP's tools/list: it returns exactly what your credential may call, filtered by scope and by the agent's connector allowlist. A tool that isn't listed returns 404 if you call it — unavailable and non-existent are deliberately indistinguishable.

# Exactly the tools YOUR token can call, each with its JSON Schema.
curl "https://onbf.ai/api/passport/v1/tools" \
  -H "Authorization: Bearer onbf_sess_YOUR_TOKEN"

# → {
#     "principal": { "kind": "session", "scopes": ["identity:read", …] },
#     "tools": [
#       {
#         "name": "post_reply",
#         "title": "Post reply",
#         "path": "/api/passport/v1/tools/post_reply",
#         "requiredScopes": ["conversation:write"],
#         "inputSchema": { "type": "object", "properties": { … } }
#       }, …
#     ]
#   }

# The full contract, no token required — point Swagger/Postman/codegen at:
#   https://onbf.ai/api/passport/v1/openapi.json

#Errors & rate limits

Failures return { error: { code, message } } with a meaningful HTTP status. code is stable and machine-readable — branch on it rather than parsing message.

• Rate limit: 120 requests per 60s per token, shared with MCP traffic on the same credential.
• Tracing: every explicit API response carries X-ONBF-Request-Id and X-ONBF-Duration-Ms — include the request id when reporting an issue.
• Retry: retry 429 after Retry-After; retry a 500 once with backoff. Do not retry validation, auth, missing-tool or cancelled-run errors unchanged.
• Auditing: executed HTTP tool calls are audited. Bound session calls also stream tool activity into the user's live chat, exactly like MCP calls.