How do requests and responses work?
The same conventions apply to every endpoint:
- Base URL: https://app.kawlnow.com. Every path starts with /api/manage/, and there’s no version number in the path.
- Authentication: Authorization: Bearer YOUR_WORKSPACE_TOKEN on every request.
- Request bodies: JSON with Content-Type: application/json, up to 150,000 bytes, on the endpoints that take one. A larger body returns 413, and one that isn’t valid JSON returns 400 with “Send valid JSON.”
- Responses: JSON, sent with Cache-Control: no-store. A failure is an object with one field, error, holding a plain-language message.
- IDs: workspace IDs start with hl_. Source, conversation and token IDs are UUIDs.
- Times: ISO 8601 strings in UTC, such as 2026-10-08T09:30:00.000Z, except in the workspace response’s phoneVerification object, which uses epoch milliseconds.
- Flags: settings use true and false, but approved, finalized and is_test come back as 1 or 0.
- Browsers: there are no CORS headers, so call the API from servers, scripts and CI rather than from a web page.
curl -i -X PATCH 'https://app.kawlnow.com/api/manage/sources/SOURCE_ID' \
-H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"approved": "yes"}'
HTTP/2 400
cache-control: no-store
content-type: application/json
{"error":"Set approved to true or false."}Which endpoints are there?
On 8 October 2026 the API had these 14 operations, and the OpenAPI file describes the same ones for tools. Other statuses are covered in the errors reference.
| Endpoint | What it does | Success |
|---|---|---|
| GET /api/manage/workspace | Reads both agents’ settings, usage, sources, the latest 100 conversations and tokens | 200 with the workspace |
| PATCH /api/manage/settings | Changes the support agent and its widget | 200 with the saved settings |
| PATCH /api/manage/sales-settings | Changes the sales agent and its widget | 200 with the saved settings |
| POST /api/manage/sources | Adds a document, always unapproved | 201 with {"id": "SOURCE_ID"} |
| GET /api/manage/sources/{id} | Reads one source with its full text | 200 with the source |
| PATCH /api/manage/sources/{id} | Approves or unapproves a source | 200 with {"ok": true} |
| DELETE /api/manage/sources/{id} | Deletes a source | 200 with {"ok": true} |
| POST /api/manage/github | Imports or refreshes one GitHub support document, unapproved | 201 with {"id": "SOURCE_ID"} |
| POST /api/manage/website | Switched off | None: 503 for any valid URL |
| GET /api/manage/conversations/{id} | Reads one conversation with its transcript | 200 with the conversation |
| GET /api/manage/insights | Reads one agent’s automatic insights: recurring questions, reported issues and themes from recent customer calls, with quotes. Add ?channel=sales for the sales agent | 200 with its state and the latest report, if there is one |
| POST /api/manage/keys | Creates a workspace token | 201 with {"id", "token"} |
| DELETE /api/manage/keys/{id} | Revokes a workspace token | 200 with {"ok": true} |
| POST /api/manage/notifications/test | Sends a test email to the owner | 202 with {"queued": true} |
What can’t the REST API do?
Plan around these gaps rather than looking for a hidden endpoint:
- Start a call. Visitors start calls from the widget, and you test from the dashboard.
- Return the embed snippet. Copy it from the dashboard or the get_installation MCP tool, or build it from the workspace id: it’s the standard script tag with your ID in data-helpline.
- Send webhooks or events. Poll GET /api/manage/workspace for new conversations and changes.
- Page through conversations. The workspace response holds the latest 100, and GET /api/manage/conversations/{id} reads any conversation by id, including older ones whose ids you kept.
- Return text in lists. The workspace response lists sources without their text, so read each one with GET /api/manage/sources/{id}.
- Work in bulk. Each request adds, approves or deletes one source.
- Delete conversations or the workspace. Deletion is handled on request.
- Verify a team phone number for human handover, an early release, or manage billing. Both work only in the signed-in dashboard.