Skip to main content

Option C — Invoke skills via HTTP

Call named, deterministic operations on your pod from any external tool.

What it is​

Skills are named operations that run on your pod with full access to your data — entities, documents, search, and memory. Each skill has a defined input schema, a fixed scope (pod-wide, workspace, or user), and runs synchronously with a configurable timeout.

Invoking a skill via HTTP is like calling a typed function on your pod. The result is structured JSON. There is no natural language involved: you pass input, you get result.

This is the right option when you want repeatable, predictable behavior — extracting entities from raw text, creating structured notes, running a search pipeline, or any other operation your pod has a skill for.

Get an API key​

Go to Settings → API Keys → New Key, and select the scope skills.invoke.

The key is shown once at creation. Store it securely — it cannot be retrieved later.

List your skills​

curl https://YOUR_POD.synap.live/api/external/skills \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

[
  {
    "id": "sk_01hx...",
    "name": "Extract and save entities",
    "description": "Parses raw text and creates structured entity records in your workspace.",
    "scope": "workspace",
    "parameters": {
      "type": "object",
      "properties": {
        "text": { "type": "string", "description": "Raw text to parse" },
        "workspaceId": { "type": "string" }
      },
      "required": ["text", "workspaceId"]
    },
    "executionMode": "synchronous",
    "timeoutSeconds": 30
  },
  {
    "id": "sk_02hy...",
    "name": "Summarize overdue tasks",
    "description": "Fetches overdue tasks and returns a markdown summary.",
    "scope": "workspace",
    "parameters": {
      "type": "object",
      "properties": {
        "workspaceId": { "type": "string" }
      },
      "required": ["workspaceId"]
    },
    "executionMode": "synchronous",
    "timeoutSeconds": 15
  }
]

Note: Skill slugs are not yet supported — use the UUID id from the list endpoint when invoking. Slugs may be added in a future release.

Invoke a skill​

curl -X POST https://YOUR_POD.synap.live/api/external/skills/sk_01hx.../invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Meeting with Alice on Friday re: Q3 budget. Action: send updated projections by EOD.",
      "workspaceId": "ws_..."
    }
  }'

Response:

{
  "success": true,
  "result": {
    "entitiesCreated": [
      { "id": "ent_abc", "profileSlug": "task", "title": "Send updated Q3 projections" },
      { "id": "ent_def", "profileSlug": "event", "title": "Meeting with Alice – Friday" }
    ],
    "summary": "Created 1 task and 1 event from the input text."
  },
  "executionTimeMs": 142
}

TypeScript example​

const POD_URL = 'https://YOUR_POD.synap.live';
const API_KEY = 'YOUR_API_KEY';

async function listSkills() {
  const res = await fetch(`${POD_URL}/api/external/skills`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });

  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json() as Promise<Skill[]>;
}

async function invokeSkill(skillId: string, input: Record<string, unknown>) {
  const res = await fetch(`${POD_URL}/api/external/skills/${skillId}/invoke`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ input }),
  });

  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

  const data = await res.json();
  if (!data.success) throw new Error(`Skill failed: ${JSON.stringify(data)}`);

  return data.result;
}

// Usage
const skills = await listSkills();
const extractSkill = skills.find(s => s.name === 'Extract and save entities');

const result = await invokeSkill(extractSkill.id, {
  text: 'Follow up with Bob about the contract renewal.',
  workspaceId: 'ws_...',
});

console.log(result);

Using with Claude Code​

Add skill invocation as a tool in your project's CLAUDE.md so Claude Code can call it directly:

## Tools

### invoke_synap_skill
Calls a named operation on the Synap data pod.

```bash
# List available skills first
curl https://YOUR_POD.synap.live/api/external/skills \
  -H "Authorization: Bearer $SYNAP_API_KEY"

# Invoke a skill by ID
curl -X POST https://YOUR_POD.synap.live/api/external/skills/SKILL_ID/invoke \
  -H "Authorization: Bearer $SYNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { ... } }'
```

Use this when you want to persist something to my Synap pod, search my knowledge base, or run a structured operation. Store SYNAP_API_KEY in your environment.

Or as a standalone script Claude Code can run:

// synap-invoke.ts — run with: npx tsx synap-invoke.ts SKILL_ID '{"text":"..."}'
import { execSync } from 'node:child_process';

const [, , skillId, inputJson] = process.argv;

const result = await fetch(
  `${process.env.SYNAP_POD_URL}/api/external/skills/${skillId}/invoke`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SYNAP_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ input: JSON.parse(inputJson) }),
  }
);

console.log(JSON.stringify(await result.json(), null, 2));

Skill scopes​

ScopeVisibilityNotes
podAll workspaces on the podSystem-level skills: full-text search, cross-workspace indexing
workspaceOne workspaceMost skills live here; your API key's workspace context applies
userCurrent authenticated user onlyPersonal skills: private notes, personal memory

Your API key is tied to a user and (optionally) a workspace. Skills scoped below your key's permissions return 403.

Errors​

StatusMeaning
401 UnauthorizedAPI key missing or invalid
403 ForbiddenKey has no skills.invoke scope, or skill is out of your key's scope
404 Not FoundSkill ID does not exist, or you do not have access to it
400 Bad RequestSkill exists but is inactive, or input fails the skill's parameter schema
502 Bad GatewayPod could not reach the AI service (Intelligence Service unavailable)
504 Gateway TimeoutSkill ran longer than timeoutSeconds

Next steps​