What is OpenAPI?

How does an OpenAPI document work?

An OpenAPI document is usually one file, such as openapi.json or openapi.yaml. Its info section names the API and its version. Its paths section lists each URL and HTTP method with its parameters, request body and responses. Its components section holds reusable schemas and security schemes, such as a bearer token, so operations can refer to them instead of repeating them.

Schemas describe the shape of JSON bodies. Since version 3.1, published in February 2021, the Schema Object is a superset of JSON Schema draft 2020-12, so OpenAPI schemas line up with standard JSON Schema. As of October 2026, the newest release is version 3.2.1, a patch release published on 10 September 2026.

Tools read the document to render reference docs, let developers try requests, build test cases or generate client code, which is how many SDKs are produced.

Why does OpenAPI matter for a website voice agent?

An OpenAPI file is the contract for a voice agent’s management API. Your developers can load it into an API client or test runner to see exactly which requests exist, and a coding assistant given the file can write correct calls instead of guessing endpoint names.

It also shows the limits quickly. If an operation you need isn’t in the file, such as starting a call or registering a webhook, ask the vendor before you plan around it.

How Kawl Now uses OpenAPI

Kawl Now publishes an OpenAPI 3.1 file at https://app.kawlnow.com/api/openapi, and anyone can read it without a token. It describes the Kawl Now Management API: each REST operation that takes a workspace token, from reading the workspace to approving sources and creating tokens, with request bodies, responses and errors.

It declares one security scheme, an HTTP bearer token, so tools know to send Authorization: Bearer with your workspace token. The website import operation is marked as unavailable, matching the API, which returns 503 for it.

Kawl Now doesn’t publish an SDK generated from the file. Tools that read OpenAPI 3.1 can generate a client from it, though none has been tested. The MCP server isn’t in the file, because MCP clients get its tool list from the server itself.

{
  "paths": {
    "/api/manage/sources/{id}": {
      "patch": {
        "summary": "Approve or unapprove a source",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "approved"
                ],
                "properties": {
                  "approved": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done"
          },
          "401": {
            "description": "Missing, invalid or revoked workspace token"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "workspaceToken": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}

Common questions