Research Project This is a free AI research project. No warranties, SLAs, or company associations. Learn more

AI Discovery

Built for machines first.
Readable by humans too.

The Machine-Native Interface is a layered discovery stack that lets any AI agent find, understand, and operate BrainstormRouter without human help. From llms.txt to self-awareness endpoints — every surface is machine-optimized.

Discovery Stack

Seven Layers of Machine Discoverability

L1

llms.txt

Concise AI-readable site map. 3-step agent bootstrap sequence. Served at GET /llms.txt and brainstormrouter.com/llms.txt.

L2

llms-full.txt

Complete API reference with every endpoint, parameter, and response schema. Auto-generated from source code on every build.

L3

Agent Playbook

Step-by-step operational guide at brainstormrouter.com/llms-agent-playbook.txt. Covers registration, authentication, model selection, memory, and MCP tools.

L4

agents.json

Agent capability manifest at .well-known/agents.json. Declares supported protocols, auth methods, and tool namespaces.

L5

ai-plugin.json

OpenAI plugin manifest at .well-known/ai-plugin.json. Compatible with ChatGPT plugins, Copilot, and other plugin-aware agents.

L6

GET /v1/discovery

Authenticated endpoint returning full API topology: available routes, model count, MCP tool count, auth methods, and feature flags.

L7

GET /v1/self

Self-awareness endpoint. Returns the agent's own identity, health, budget remaining, configuration, and actionable suggestions.

Bootstrap Flow

How an Agent Finds and Operates BR

  1. Fetch llms.txt — Agent reads the site map, finds the bootstrap URL, self endpoint, and MCP connection info.
  2. Register via POST /v1/register — Receives API key, tenant ID, and claim URL. Zero human intervention required.
  3. Call GET /v1/self — Learns its own identity, available budget, rate limits, and enabled features.
  4. Call GET /v1/discovery — Maps full API topology: routes, models, tools, auth methods.
  5. Connect MCP — Uses the MCP endpoint from llms.txt to access 65 governed tools.
  6. Operate — Routes requests through /v1/chat/completions. Every response includes RFC 8631 Link headers pointing back to the discovery stack.
RFC 8631

Every Response Points Back to Docs

Every API response includes machine-readable Link headers. Agents can discover the OpenAPI spec, documentation, and status page from any response — even error responses.

Link: <https://api.brainstormrouter.com/openapi.json>; rel="describedby"; type="application/json" Link: <https://brainstormrouter.com/llms.txt>; rel="describedby"; type="text/plain" Link: <https://docs.brainstormrouter.com>; rel="help"
Self-Awareness

/v1/self — Know Thyself

The self endpoint returns everything an agent needs to understand its own state: identity, health, budget, configuration, and actionable suggestions.

{ "identity": { "agent_id": "agent_7f3a...", "tenant_id": "d360e933-...", "role": "agent", "trust_level": "standard" }, "budget": { "daily_limit": 5.00, "daily_spent": 1.23, "remaining": 3.77 }, "capabilities": { "models": 321, "mcp_tools": 65, "memory_enabled": true }, "suggestions": [ "Budget 75% consumed — consider auto:floor for remaining tasks" ] }

Read the Agent Playbook

The complete operational guide for AI agents integrating with BrainstormRouter.

Agent Playbook llms.txt