API and MCP

SynTwin exposes core data-management capabilities through REST and MCP. Meeting transcripts, email summaries, and call notes are not special: they are sources linked to people or to the owner.

Most owners should start with Connect external tools. This page is for technical setup.

Authentication

External clients use WorkOS API keys.

WorkOS setup

Use the same WorkOS environment that AuthKit uses.

1. Enable API keys.
2. In Authorization, enable API key management for the role owners receive. The role needs widgets:api-keys:manage.
3. In Authorization > Configuration, add the organization API key permissions below. SynTwin-created keys use syntwin:all; keys without permissions are rejected.

Use least-privilege permissions:

• people:read
• people:write
• sources:read
• sources:write
• sources:import
• knowledge:read
• knowledge:write
• deployments:read
• deployments:write
• syntwin:read
• syntwin:write
• syntwin:all

syntwin:all is a master scope. Write scopes imply matching read scopes.

Existing unscoped API keys must be rotated after enabling these permissions.

4. Set Convex env vars:

WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
WORKOS_CUSTOM_DOMAIN=login.syntwin.ai

Optional, if the default membership role is not the owner role:

WORKOS_PERSONAL_ORGANIZATION_ROLE_SLUG=admin

SynTwin creates a personal WorkOS organization per owner. The organization is not shown in SynTwin UI. It is only used so WorkOS can issue organization API keys through the API keys widget.

Implementation details:

• organization external id: syntwin-owner-<workos-user-id>
• organization membership: active membership for the WorkOS user
• cached Convex field: users.workosPersonalOrganizationId
• widget scope: widgets:api-keys:manage

REST

Interactive API reference:

GET /api/v1/docs

OpenAPI spec:

GET /api/v1/openapi.json

People:

GET    /api/v1/people
POST   /api/v1/people
GET    /api/v1/people/{id}
PATCH  /api/v1/people/{id}
DELETE /api/v1/people/{id}

Sources:

GET    /api/v1/sources
POST   /api/v1/sources
POST   /api/v1/sources/upload-url
POST   /api/v1/sources/uploads
GET    /api/v1/sources/{id}
PATCH  /api/v1/sources/{id}
DELETE /api/v1/sources/{id}

Knowledge and deployments:

GET    /api/v1/tags
POST   /api/v1/tags
PATCH  /api/v1/tags/{id}
DELETE /api/v1/tags/{id}

GET    /api/v1/rules
POST   /api/v1/rules
PATCH  /api/v1/rules/{id}
DELETE /api/v1/rules/{id}

GET    /api/v1/deployments
POST   /api/v1/deployments
PATCH  /api/v1/deployments/{id}
DELETE /api/v1/deployments/{id}

GET    /api/v1/questions
POST   /api/v1/questions/answer
POST   /api/v1/questions/dismiss

Create a source for people by email:

{
  "title": "Alice / Bob meeting",
  "content": "Full transcript or notes...",
  "personEmails": ["alice@example.com", "bob@example.com"],
  "createMissingPeople": true,
  "externalProvider": "custom-cron",
  "externalId": "meeting-123"
}

externalProvider plus externalId makes source creation idempotent.

Upload a file source:

1. POST /api/v1/sources/upload-url
2. POST the file bytes to the returned uploadUrl
3. Read { "storageId": "..." } from the upload response
4. POST /api/v1/sources/uploads

{
  "fileName": "meeting.pdf",
  "storageId": "returned-by-upload-response",
  "fileType": "application/pdf",
  "personEmails": ["alice@example.com"],
  "createMissingPeople": true,
  "tags": ["meeting"]
}

MCP

Remote MCP endpoint:

POST /api/mcp

This endpoint uses the MCP SDK in stateless JSON response mode over HTTP. Use the same WorkOS API key permissions as the REST API.

Available tools:

• list_people
• create_person
• update_person
• delete_person
• list_sources
• get_source
• create_source
• create_source_upload_url
• create_uploaded_source
• update_source
• delete_source
• call_capability

call_capability covers tags, rules, deployments, and reflection questions. Agents can pull data from calendars, email, notetakers, or files, then create people and sources or adjust other SynTwin state through these tools.