API

API Reference

One JSON-in / JSON-out service. Call it directly or through the MCP, Tavily, and OpenAI-compatible shims.

Authentication

Every request takes a bearer token. The base URL for all endpoints is:

Authorization: Bearer $INCORD_KEY
Base URL: https://api.incord.ai

Quickstart

Send an objective, get ranked real-time context back:

curl https://api.incord.ai/v1/context \
  -H "Authorization: Bearer $INCORD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "What is bitcoin analysis?",
    "top_k": 5,
    "rerank": true,
    "filters": { "asset_class": "crypto", "max_age_hours": 24 }
  }'

Retrieval

POST/v1/context

Embed a query and retrieve the top-K most relevant nodes, cross-encoder reranked. Returns a confidence object with did-you-mean hints. Supports six filter dimensions: symbol, asset_class, categories, node_types, tiers, max_age_hours.

POST/v1/temporal/analyze

Trend and spike detection over numeric signals. Returns { trend, current, baseline, spike_ratio, is_spike, count } from an in-memory ring buffer, no disk I/O on the read path.

POST/v1/ingest

Push content into the knowledge graph. Normalizes category and asset_class to canonical forms; snapshot uploads also feed the temporal bridge.

Discovery

GET/v1/filters/values

Single-shot enumeration of every value the /v1/context filters accept, asset classes, categories, node types, tiers, and the live symbol universe.

GET/v1/tools

OpenAI-format function-calling descriptors for the brain's tools.

Asset Registry

GET/v1/registry/asset

List all registered assets.

GET/v1/registry/asset/{canonical}

Fetch a single asset entry.

POST/v1/registry/asset

Create a new asset entry. Auto-resyncs the heartbeat schedule on the next tick.

PATCH/v1/registry/asset/{canonical}

Replace an existing asset entry.

DELETE/v1/registry/asset/{canonical}

Remove an entry and drop its per-asset heartbeat sources.

POST/v1/registry/asset/lookup

Auto-populate a full AssetEntry preview from a single input (ticker, name, or partial), cross-referencing multiple venues in parallel with imposter filtering.

GET/v1/registry/news/source

List configured news sources.

Admin & Operations

GET/v1/admin/stats

Process state: node count, hot/cold ratio, per-tier and per-type breakdowns, embed-index size. Liveness probe.

GET/v1/admin/universe

Current screener picks per asset class.

POST/v1/admin/refresh-universe

Fire one screener cycle on demand and persist new universe picks.

POST/v1/admin/refresh-metadata

Re-fetch registry metadata only (skip the screener scan).

POST/v1/admin/normalize-properties

One-shot backfill: rewrite every node's asset_class and category to canonical forms. Idempotent.

POST/v1/admin/restore-from-raw

Restore properties from preserved *_raw siblings and re-apply the current normalizer.

Compatibility

POST/mcp

Model Context Protocol JSON-RPC, surfaces brain_search / brain_ingest / brain_universe to any MCP-aware client. SSE keepalive at GET /mcp/sse.

POST/tavily/search

Tavily Search API drop-in, point existing LangChain / LlamaIndex agents at Incord by changing BASE_URL.

POST/openai/v1/embeddings

OpenAI Embeddings API, served by Incord' own model. 256-dim Matryoshka-truncated vectors.

GET/v1/health

Health check.