REST API Reference

Use REST API v1 from your server only. Long-lived Sela API keys are not supported for direct browser or mobile use in this version.

Authentication

Send the key in the Authorization header as a Bearer token. Use separate test and production keys when possible.

bash
curl https://your-convex-site.convex.site/api/v1/conversations \
  -H "Authorization: Bearer sk_live_..."

Supported Endpoints

GET

/api/v1/conversations

Lists organization conversations. Requires the conversations:read permission.

bash
curl "https://your-convex-site.convex.site/api/v1/conversations?limit=25&status=open" \
  -H "Authorization: Bearer sk_live_..."
GET

/api/v1/messages

Lists messages for a single conversation. Requires the messages:read permission and the conversation_id query parameter.

bash
curl "https://your-convex-site.convex.site/api/v1/messages?conversation_id=jt7..." \
  -H "Authorization: Bearer sk_live_..."
GET

/api/v1/orders

Lists restaurant orders created by Sela. Requires orders:read and supports status values pending, approved, arrived, rejected, failed, cancelled, and all.

bash
curl "https://your-convex-site.convex.site/api/v1/orders?status=pending&limit=25" \
  -H "Authorization: Bearer sk_live_..."
POST

/api/v1/orders/action

Approves, rejects, or marks an order as arrived. Requires orders:write. Sela sends approval and rejection messages to the customer.

bash
curl "https://your-convex-site.convex.site/api/v1/orders/action" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "toolExecutions:...",
    "action": "approve",
    "external_order_id": "menu-123"
  }'

Pagination

Read endpoints support limit and cursor and return next_cursor and is_done inside meta.

json
{
  "data": [],
  "meta": {
    "request_id": "c6f1...",
    "next_cursor": "eyJ...",
    "is_done": false,
    "limit": 25
  }
}

Errors

Every response includes a request ID in X-Sela-Request-Id and in the response body for tracing.

json
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded.",
    "request_id": "c6f1..."
  }
}