API reference

Overview

Every MCP tool has a REST equivalent at https://api.reason8.io/mcp/tools/<tool_name>. The request and response shapes are identical to the MCP tools — the REST API is the path for dashboards, scripts, and other non-agent integrations that cannot speak MCP. For agent loops, use the MCP tools directly.

Contract. The reason8_research_* REST shapes mirror the live MCP tools documented on reason8_research_*. The reason8_ask REST path follows the same pattern and is documented here as the contract the implementation matches.

Authentication

All requests use HTTP Bearer auth with a token issued from the portal Integrations page.

Header: Authorization: Bearer r8_mcp_xxx

Scopes (all tokens have all three today):

• reason8_research:run — start, continue, cancel runs
• reason8_research:read — read run status
• reason8_research:cancel — cancel runs

Token format: r8_mcp_<url-safe random>. The full secret is shown once in the portal — store it immediately. Reason8 keeps only a salted hash and a short lookup prefix server-side.

Endpoints

reason8_ask (sync)

curl -X POST https://api.reason8.io/mcp/tools/reason8_ask \
  -H "Authorization: Bearer $REASON8_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact": {
      "content": "Onboarding copy: <paste here>",
      "goal": "Decide whether this lands with first-time admins",
      "artifact_type": "text"
    },
    "audience": "Mid-market ops leads evaluating procurement",
    "grounding": "auto"
  }'

Returns the PanelResponse documented on reason8_ask — reactions[] (each with a verified/inferred split) plus a synthesis block.

reason8_research_start (async)

curl -X POST https://api.reason8.io/mcp/tools/reason8_research_start \
  -H "Authorization: Bearer $REASON8_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact": "Launch announcement copy: <paste here>",
    "research_goal": "Decide if framing lands with technical buyers",
    "target_audience": "Mid-market CTOs evaluating AI tooling"
  }'

Returns immediately with a run_id. Poll reason8_research_status, then fetch the memo with reason8_research_get_result. The full parameters, status enum, response shapes, rate limits, and troubleshooting for the async workflow are documented on reason8_research_*.

Rate limits

Start quotas and the concurrent-runs cap enforce on reason8_research_start; status, continue, and cancel are not rate-limited. See reason8_research_* → Rate limits & concurrency for the limits table and the two error families (429 rate_limited and 409 concurrent_run_limit_exceeded).