{"openapi":"3.1.0","info":{"title":"Synapse Layer API","version":"2.4.6","description":"MCP-Native Trust Infrastructure for AI Agents. Persistent, encrypted memory with AES-256-GCM encryption, cross-agent handover, Trust Quotient scoring, and built-in governance. The Trust Layer for the Agentic Internet.","contact":{"name":"Synapse Layer","url":"https://synapselayer.org","email":"founder.synapselayer@proton.me"},"license":{"name":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"},"x-category":"Trust Infrastructure for AI Agents","x-mcp-compatible":true,"x-agent-discovery":true,"x-trust-quotient":true,"x-llm-optimized":true},"servers":[{"url":"https://forge.synapselayer.org","description":"Production — MCP + REST API"},{"url":"https://synapselayer.org","description":"Marketing site — discovery/pages only"}],"paths":{"/.well-known/mcp/server-card.json":{"get":{"operationId":"get_mcp_server_card","summary":"MCP server card for agent discovery.","description":"Returns the MCP server card with tool definitions, auth requirements, and transport configuration. Used by MCP-compatible clients to discover and configure the Synapse Layer server.","x-agent-readable":true,"tags":["Discovery"],"responses":{"200":{"description":"MCP server card","content":{"application/json":{}}}}}},"/.well-known/trust.json":{"servers":[{"url":"https://synapselayer.org","description":"Marketing site — discovery/pages only"}],"get":{"operationId":"get_trust_manifest","summary":"Trust manifest for agent discovery.","description":"Machine-readable trust manifest. Returns security, compliance, and capability metadata.","x-agent-readable":true,"tags":["Discovery"],"responses":{"200":{"description":"Trust manifest JSON","content":{"application/json":{}}}}}},"/.well-known/pricing.json":{"servers":[{"url":"https://synapselayer.org","description":"Marketing site — discovery/pages only"}],"get":{"operationId":"get_pricing","summary":"Machine-readable pricing for agent checkout.","description":"Returns current plan pricing, features, and future billing capabilities.","x-agent-readable":true,"tags":["Discovery"],"responses":{"200":{"description":"Pricing JSON","content":{"application/json":{}}}}}},"/.well-known/mcp.json":{"servers":[{"url":"https://synapselayer.org","description":"Marketing site — discovery/pages only"}],"get":{"operationId":"get_mcp_manifest","summary":"MCP capability manifest.","description":"Returns MCP server metadata including tools count, transport options, and integration links.","x-agent-readable":true,"tags":["Discovery"],"responses":{"200":{"description":"MCP manifest JSON","content":{"application/json":{}}}}}},"/api/health":{"get":{"operationId":"get_health","summary":"Service health and connectivity status.","description":"Returns operational health for the Forge runtime: overall status, product version, server (engine) version, database connectivity and latency, tenant-isolation and privacy-model flags, and embedding/scoring subsystem status. Fields reflect exactly what the runtime emits and may expand over time.","x-agent-readable":true,"tags":["Operational"],"responses":{"200":{"description":"Health status JSON (e.g. status, version, serverVersion, db, tenantIsolation, privacyModel).","content":{"application/json":{}}}}}},"/api/mcp":{"post":{"operationId":"mcp_jsonrpc","summary":"MCP endpoint over HTTP (streamable-http, JSON-RPC 2.0).","description":"Model Context Protocol endpoint. Accepts JSON-RPC 2.0 requests (jsonrpc, method, params, id). Set Accept to include both application/json and text/event-stream; the response is returned as a JSON object or as an SSE stream (data: lines) depending on the method. Example: method \"tools/list\" returns the available MCP tools. Requires a connect token for authenticated operations.","security":[{"connectToken":[]}],"tags":["Operational"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","description":"JSON-RPC version, e.g. \"2.0\""},"method":{"type":"string","description":"JSON-RPC method, e.g. \"tools/list\""},"params":{"type":"object","description":"Method parameters"},"id":{"description":"JSON-RPC request identifier"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"JSON-RPC result (application/json) or SSE stream (text/event-stream).","content":{"application/json":{},"text/event-stream":{}}}}},"get":{"operationId":"get_mcp_metadata","summary":"MCP endpoint discovery metadata.","description":"Returns lightweight MCP metadata for discovery — server name, product version, protocol, transport, and the endpoint map. This GET does NOT return the tools array (use POST with method \"tools/list\" for tools). Runtime shape: { name: \"synapse-layer\", version: \"2.4.6\", protocol: \"mcp\", transport: \"streamable-http\", endpoints: { post: \"/mcp\" } }.","x-agent-readable":true,"tags":["Operational"],"responses":{"200":{"description":"MCP metadata JSON (name, version, protocol, transport, endpoints). No tools array is returned by GET.","content":{"application/json":{}}}}}},"/api/connect/token":{"post":{"operationId":"issue_connect_token","summary":"Exchange an authorization code for a connect token.","description":"Issues a connect token (sk_connect_*) used for authenticated API/MCP access. The request exchanges an authorization code obtained from the Forge connect flow. Returns 400 (invalid_request) when the authorization code is missing. Note: the handler is served by the Forge runtime (not this repository); the schema below is documented from verified runtime behavior only — no fields are invented.","tags":["Operational"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Authorization code from the Forge connect flow"}},"required":["code"]}}}},"responses":{"200":{"description":"Connect token issued.","content":{"application/json":{}}},"400":{"description":"invalid_request — e.g. \"Missing authorization code.\"","content":{"application/json":{}}}}}},"/api/connect/health":{"get":{"operationId":"get_connect_health","summary":"Authenticated connectivity + account health check.","description":"Authenticated health check used to verify a connect token before heavy work. On success (200) returns the caller identity, plan, and memory count for the authenticated tenant. Requires a valid connect token in the x-connect-token header; without one the runtime returns 401 (\"Missing or invalid token format.\"). Only GET is allowed (POST returns 405).","security":[{"connectToken":[]}],"x-agent-readable":true,"tags":["Operational"],"responses":{"200":{"description":"Authenticated health JSON (identity, plan, memory count).","content":{"application/json":{}}},"401":{"description":"Missing or invalid token format.","content":{"application/json":{}}}}}},"/api/v1/capture":{"post":{"operationId":"capture_memory_v1","summary":"Store an encrypted memory (REST).","description":"Stores a memory in the Forge Vault (AES-256-GCM at rest) via REST — the REST equivalent of the save_to_synapse MCP tool / Synapse.store(). Requires a valid connect token sent in the x-connect-token header (Authorization: Bearer is also accepted by the runtime); without one the runtime returns 401 (\"Missing x-connect-token header or Authorization: Bearer token.\", code MISSING_TOKEN). Only POST is allowed (GET returns 405).","security":[{"connectToken":[]}],"tags":["Operational"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Memory content to store (required)."},"memory_type":{"type":"string","description":"Memory type (e.g. long_term, short_term)."},"metadata":{"type":"object","description":"Arbitrary metadata object attached to the memory."}},"required":["content"]}}}},"responses":{"200":{"description":"Memory stored.","content":{"application/json":{}}},"400":{"description":"invalid request","content":{"application/json":{}}},"401":{"description":"Missing/invalid token (MISSING_TOKEN).","content":{"application/json":{}}},"402":{"description":"quota exceeded","content":{"application/json":{}}},"429":{"description":"rate limited (respect Retry-After)","content":{"application/json":{}}},"500":{"description":"transient error (retry with backoff)","content":{"application/json":{}}}}}},"/api/v1/handover":{"post":{"operationId":"legacy_handover_v1","deprecated":true,"summary":"Deprecated — legacy V1 handover (permanently disabled, returns 410).","description":"Retired endpoint. Neural handover is now an MCP tool (neural_handover) and was aligned in the spec in commit c177834. Documented here for runtime transparency (\"autopsy\"): the endpoint exists and permanently returns 410 Gone. Use Secure Agent Handover V2 via the Forge UI or the neural_handover MCP tool.","tags":["Operational"],"responses":{"410":{"description":"LEGACY_DISABLED — V1 handover is permanently disabled. Use neural_handover (MCP) or Handover V2.","content":{"application/json":{}}}}}}},"components":{"securitySchemes":{"connectToken":{"type":"apiKey","in":"header","name":"x-connect-token","description":"Connect token (sk_connect_xxx) sent in the x-connect-token header. Get your key at https://forge.synapselayer.org/dashboard/connect"}}},"tags":[{"name":"Discovery","description":"Agent discovery and metadata endpoints (served from marketing site)"},{"name":"Operational","description":"Operational REST + MCP endpoints served by the Forge runtime"}],"externalDocs":{"description":"Synapse Layer Documentation","url":"https://synapselayer.org/docs"},"x-mcp-tools":{"x-canonical-source":"https://forge.synapselayer.org/api/mcp (tools/list)","x-snapshot-date":"2026-08-31","x-regeneration":"Re-run tools/list on Forge and diff before trusting these schemas.","recall":{"description":"Retrieve memories by semantic query. A reason is required for the audit trail.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Semantic search query"},"reason":{"type":"string","description":"Why this recall is performed (audit trail)"},"limit":{"type":"number","default":5,"description":"Max results to return"}},"required":["query","reason"]}},"save_to_synapse":{"description":"Persist an encrypted memory to the Forge Vault (AES-256-GCM at rest). `importance` is accepted for compatibility but is not enforced by the API.","inputSchema":{"type":"object","properties":{"content":{"type":"string","description":"Memory content to store"},"agent_id":{"type":"string","description":"Agent identifier for cross-agent traceability"},"project":{"type":"string","description":"Project namespace"},"type":{"type":"string","description":"Memory type (e.g. long_term, short_term)"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags for categorization"}},"required":["content"]}},"process_text":{"description":"Extract and store salient memories from a block of unstructured text.","inputSchema":{"type":"object","properties":{"content":{"type":"string","description":"Raw text to process"},"agent_id":{"type":"string","description":"Agent identifier"}},"required":["content"]}},"search":{"description":"Keyword and semantic search across stored memories.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Search query"},"limit":{"type":"number","default":10,"description":"Max results"}},"required":["query"]}},"health_check":{"description":"Return server health and connectivity status.","inputSchema":{"type":"object"}},"initialize_context":{"description":"Initialize an agent session context before memory operations.","inputSchema":{"type":"object","properties":{"agent_id":{"type":"string","description":"Agent identifier"},"project":{"type":"string","description":"Project namespace"}}}},"save_memory":{"description":"Alias of save_to_synapse for compatibility.","inputSchema":{"type":"object","properties":{"content":{"type":"string","description":"Memory content to store"},"agent_id":{"type":"string","description":"Agent identifier"}},"required":["content"]}},"store_memory":{"description":"Alias of save_to_synapse for compatibility.","inputSchema":{"type":"object","properties":{"content":{"type":"string","description":"Memory content to store"},"agent_id":{"type":"string","description":"Agent identifier"}},"required":["content"]}},"recall_memory":{"description":"Alias of recall for compatibility. A reason is required for the audit trail.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Semantic search query"},"reason":{"type":"string","description":"Why this recall is performed (audit trail)"},"limit":{"type":"number","default":5,"description":"Max results"}},"required":["query","reason"]}},"list_memories":{"description":"List stored memories for the authenticated agent/tenant.","inputSchema":{"type":"object","properties":{"limit":{"type":"number","default":50,"description":"Max memories to list"},"agent_id":{"type":"string","description":"Filter by agent identifier"}}}},"memory_feedback":{"description":"Submit feedback on a memory to adjust its Trust Quotient.","inputSchema":{"type":"object","properties":{"memory_id":{"type":"string","description":"Target memory identifier"},"feedback":{"type":"string","description":"Feedback signal (e.g. positive, negative)"}},"required":["memory_id","feedback"]}},"neural_handover":{"description":"Consume a handover token to transfer context between agents. A reason is required for the audit trail.","inputSchema":{"type":"object","properties":{"token":{"type":"string","description":"Handover token (64 hex chars) generated by the source agent"},"reason":{"type":"string","description":"Why this handover is consumed (audit trail)"},"consuming_agent":{"type":"string","description":"Agent identifier consuming the handover (defaults to token agent)"}},"required":["token","reason"]}},"slo_report":{"description":"Return service-level objective metrics for the authenticated tenant.","inputSchema":{"type":"object"}}}}