Synap

Config is auto-fetched on startup. No restart needed.

Manual

SYNAP_HUB_API_KEY    = hub_xxxx
SYNAP_POD_URL        = https://pod.synap.live
SYNAP_WORKSPACE_ID   = <uuid>
SYNAP_AGENT_USER_ID  = <uuid>

All calls: Authorization: Bearer {SYNAP_HUB_API_KEY} + Content-Type: application/json.

Key must have hub-protocol.read AND hub-protocol.write scopes.

Data Model

Entities

Typed objects with properties and relationships. The fundamental unit of knowledge.

Extend profiles: a "lead" extends person, a "webinar" extends event. Use GET /api/hub/profiles to discover types. Use POST /api/hub/profiles to create new ones.

Documents

Long-form Markdown. Reports, summaries, specs, meeting notes.

Facts (Memory)

Atomic knowledge that persists across sessions. "Marc prefers email over Slack."

Relations

Typed connections between entities. Types: related, parent, child, belongs-to.

Decision Tree

ALWAYS search before creating to prevent duplicates.

Governance

Auto-approved:

• All reads and searches
• Memory storage/recall
• Profile and property creation

May create proposal:

• Entity creation/updates
• Document creation
• Relation creation/deletion

Response format:

• { "status": "approved" } — executed
• { "status": "proposed", "proposalId": "..." } — queued for user approval (tell user, don't retry)
• { "status": "denied" } — blocked (respect, don't retry)

API Reference

Base URL: {SYNAP_POD_URL}/api/hub Auth: Authorization: Bearer {SYNAP_HUB_API_KEY}

Search & Read

GET /api/hub/search?userId={UID}&workspaceId={WID}&query=Marc&limit=10
GET /api/hub/entities/<id>?userId={UID}&workspaceId={WID}
GET /api/hub/users/{UID}/entities?workspaceId={WID}&type=task&limit=50
GET /api/hub/documents/<id>?userId={UID}
GET /api/hub/profiles?userId={UID}&workspaceId={WID}
GET /api/hub/relations?userId={UID}&workspaceId={WID}&entityId=<id>
GET /api/hub/users/{UID}/context?workspaceId={WID}
GET /api/hub/graph/traverse?userId={UID}&startEntityId=<id>&maxDepth=2

Memory

POST /api/hub/memory
{ "userId": "{UID}", "fact": "Marc prefers email", "confidence": 0.9 }
# embedding is optional — server handles it

GET /api/hub/memory?userId={UID}&query=Marc+preferences&limit=10

DELETE /api/hub/memory/<fact-id>?userId={UID}

Create & Update

POST /api/hub/entities
{
  "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}",
  "profileSlug": "task", "title": "Follow up with Marc",
  "properties": { "status": "todo", "priority": "high", "dueDate": "2026-04-10" },
  "reasoning": "User asked to track follow-up"
}

PATCH /api/hub/entities/<id>
{ "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}",
  "properties": { "status": "done" }, "reasoning": "Task completed" }

POST /api/hub/documents
{ "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}",
  "title": "Meeting Notes", "content": "# Meeting\n\n...", "reasoning": "..." }

POST /api/hub/relations
{ "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}",
  "sourceEntityId": "<id>", "targetEntityId": "<id>", "type": "related",
  "reasoning": "Marc works at Acme Corp" }

DELETE /api/hub/relations/<id>
{ "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}" }

POST /api/hub/profiles
{ "userId": "{UID}", "workspaceId": "{WID}", "name": "Lead", "slug": "lead",
  "parentProfileId": "<uuid>", "description": "Sales lead" }

POST /api/hub/property-defs
{ "userId": "{UID}", "workspaceId": "{WID}", "profileId": "<uuid>",
  "name": "Company", "slug": "company", "valueType": "string" }

Property value types: string, number, boolean, date, entity_id, array, object, secret.

Message Relay (External Channels)

When a message arrives from Telegram, WhatsApp, Slack, or another platform:

Step 1: Create or reuse a thread:

POST /api/hub/threads
{ "userId": "{UID}", "workspaceId": "{WID}", "title": "Telegram: Alice" }

Step 2: Post the message (with autoRespond: true to trigger Synap AI):

POST /api/hub/threads/<thread-id>/messages
{ "role": "user", "content": "Hey are you free today?",
  "userId": "{UID}", "autoRespond": true }

Step 3: Poll for AI response:

GET /api/hub/threads/<thread-id>/messages

Filter for role: "assistant" messages after your timestamp. Poll every 3s, max 45s.

A2AI (Agent-to-Agent)

Same thread/message endpoints. Post with autoRespond: true, poll for response.

GET /api/hub/threads?userId={UID}&workspaceId={WID}
POST /api/hub/threads/<id>/messages
GET /api/hub/threads/<id>/messages

Error Handling

"proposed" and "denied" in response body are NOT errors — they're governance.

Best Practices

1. Search before creating — prevent duplicates. Most important habit.
2. Use specific entity types — person not note, company not bookmark.
3. Store atomic facts — preferences, decisions, context. Always auto-approved.
4. Link entities with relations — build the graph. Use graph traversal to explore.
5. Include reasoning — every write accepts "reasoning". Creates audit trail.
6. Batch related operations — person + company + relation in sequence.
7. Read before updating — documents replace full content, not diff.
8. Extend profiles — "lead" extends person, "webinar" extends event.

Filesystem Rules

synap v1.0.0 — github.com/synap-core/backend/tree/main/skills/synap