API Reference
Programmatic access to the Danvas platform
Overview
The Danvas API provides programmatic access to the restaurant operations platform. All endpoints are REST-based and return JSON responses. The API is primarily consumed by the internal @repo/telemetry and @repo/ai packages, but is also available for external integrations.
Live Service Status
Base URL
| Environment | URL |
|---|---|
| Production | https://danvas.hartalliance.com |
| Development | http://localhost:4000 |
Authentication
Danvas uses multiple authentication methods depending on the endpoint:
| Method | Use Case |
|---|---|
| Bearer Token | User authentication via Clerk JWT |
| Session Cookie | Browser session authentication |
| Webhook Signature | Verification for Clerk and Svix webhooks |
| Bearer (Cron Secret) | Authentication for scheduled cron jobs |
Rate Limiting
The API implements rate limiting via Upstash Redis.
- Chat Endpoint: Limited to 20 requests per minute per user.
- Push Notifications: Rate-limited per user (5/min for sending, 10/min for subscriptions).
- Cron Jobs: Restricted to internal infrastructure and verified secrets.
API Categories
AI Chat
Streaming SSE responses for conversational data queries.
Push Notifications
Management of Web Push subscriptions and delivery.
Webhooks
Handlers for external lifecycle events. Idempotency is enforced via @repo/idempotency.
Cron Jobs
Internal endpoints for scheduled operational tasks.
Error Handling
All API errors follow a consistent format:
{
"error": "Error message description",
"code": "MACHINE_READABLE_CODE"
}| Status Code | Meaning |
|---|---|
200 | Success |
400 | Bad request — invalid parameters or payload |
401 | Unauthorized — missing or invalid authentication |
403 | Forbidden — insufficient permissions for this resource |
429 | Too many requests — rate limit exceeded |
500 | Internal server error |
OpenAPI Specification
The curated API schema is available as an OpenAPI 3.0 specification in content/docs/api-reference/openapi.json. It covers stable documented integration endpoints; internal cron and application routes that are not intended for external callers are omitted. This file is manually maintained and must change with the documented endpoint contracts. The interactive specification follows: