API Overview

Syntropy provides HTTP APIs for event ingestion, project configuration, customer data, chat automation, knowledge base / RAG, transactional email, and hosted databases.

Base URL

https://syntropy.chat/api

Or your self-hosted instance:

https://your-domain.com/api

Authentication

Public ingest API

/api/ingest uses your Project ID (DSN) in the request body:

{
  "projectId": "your-project-id",
  ...
}

Project API routes (/api/{accountId}/...)

Endpoints under /api/{accountId}/... are for server-to-server use by connected products. They accept a project API key via Authorization: Bearer <key> or x-api-key. The /api/{accountId}/chat route additionally allows unauthenticated browser requests from allowlisted origins (for embedded chat widgets).

Organization-scoped APIs

Organization/project management endpoints require either:

• an authenticated dashboard user session, or
• a project API key with required scopes

Session requests are authorized only when:

1. The user is logged in
2. The user belongs to the target organization
3. The project belongs to that organization

API key requests are authorized by:

1. key validity (not revoked/expired)
2. organization and project binding
3. required scope checks for the endpoint

Endpoints

Endpoint	Method	Description
/api/{accountId}/chat	POST	Run a chat turn (browser embed or server-to-server with chat:invoke scope)
/api/{accountId}/kb/docs	POST	Register a document for KB ingestion
/api/{accountId}/kb/docs/{documentId}	GET	Poll document ingestion status
/api/{accountId}/kb/query	POST	Query the knowledge base — returns answer + citations
/api/ingest	POST	Ingest events (errors, pageviews, custom)
/api/organizations/{organizationId}/projects/{projectId}/source-maps	GET, POST	Upload and list source maps
/api/organizations/{organizationId}/projects/{projectId}/api-keys	GET, POST	Create/list project API keys
/api/organizations/{organizationId}/projects/{projectId}/api-keys/{keyId}	DELETE	Revoke project API key
/api/organizations/{organizationId}/projects/{projectId}/chat-schemas	GET, POST	Manage structured chat schemas
/api/organizations/{organizationId}/projects/{projectId}/chat-schemas/{schemaId}	GET, PATCH, DELETE	Manage one structured chat schema
/api/organizations/{organizationId}/projects/{projectId}/customers	GET, POST	List and upsert customer profiles
/api/organizations/{organizationId}/projects/{projectId}/customers/import/csv	POST	Import customers from CSV (Customer.io-style exports)
/api/organizations/{organizationId}/projects/{projectId}/customers/events	POST	Ingest customer-scoped custom events
/api/organizations/{organizationId}/projects/{projectId}/customers/segments	GET, POST	List and materialize customer segments
/api/organizations/{organizationId}/projects/{projectId}/customers/segments/preview	POST	Preview segment matches without persisting
/api/organizations/{organizationId}/projects/{projectId}/customers/eligibility	POST	Evaluate channel/topic eligibility for a customer
/api/organizations/{organizationId}/projects/{projectId}/customers/{customerId}/devices	GET, POST	List/register customer devices
/api/organizations/{organizationId}/projects/{projectId}/queue/jobs	GET, POST	List and enqueue worker jobs
/api/organizations/{organizationId}/projects/{projectId}/queue/jobs/{jobId}	GET	Read one queue job with lifecycle history
/api/organizations/{organizationId}/projects/{projectId}/queue/jobs/events	GET	Poll lifecycle events across project queue jobs
/api/organizations/{organizationId}/projects/{projectId}/queue/jobs/stream	GET (SSE)	Subscribe to live lifecycle events
/api/v1/emails/send	POST	Send transactional email (email:send scope, secret key)
/api/organizations/{organizationId}/projects/{projectId}/databases	GET, POST	List and provision hosted databases
/api/organizations/{organizationId}/projects/{projectId}/databases/{databaseId}	GET, DELETE	Read or delete a hosted database
/api/organizations/{organizationId}/projects/{projectId}/databases/{databaseId}/connection-string	GET	Retrieve live connection string (requires databases:read)
/api/organizations/{organizationId}/projects/{projectId}/databases/{databaseId}/credentials	GET, POST	List credentials or trigger a rotation
/api/organizations/{organizationId}/projects/{projectId}/chat-triggers	GET, POST	List and create chat triggers
/api/organizations/{organizationId}/projects/{projectId}/chat-triggers/{triggerId}	GET, PATCH, DELETE	Read, update, or delete a chat trigger

For typed client usage from SDKs, see SDK API Client.

Shared Infrastructure Modules

• @eclosion-tech/syntropy-blob-storage for S3-compatible blob operations and UploadThing-style upload routes.
• See Blob Storage Module for integration details.
• @eclosion-tech/syntropy-queue for shared queue envelopes, worker runtime, and task lifecycle monitoring.
• See Queue Worker SDK for integration details.
• See Transactional email for the send API, templating, and mail provider configuration.

Rate Limits

Tier	Events/minute	Source Maps/day
Free	1,000	10
Team	10,000	100
Business	100,000	1,000

Response Format

All responses are JSON:

{
  "success": true,
  "eventIds": ["uuid-1", "uuid-2"],
  "sessionId": "session-uuid"
}

Error responses:

{
  "success": false,
  "error": "Invalid project ID",
  "details": [...]
}

CORS

The ingestion endpoint supports CORS for browser requests:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type