API Documentation

SwiftChat exposes a versioned REST API at /api/v1. Interactive explorer at /developer-portal.

Authentication

Every request must include an API key:

Authorization: Bearer sk_live_...

Create keys in Developer Center → API Keys. Keys scope to a tenant and a permission set.

Base URL

https://<your-domain>/api/v1

Core resources

| Resource | Endpoints | |----------|-----------| | conversations | list, get, create, update, close | | messages | list, get, send, delete | | contacts | list, get, create, update, delete | | deals | list, get, create, update, move-stage | | webhooks | list, create, rotate-secret, delete |

Pagination

Cursor-based:

GET /api/v1/conversations?limit=50&cursor=eyJpZCI6...

Responses include next_cursor (nullable).

Rate limits

• Default: 60 requests / second / tenant
• Burst: 120 requests over 10 seconds
• Every response includes X-RateLimit-Remaining and X-RateLimit-Reset
• 429 responses include Retry-After (seconds)

Errors

All errors use RFC 7807 problem-details:

{
  "type": "https://swiffer.dev/errors/invalid-input",
  "title": "Invalid input",
  "status": 400,
  "detail": "phone_number must be E.164",
  "instance": "/api/v1/messages",
  "trace_id": "req_01H..."
}

Example

curl -X POST https://api.swiffer.app/api/v1/messages \
  -H "Authorization: Bearer $WADIFF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_123",
    "type": "text",
    "text": "Hello 👋"
  }'