Pod API Quickstart
Connect to your Data Pod with a single base URL and Bearer token. Copy-paste examples below work with curl, JavaScript, and Python.1. Base URL and authentication
Your Pod exposes a REST API at /api/hub. Use your Data Pod domain (e.g. the same URL you use for the Synap app). Authentication is a single API key in the Authorization header.
Create an API key in the Synap app under Settings → API Access. Use scopes hub-protocol.read and hub-protocol.write for full access.
2. Create an entity
POST /entities creates an entity (task, note, project, or any profile type). You must send userId, workspaceId, type (profile slug, e.g. task, note, project), and title.
curl
curl -X POST "https://<your-pod-domain>/api/hub/entities" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"userId": "YOUR_USER_ID",
"workspaceId": "YOUR_WORKSPACE_ID",
"type": "task",
"title": "My first task from API",
"description": "Optional description"
}'JavaScript (fetch)
const res = await fetch(`https://<your-pod-domain>/api/hub/entities`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.SYNAP_API_KEY}`,
},
body: JSON.stringify({
userId: "YOUR_USER_ID",
workspaceId: "YOUR_WORKSPACE_ID",
type: "task",
title: "My first task from API",
description: "Optional description",
}),
});
const data = await res.json(); // { status, message, id }Python
import os
import requests
resp = requests.post(
f"https://<your-pod-domain>/api/hub/entities",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {os.environ['SYNAP_API_KEY']}",
},
json={
"userId": "YOUR_USER_ID",
"workspaceId": "YOUR_WORKSPACE_ID",
"type": "task",
"title": "My first task from API",
"description": "Optional description",
},
)
data = resp.json() # {"status", "message", "id"}Response: { status, message, id }. Entity creation goes through an event chain (requested → validated → completed). The returned id is the new entity ID.
3. Update an entity
PATCH /entities/:entityId updates title, preview (description), or metadata. Include workspaceId in the body.
curl -X PATCH "https://<your-pod-domain>/api/hub/entities/ENTITY_UUID" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"userId": "YOUR_USER_ID",
"workspaceId": "YOUR_WORKSPACE_ID",
"title": "Updated title",
"preview": "Updated description"
}'4. Create a document
POST /documents creates a document. No workspaceId required in body (documents are user-scoped in this endpoint).
curl -X POST "https://<your-pod-domain>/api/hub/documents" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"userId": "YOUR_USER_ID",
"title": "My note",
"content": "# Hello\nContent here.",
"type": "markdown"
}'5. Search
GET /search with query params userId, query, and optionally workspaceId, collections, limit, page.
curl -X GET "https://<your-pod-domain>/api/hub/search?userId=YOUR_USER_ID&query=my%20tasks" \ -H "Authorization: Bearer YOUR_API_KEY"
