Kapso API Reference

This document details the Kapso External API endpoints for integrating your systems with Kapso WhatsApp AI agents.

​

Authentication

All requests to the Kapso API require authentication using an API Key specific to your project.

X-API-Key: your_project_api_key

Each API key is associated with a single project and provides access to all resources within that project. You can generate API keys in the Kapso web interface under your Project Settings.

​

Response Format

All API responses are returned as JSON with a consistent structure:

​

Success Responses (2XX)

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "Customer Support Bot",
  "created_at": "2023-10-15T12:00:00Z",
  "updated_at": "2023-10-20T14:30:00Z"
}

Successful responses include the requested resource(s) serialized according to the corresponding Blueprint.

​

Error Responses

Common HTTP status codes you may encounter:

400 Bad Request

{
  "error": "Invalid parameters", 
  "message": "Parameter X is required"
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

404 Not Found

{
  "error": "Agent not found"
}

422 Unprocessable Entity

{
  "error": "Execution cannot be resumed", 
  "message": "This execution is not in a paused state"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded", 
  "message": "Please retry after X seconds"
}

500 Internal Server Error

{
  "error": "An unexpected error occurred", 
  "message": "Details about the error"
}

​

Rate Limiting

When a rate limit is exceeded, the API will return a 429 Too Many Requests response with the following headers:

​

Available Endpoints