API Reference 🛠️

The OBrain API is the bridge between the Sovereign Engine and the storefront/fulfillment layers. All endpoints are secured and requires institutional authorization.

Authentication

Authentication is handled via the x-api-key header (for client-side/frontend tools) or via the HMAC Handshake Protocol (for server-to-server node communication).

📦 Products & Discovery

GET `/api/products`

Retrieves the curated catalogue of high-velocity arbitrage opportunities.

Query Parameters:

Parameter	Type	Description
`page`	Integer	Pagination index (starts at 1).
`limit`	Integer	Max results per page (max 100).
`category`	String	Filter by product niche.

Response:

{
  "products": [
    {
      "id": "prod_8329x",
      "name": "Smart Vision Hub v4",
      "price": 29.50,
      "roi": 45.2,
      "velocity": 9.2,
      "category": "Electronics"
    }
  ]
}

GET `/api/categories`

Returns a list of all active niches and the count of validated products.

🤖 Gap Intelligence

GET `/api/gap-intelligence/trends`

Provides raw signals of identified "Anticipation Gaps" (15-45 days window).

POST `/api/v1/risk/analyze`

Submits a product SKU or URL for real-time risk/ROI analysis through the Waterfall Pipeline.

🏛️ Institutional Management

GET `/api/decision-metrics/stats`

Retrieves global performance KPIs for the operational nodes.

GET `/api/user/api-key`

Returns the active institutional access key for the authenticated node.

Error Codes

Code	Meaning
`401 Unauthorized`	Invalid API Key or expired HMAC signature.
`403 Forbidden`	Node ID does not have permissions for this niche.
`429 Too Many Requests`	Request volume exceeds the hardware thread capacity.
`503 Service Unavailable`	Local Engine node is offline or unreachable via Tunnel.

API Reference (v1.0)