hireburst api surface.

Remote MCP endpoint

The MCP contract is exposed at https://hireburst.com/api/mcp. Remote clients should treat it as an OAuth-protected MCP 2.1 resource. Server-side MCP clients can mirror the same tool calls at https://hireburst.com/api/mcp/bearer with a bearer token.

{
  "jsonrpc": "2.0",
  "id": "hb-init-01",
  "method": "initialize",
  "params": {
    "protocolVersion": "2.1",
    "clientInfo": {
      "name": "your-agent",
      "version": "1.0.0"
    }
  }
}

Supported tool contract

The MCP surface exposes the same product capabilities as REST, but as callable tools for agent runtimes that need to reason, call, observe, and adapt inside a workflow.

MCP role-plan call

Use MCP when an agent should decide the next hiring move, call hireburst tools, and feed the output into another agent or human review step.

{
  "jsonrpc": "2.0",
  "id": "hb-call-42",
  "method": "tools/call",
  "params": {
    "name": "hireburst.role_plan.create",
    "arguments": {
      "company": "BlockHome AI",
      "role": "Account Manager",
      "team_size": 34,
      "growth_goal": "scale customer organization before enterprise expansion",
      "must_have_signals": [
        "real estate workflow fluency",
        "adoption-risk saves",
        "expansion judgment",
        "product feedback synthesis"
      ]
    }
  }
}

MCP authorization failures

The MCP endpoint currently fails closed. Expect 401 Unauthorized, a WWW-Authenticate header, and a JSON-RPC error payload.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="hireburst-mcp",
  error="invalid_token",
  resource_metadata="https://hireburst.com/.well-known/oauth-protected-resource/api/mcp"

{
  "jsonrpc": "2.0",
  "id": "hb-call-42",
  "error": {
    "code": -32001,
    "message": "Authorization failed",
    "data": {
      "mcp_version": "2.1",
      "authorization": "oauth"
    }
  }
}

REST exposes the same hiring system without MCP.

Use REST when you are building a product integration: ATS syncs, internal recruiting dashboards, custom approval flows, BI pipelines, or an app that needs normal HTTP resources. REST uses bearer API keys generated at hireburst.com/manage/api-keys.

{
  "surface": "rest",
  "same_capabilities_as": "mcp",
  "resources": [
    "role_plan",
    "target_map",
    "interview_loop",
    "calibration_update"
  ]
}

REST authorization

REST requests use bearer API keys and do not use MCP envelopes, JSON-RPC IDs, or MCP method names. Missing, expired, or incorrect tokens receive 401 as invalid API tokens.

POST /api/role_plan/ HTTP/1.1
Host: hireburst.com
Authorization: Bearer hb_live_...
Content-Type: application/json

REST endpoint map

The REST API is resource-oriented. Create a plan, retrieve it later, list submitted requests with cursor pagination, and generate the supporting target map, interview loop, and calibration update as separate artifacts.

Role-plan submissions

Submission lists use cursors instead of page numbers so integrations can resume safely as new hiring requests arrive.

GET /api/role_plan/submissions?limit=25&cursor=sub_01jz9a9c3z&status=submitted HTTP/1.1
Host: hireburst.com
Authorization: Bearer hb_live_...

Expected response

{
  "object": "list",
  "data": [
    {
      "id": "rps_01jz9b2d4a",
      "role": "Account Manager",
      "company": "BlockHome AI",
      "status": "submitted",
      "created_at": "2026-07-07T18:40:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "sub_01jz9c8nr4",
    "has_more": true,
    "limit": 25
  }
}

Shared object types

These object shapes repeat across endpoint responses so client libraries can share models across REST and MCP tool results.

REST authorization failures

The REST endpoints also fail closed. They return normal JSON errors instead of JSON-RPC envelopes.

{
  "error": {
    "type": "authorization_error",
    "code": "invalid_token",
    "message": "Invalid API token."
  }
}