API Reference

85+ REST endpoints. Base URL: https://brain.api.vauban.tech

All endpoints return { success, data, meta?, error? }. Pagination via limit + offset.

Authentication Methods

JWTSession token from /auth/verify. Header: Authorization: Bearer ...

KeyAPI key from /v1/keys. Header: X-API-Key: sk_...

AdminAdmin key. Header: X-Admin-Key: ...

NonePublic endpoint, no auth required

Sections

Health & Monitoring (3)Authentication (10)Knowledge (11)Cognitive Pipeline (V4.1) (11)Brains & Workspaces (6)API Keys (4)Agents (3)Development Intelligence (5)Billing & Subscriptions (4)Usage & Quotas (1)Organizations (7)Analytics (7)Marketplace (5)Sync & Export (4)Admin (4)

Health & Monitoring

Liveness probes and system status.

Method	Path	Auth	Description
GET	/health	None	Liveness probe — uptime, version
GET	/health/stats	None	Full status with knowledge stats
GET	/metrics	None	Prometheus-compatible metrics

Authentication

Wallet SNIP-12, OAuth (GitHub, Google), JWT tokens.

Method	Path	Auth	Description
POST	/auth/challenge	None	Generate SNIP-12 wallet challenge
POST	/auth/verify	None	Verify wallet signature, returns JWT
GET	/auth/me	JWT	Current user info + brains
POST	/auth/link	JWT	Link OAuth identity to wallet
GET	/auth/links	JWT	List identity links
GET	/auth/providers	None	Available auth providers
GET	/auth/github	None	Redirect to GitHub OAuth
GET	/auth/github/callback	None	GitHub OAuth callback
GET	/auth/google	None	Redirect to Google OAuth
GET	/auth/google/callback	None	Google OAuth callback

Knowledge

Core CRUD, full-text search, anchoring, graph traversal.

Method	Path	Auth	Description
POST	/api/knowledge	JWT/Key	Create knowledge entry
GET	/api/knowledge	Optional	Query with FTS + filters (?q, ?category, ?tags, ?limit, ?offset, ?brain_ids, ?confidence_min)
GET	/api/knowledge/:id	Optional	Get entry by ID + edges
PATCH	/api/knowledge/:id	JWT/Key	Update entry (partial)
GET	/api/knowledge/:id/versions	Optional	Version history
GET	/api/knowledge/:id/graph	Optional	Graph traversal (?depth=1-3)
POST	/api/knowledge/edges	JWT/Key	Create edge (source_id, target_id, edge_type)
POST	/api/knowledge/:id/anchor	JWT/Key	Anchor to Starknet (?format=vc)
GET	/api/knowledge/search/hybrid	Optional	Hybrid FTS + semantic search (?q, ?limit)
GET	/api/knowledge/graph/overview	Optional	Full graph overview (?limit, ?brain_id)
PATCH	/api/knowledge/:id/memory-class	JWT/Key	Reclassify entry epistemic type (fact, opinion, hypothesis)

Cognitive Pipeline (V4.1)

Proactive cognition, contradictions, spreading activation, analogical reasoning, feedback signals.

Method	Path	Auth	Description
GET	/api/cognitive/taxonomy	None	Epistemic taxonomy rules (fact/opinion/hypothesis)
GET	/api/cognitive/proactive/status	Optional	Proactive cognition monitoring — last runs, budget
GET	/api/cognitive/proactive/foresight	Optional	Foresight edges with survival rate
GET	/api/cognitive/proactive/dialectical	Optional	Dialectical syntheses with promotion rate
GET	/api/cognitive/contradictions/list	Optional	Contradictions with status/type filters (?status, ?type, ?limit)
GET	/api/cognitive/contradictions/:id	Optional	Full contradiction detail — entries, evidence, resolution
PATCH	/api/cognitive/contradictions/:id	JWT/Key	Resolve contradiction (admin — verdict + rationale)
POST	/api/brain/context	JWT/Key	FoA cognitive pipeline — full fluid intelligence query
GET	/api/retrieval-proofs	Optional	List retrieval proofs
GET	/api/proof/retrieval/:id	Optional	Proof details + on-chain status
GET	/api/proof/:id/vc	Optional	W3C VerifiableCredential output

Brains & Workspaces

Multi-tenant knowledge workspaces with member management.

Method	Path	Auth	Description
POST	/api/brains	JWT	Create brain
GET	/api/brains	JWT	List user brains
GET	/api/brains/:id	JWT	Get brain detail + members
PATCH	/api/brains/:id	JWT	Update brain settings (owner/admin)
POST	/api/brains/:id/members	JWT	Add member
DELETE	/api/brains/:id/members/:accountId	JWT	Remove member

API Keys

Create, list, rotate, and revoke API keys.

Method	Path	Auth	Description
POST	/v1/keys	JWT	Create API key
GET	/v1/keys	JWT	List keys (no raw values)
POST	/v1/keys/:id/rotate	JWT	Rotate key (new secret, same ID)
DELETE	/v1/keys/:id	JWT	Revoke key

Agents

Agent telemetry — log task executions, track cost.

Method	Path	Auth	Description
POST	/api/agents/tasks	JWT	Log agent task execution
GET	/api/agents/stats	JWT	Aggregated agent stats + cost
GET	/api/agents/:name/tasks	JWT	Agent task history (?limit, ?offset, ?status)

Development Intelligence

Pattern suggestion, anti-pattern detection, architecture analysis.

Method	Path	Auth	Description
POST	/api/development/suggest-patterns	JWT	Suggest design patterns for code
POST	/api/development/detect-antipatterns	JWT	Detect anti-patterns + vulnerabilities
POST	/api/development/architectural-advice	JWT	Architecture recommendations
POST	/api/development/realtime-analysis	JWT	Full real-time analysis
GET	/api/development/health	None	Pattern intelligence health

Billing & Subscriptions

Stripe integration for paid tiers.

Method	Path	Auth	Description
GET	/api/billing/prices	None	Public pricing info
POST	/api/billing/checkout	JWT	Create Stripe checkout session
POST	/api/billing/portal	JWT	Customer portal URL
GET	/api/billing/subscription	JWT	Current subscription

Usage & Quotas

Request metering with tier-based limits.

Method	Path	Auth	Description
GET	/api/usage	JWT	Account usage for last N days (?days=30)

Organizations

Team workspaces with RBAC, SSO, audit logs.

Method	Path	Auth	Description
POST	/api/organizations	JWT	Create organization
GET	/api/organizations	JWT	List user organizations
GET	/api/organizations/:id	JWT	Organization details
POST	/api/organizations/:id/members	JWT	Add member (admin)
DELETE	/api/organizations/:id/members/:accountId	JWT	Remove member
GET	/api/organizations/:id/audit-logs	JWT	Audit logs (?limit, ?offset)
POST	/api/organizations/:id/sso/configure	JWT	Configure SSO (owner)

Analytics

Velocity compounding, pattern success rates, ROI analysis.

Method	Path	Auth	Description
GET	/api/analytics/velocity	JWT	Velocity analytics (?project_id, ?period)
GET	/api/analytics/patterns/success	JWT	Pattern success metrics
GET	/api/analytics/quality	JWT	Quality metrics
GET	/api/analytics/roi	JWT	ROI analysis (?period, ?hourly_rate)
GET	/api/analytics/dashboard	JWT	Comprehensive dashboard
GET	/api/analytics/velocity/trends	JWT	Velocity trends (?periods=6)
GET	/api/analytics/velocity/forecast	JWT	Velocity forecast + compounding

Marketplace

Knowledge marketplace with escrow protection.

Method	Path	Auth	Description
GET	/api/marketplace	None	Browse listings (?category, ?limit)
POST	/api/marketplace	Key	Create listing
GET	/api/marketplace/patterns	None	Search public patterns
POST	/api/marketplace/patterns	JWT	Publish pattern
POST	/api/marketplace/patterns/:id/download	JWT	Download pattern

Sync & Export

Cross-instance knowledge synchronization.

Method	Path	Auth	Description
POST	/api/sync/push	JWT	Push knowledge to target instance
GET	/api/sync/export	JWT	Export entries for sync (?categories, ?since, ?limit)
POST	/api/sync/import	JWT	Import entry from external
GET	/api/sync/status	JWT	Sync status

Admin

Administrative operations (X-Admin-Key auth).

Method	Path	Auth	Description
POST	/api/admin/keys	Admin	Create API key (admin)
GET	/api/admin/keys	Admin	List all API keys
DELETE	/api/admin/keys/:id	Admin	Revoke key (admin)
GET	/api/admin/usage/:keyId	Admin	Usage stats for key (?hours=24)

Rate Limits & Quotas

Tier	Price	Daily Requests	Features
Free	$0	1,000	1 brain, SQLite local, no proofs
Pro	$29/mo	10,000	5 brains, cloud sync, Starknet proofs
Team	$99/mo	100,000	Unlimited brains, RBAC, 5 members, encrypted

Quota headers: X-Quota-Remaining, X-Quota-Limit, X-Quota-Reset