API reference

The Praigen Events API has a single endpoint: POST /api/v1/events. Send events (messages, appointment requests, etc.); the API routes them to the right AI Employee and returns a reply. Response field names such as agent remain unchanged for compatibility.

Endpoint

POST /api/v1/events

Request body: JSON. Response: JSON.

Request body

Field	Required	Description
`tenant_id`	Yes	Your tenant (account) UUID.
`contact_id`	No	Contact (end-user) UUID for context.
`conversation_id`	No	Conversation thread UUID.
`channel`	Yes	e.g. `web`, `email`, `api`.
`event_type`	Yes	e.g. `message`, `appointment.requested`.
`payload`	No	Arbitrary JSON (message content, etc.).
`request_id`	No	Idempotency or correlation ID.

Backwards compatibility: customer_id is accepted as tenant_id; user_id as contact_id.

Success response (200)

{
  "ok": true,
  "agent": "ChatAgent",
  "reply": {
    "text": "Reply text from the employee.",
    "tool_results": []
  }
}

Error response (4xx / 5xx)

{
  "ok": false,
  "error": "tenant_id is required",
  "details": null
}

Environment (server)

For the API to run, set (e.g. in .env or server config):

DB_DSN – PostgreSQL connection string (e.g. pgsql:host=localhost;port=5432;dbname=praigen)
DB_USER – Database user
DB_PASS – Database password

Run the migration once: psql "$DB_DSN" -f website/api/sql/001_tenants_contacts_events_state.sql