REST API Reference

HTTP endpoints for the Synapse Layer REST API v1. All endpoints require authentication via Connect Token and return JSON responses.

On this page

Warning

This is a human-maintained endpoint reference, not an auto-generated OpenAPI specification. Endpoints are documented based on the current implementation.

Authentication

All API requests require a Connect Token in the x-connect-token header:

bash
curl -X POST https://forge.synapselayer.org/api/v1/memory/commit \
  -H "Content-Type: application/json" \
  -H "x-connect-token: sk_connect_your_token" \
  -d '{"content": "test memory", "agent": "my-agent"}'

Tokens use the sk_connect_* prefix. Generate tokens at Forge → Dashboard → Connect.

Base URL

text
https://forge.synapselayer.org/api/v1

Store Memory

POST/api/v1/memory/commit

Store a memory. Content passes through the security pipeline (PII sanitization, intent validation, differential privacy) and is encrypted server-side with AES-256-GCM before persistence.

Request Body

FieldTypeRequiredDescription
contentstringYesMemory content (1–10,000 chars)
agentstringNoAgent identifier. Default: token's agent
memoryTypestringNoshort_term | long_term | episodic
metadataobjectNoArbitrary key-value metadata

Response (200/201)

json
{
  "memoryId": "uuid-string",
  "contentHash": "sha256-hex",
  "trustQuotient": 0.85,
  "requestId": "req-uuid"
}

Recall Memory

POST/api/v1/sdk/recall

Semantically recall memories using pgvector HNSW similarity search.

Request Body

FieldTypeRequiredDescription
querystringYesNatural language search query
limitnumberNoMax results (1–50, default: 5)
modestringNoauto | semantic | temporal | priority | hybrid

Response (200)

json
{
  "memories": [
    {
      "content": "User prefers dark mode",
      "trust_quotient": 0.92,
      "intent": "preference",
      "agent": "my-agent",
      "timestamp": "2026-07-01T12:00:00Z",
      "memory_type": "long_term"
    }
  ],
  "latency_ms": 45
}

List Memories

GET/api/v1/memories/recent

List recent memories for the authenticated tenant.

GET/api/v1/memories/count

Returns the total memory count for the authenticated tenant.

Health & Metrics

GET/api/v1/quota

Check current quota usage and limits.

GET/api/v1/usage

Usage statistics for the current billing period.

GET/api/v1/metrics

Operational metrics (latency, throughput, error rates).

Error Codes

StatusMeaning
200Success
201Created (memory stored)
400Bad request (invalid payload)
401Unauthorized (invalid/missing Connect Token)
429Rate limit exceeded
500Internal server error

Next Steps

Python SDK

Higher-level Python client wrapping these endpoints.

MCP Tools Reference

13 MCP tools — same capabilities, MCP protocol.

Authentication

Connect Token and OAuth setup.