How does a REST API work?
Fielding defined REST as a set of constraints: a client and server that can change independently; stateless requests that each carry everything the server needs; responses marked as cacheable or not; a uniform interface; layers, such as proxies, that a client can’t see past; and, optionally, code sent to the client on demand.
In practice, a REST API names things as resources, such as /customers/42, and the HTTP method says what to do. GET reads, POST creates, PUT replaces, PATCH changes part of a resource and DELETE removes it. Status codes report the result, such as 200 for success, 201 for something created, 401 for missing or invalid credentials and 404 for something that doesn’t exist.
For example, GET /customers/42 returns that customer as JSON, and PATCH /customers/42 with {"plan": "team"} changes only the plan.
HTTP defines GET as safe, because it only reads, and PUT and DELETE as idempotent: sending the same request twice has the same intended effect as sending it once. That’s why a client can retry them after a dropped connection.
Why does a REST API matter for a website voice agent?
A voice agent is only as good as its content and settings, and a REST API lets your own scripts keep them current: add an answer when your docs change, check settings before a release or copy conversations into your own tools. REST runs over plain HTTPS, so curl or any language’s HTTP client can call it.
Before you plan around one, check two things: whether changes made through the API skip a review that the dashboard enforces, and whether the API sends events or has to be polled.
How Kawl Now’s REST API works
Kawl Now has a REST management API under https://app.kawlnow.com/api/manage. It takes your workspace token as a bearer token, sends and receives JSON, and manages one workspace: both agents’ settings, knowledge sources and approvals, GitHub imports, conversations, automatic insights and tokens.
POST /api/manage/sources always saves a new source unapproved, and PATCH /api/manage/sources/{id} with {"approved": true} approves it once someone has read it. GET /api/manage/conversations/{id} returns a conversation with its full transcript, and GET /api/manage/insights returns the automatic insights for support or sales.
There’s no endpoint that starts a call, because visitors start conversations from the widget. The API doesn’t return the embed snippet, sends no webhooks and sets no CORS headers, so call it from server-side code or trusted tools rather than from a web page. Verifying a team phone number for human handover, an early release, needs the signed-in dashboard, and the API refuses workspace tokens for it. The OpenAPI 3.1 file at https://app.kawlnow.com/api/openapi describes each operation a token can use.
curl 'https://app.kawlnow.com/api/manage/workspace' \
-H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'Common questions
Is a REST API the same as an HTTP API?
Not strictly. REST is an architectural style with specific constraints, while any API that runs over HTTP is an HTTP API. In everyday use the terms overlap, because most HTTP APIs with resource URLs and standard methods are called REST even when they skip constraints such as hypermedia links.
Do you need an SDK to call a REST API?
No. A REST API takes ordinary HTTPS requests, so curl or any language’s HTTP client can call it. An SDK only wraps those requests in functions for one programming language.