How do you call it?

Send a GET with your token. It takes no parameters. The example response leaves out some fields and shows one item in each list.

Request
curl 'https://app.kawlnow.com/api/manage/workspace' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'
Response 200, with some fields left out
{
  "id": "YOUR_WORKSPACE_ID",
  "settings": {
    "productName": "Example App",
    "agentName": "Sam",
    "voice": "marin",
    "widgetLabel": "Talk to us",
    "allowedOrigins": [
      "https://www.example.com"
    ],
    "enabled": false,
    "agentConfigured": true
  },
  "freeUsed": 4,
  "sources": [
    {
      "id": "SOURCE_ID",
      "channel": "support",
      "title": "Invite a teammate",
      "kind": "document",
      "repo": null,
      "path": null,
      "approved": 1,
      "updated_at": "2026-10-08T09:30:00.000Z",
      "characters": 1240
    }
  ],
  "conversations": [
    {
      "id": "CONVERSATION_ID",
      "channel": "support",
      "topic": "Inviting a teammate",
      "status": "ended",
      "created_at": "2026-10-08T10:02:11.000Z",
      "seconds": 96.4,
      "finalized": 1,
      "is_test": 1,
      "summary": "How do I invite someone from my team?",
      "feedback": "Customer rating: helpful"
    }
  ],
  "keys": [
    {
      "id": "TOKEN_ID",
      "prefix": "hl_sk_1a2b3c4d",
      "created_at": "2026-10-08T09:00:00.000Z"
    }
  ],
  "onboarding": {
    "supportTestCompleted": true,
    "salesTestCompleted": false
  }
}

What does each field hold?

Fields may be added during the pilot, so have your code ignore any it doesn’t recognise.

Fields in the workspace response
FieldWhat it holds
idYour public workspace ID, starting with hl_. It’s the data-helpline value in the embed.
settingsThe support agent’s saved settings, including its instructions, allowed origins and calls switch. The agent settings reference explains each one.
salesSettingsThe sales agent’s saved settings, in the same shape.
freeUsedHow many of the workspace’s 50 free conversations have been used. It never resets.
phoneVerificationThe team phone numbers for human handover, an early release: whether verification is available, the countries allowed (GB and US) and, for support and sales, the verified number, when it was verified and any verification in progress. Numbers are verified and changed only in the dashboard. Its times are epoch milliseconds, and its numbers can be personal data, so keep them out of logs.
sourcesEvery knowledge source, most recently changed first, without its text: id, channel, title, kind, repo, path, approved (1 or 0), updated_at and characters.
conversationsThe latest 100 conversations, newest first, without transcripts: id, channel, topic, status, created_at, seconds, finalized, is_test (1 for a dashboard test), summary and feedback.
keysYour tokens, newest first: id, prefix and created_at.
onboardingWhether a dashboard test call has finished for each agent, as supportTestCompleted and salesTestCompleted. The dashboard’s setup checklist reads them.
connectionsWhether the services the app relies on are set up, such as openai for the voice service and email for notices. If openai is false, calls can’t start.
notificationsWhether notices can reach you, with a reason if not, and the kind, status and time of the last 10 emails.
accountThe owner’s sign-in email address, where notices go, and an operator flag that is false for customer workspaces.
billingUsage of the free allowance and the state of paid calls, as the Usage & billing tab shows them. Paid calls aren’t available yet.

How should you poll it?

Kawl Now sends no webhooks, so a script that reacts to new conversations or approvals reads this endpoint on a schedule. Compare conversation ids with the ones you’ve already handled, and fetch transcripts for new ones with GET /api/manage/conversations/{id}.

The list includes calls that are still connecting or in progress, with the status pending or active, so wait for a final status before you process one. Polling every five minutes sees every new call at least once, because a workspace starts at most 12 calls a minute and the list holds 100. A call can stay active for up to 10 minutes, though, so at very high volumes one you saw as pending or active can leave the list before it finishes. If that happens, read it by id with GET /api/manage/conversations/{id}.

Which changes send email, and how do you test it?

Notices go to the owner’s sign-in address when a token is created or revoked, when customer calls are switched on or off, when allowed origins change, when human handover is switched on or off for an agent, when a caller’s handover to your team couldn’t be prepared, and when 40 and then all 50 free conversations have been used. They never include transcripts, summaries or caller details. Approvals, new sources and changes to text such as greetings and instructions don’t send one.

POST /api/manage/notifications/test queues one test email to that address and returns 202 with {"queued": true}. It takes no body and works once a minute: a second request within the minute returns 429, 409 means there’s no address to send to, and 503 means email isn’t set up on the server.

Send a test email
curl -X POST 'https://app.kawlnow.com/api/manage/notifications/test' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'

# Response 202: {"queued": true}