API Overview
HTTP endpoints for interacting with Struere
Struere exposes HTTP endpoints through its Convex backend for agent communication, webhook processing, and health monitoring. Your base URL is your Convex deployment URL (the CONVEX_SITE_URL).
Authentication
Chat endpoints authenticate via Bearer token using API keys. API keys are created in the Struere dashboard under API Keys and are scoped to a specific environment (development or production).
Authorization: Bearer sk_dev_abc123...
The environment of the API key determines which environment the request operates in. A development API key accesses development agents, entities, and configurations. A production API key accesses production data. There is no way to cross environments with a single key.
API keys are validated by computing a SHA-256 hash and looking up the hashed value in the database.
Permissions
Each API key has a set of permissions that control which endpoints it can access.
| Permission | Access |
|---|---|
* |
Full access to all endpoints (chat, data, sync) |
chat |
Chat endpoints (/v1/chat, /v1/agents/:slug/chat) |
data |
Data API endpoints (/v1/data/*, /v1/entity-types) |
sync |
CLI sync endpoints (/v1/sync/*) |
Keys created in the dashboard default to * (full access). When creating keys programmatically or through the agent settings page, you can restrict permissions to specific scopes.
Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/health |
None | Health check |
POST |
/v1/chat |
Bearer token | Chat with an agent by agent ID |
POST |
/v1/agents/:slug/chat |
Bearer token | Chat with an agent by slug |
GET |
/v1/entity-types |
Bearer token (data) | List entity types |
GET |
/v1/data/:type |
Bearer token (data) | List entities |
GET |
/v1/data/:type/:id |
Bearer token (data) | Get entity by ID |
POST |
/v1/data/:type |
Bearer token (data) | Create entity |
POST |
/v1/data/:type/query |
Bearer token (data) | Query entities with filters |
POST |
/v1/data/:type/search |
Bearer token (data) | Full-text search entities |
PATCH |
/v1/data/:type/:id |
Bearer token (data) | Update entity |
DELETE |
/v1/data/:type/:id |
Bearer token (data) | Delete entity |
POST |
/webhook/clerk |
None | Clerk user/organization sync webhook |
POST |
/webhook/kapso/project |
HMAC signature | WhatsApp phone number connection events |
POST |
/webhook/kapso/messages |
HMAC signature | WhatsApp inbound messages and status updates |
POST |
/webhook/flow |
None | Flow payment status updates |
POST |
/webhook/polar |
HMAC signature | Polar payment/billing events |
GET /health
Returns the current server status and timestamp.
Request:
curl https://your-deployment.convex.site/health
Response:
{
"status": "ok",
"timestamp": 1710500000000
}
POST /v1/chat
Send a message to an agent identified by its Convex document ID. See the Chat API documentation for full details.
POST /v1/agents/:slug/chat
Send a message to an agent identified by its slug. This is the preferred endpoint for external integrations as slugs are human-readable and stable across deployments. See the Chat API documentation for full details.
Data API
CRUD and query operations for entities in your data layer. Requires an API key with the data permission. See the Data API documentation for full details.
Webhook Endpoints
Webhook endpoints receive events from external services. See the Webhooks documentation for details on each webhook.
Error Responses
All endpoints return JSON error responses with appropriate HTTP status codes:
401 Unauthorized — Missing or invalid API key:
{
"error": "Unauthorized"
}
400 Bad Request — Missing required fields:
{
"error": "agentId and message are required"
}
500 Internal Server Error — Server-side execution failure:
{
"error": "Error description"
}
Rate Limiting
Rate limits are enforced at the Convex platform level. Refer to your Convex plan for specific limits on function calls and bandwidth.
CORS
The HTTP endpoints do not set CORS headers by default. For browser-based integrations, use the Convex React client which connects over WebSocket rather than HTTP.