Skip to main content

aether-mcp HTTP API

The control plane that AMC, REST clients, and remote agents talk to. The MCP tools are also available over HTTP at POST /v1/mcp, see aether-mcp CLI and MCP tools.

HTTP Control Plane & Team API (19 endpoints)​

When require_auth is false, ControlPlaneServer::bind permits only 127.0.0.1 and ::1. When require_auth is true, every request (except OPTIONS CORS preflight returning 204 No Content and GET /v1/openapi.json) requires Authorization: Bearer aek_<hex>. Errors return { "error": "..." } with status 400, 401, 403, 404, or 500.

MethodPathMinimum role (when authenticated)Request body or queryResponse fields
GET/v1/openapi.jsonPublic (unauthenticated)NoneOpenAPI 3.1.0 specification (bearerAuth, /v1/status, /v1/recall, /v1/stage, /v1/inspect)
GET/v1/statusValid token (Reader+)NoneVaultStatusReport (status, schema_version, embedder_id, embedding_dim, active_amus, pending_inbox_count, approved_inbox_count, hot_tokens_used, hot_token_budget, prefix_hash)
GET/v1/inboxReaderNoneinbox_path, approved_mirror_path, pending (Vec<InboxEntry>)
POST/v1/inbox/decideAdmin (plus write scope check){ candidate_id, decision } ("approve" or "reject"){ candidate_id, decision, reconcile: InboxReconcileReport }
POST/v1/inbox/reconcileAdminNoneInboxReconcileReport (compiled, rejected, remaining_pending)
POST/v1/dreamAdminNoneDreamReport (daily_notes_scanned, daily_notes_skipped_unchanged, candidates_staged, contradictions_flagged, staged_candidate_ids)
POST/v1/syncAdminNoneSyncReport (files_scanned, files_skipped_unchanged, files_skipped_self_write, files_updated, files_removed, private_skipped, amus_indexed, inbox_approved, inbox_rejected, reindexed_amus)
POST/v1/git/syncAdminOptional { remote, branch, push, commit_message }GitSyncReport (remote, branch, head_commit, merged_cleanly, aether_conflicts_resolved, conflicted_files, sync_report, pushed)
GET/v1/vault/pullReaderNoneVaultPullResponse (manifest, inbox_path, inbox_markdown, approved_mirror_path, approved_mirror_markdown)
POST/v1/vault/pushContributor (Admin for Inbox decisions or run_dream){ notes?, deleted_paths?, private_paths?, inbox_markdown?, aetherignore?, run_dream? }VaultPushResponse (sync_report, dream_report?, inbox_path, inbox_markdown, approved_mirror_path, approved_mirror_markdown)
POST/v1/recallReader{ query, scope?, max_tokens?, include_hot_profile?, kv_model? }RecallResponse (formatted_context, hot_prefix, static_prefix, dynamic_context, hot_amus, warm_cold_amus, entries, static_prefix_tokens, dynamic_tokens, tokens_used, prefix_hash, kv_hint?)
POST/v1/stageContributor{ proposed_fact, suggested_tier?, scope?, target_note?, supersedes_amu_id?, proposed_by? }{ candidate_id, inbox_path }
POST/v1/inspectReader{ source_pointer }{ source_pointer, content }
POST/v1/mcpTool role (Reader or Contributor)JSON-RPC 2.0 request objectJSON-RPC 2.0 response object
POST/v1/kv/warmContributor{ model_id, scope?, amu_ids?, target_tier?, include_hot_prefix?, include_cache_blend?, block_tokens? }KvWarmReport (model_id, target_tier, blocks_warmed, blocks_reused, tokens_warmed, estimated_baseline_ttft_ms, estimated_warmed_ttft_ms, estimated_ttft_saved_ms, ttft_reduction_pct, fallback_used, block_hashes)
GET/v1/kv/statsValid token (Reader+)Optional ?model_id=<id>KvCacheStats (adapter_id, persisted_blocks, total_tokens, total_bytes, tier_usage, models)
GET/v1/auth/keysAdminNone{ keys: Vec<ScopedApiKey> }
POST/v1/auth/keysAdmin{ agent_id, role, scopes, expires_at? } (RFC 3339){ key: ScopedApiKey, secret: "aek_<64-hex>" }
POST/v1/auth/keys/revokeAdmin{ key_id }{ key_id, revoked: bool }