This section is for developers. It documents every REST API endpoint. If you’re looking for how to use Kakiyo from the dashboard (no code), see the Dashboard Guides instead. Overview
The Kakiyo API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Base URL
All API requests should be made to:
https://api.kakiyo.com/v1
Authentication
The Kakiyo API uses API keys to authenticate requests. You can view and manage your API keys in the Kakiyo dashboard.
Authentication is performed via the Authorization header with a Bearer token:
Authorization: Bearer YOUR_API_KEY
POST and PUT requests, the request body should be JSON, with the Content-Type header set to application/json.
Content-Type: application/json
200 OK status code and the appropriate response data.
Example successful response:
{
"id": "campaign_123456789",
"name": "Summer Outreach Campaign",
"status": "active"
}
Error Handling
Kakiyo uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
2xx range indicates success4xx range indicates an error occurred based on the information provided (e.g., missing required parameters, invalid API key)5xx range indicates an error with Kakiyo’s servers
All error responses include a JSON object with the following structure:
{
"error": "error_code",
"message": "A human-readable description of the error"
}
Common Error Codes
| Status Code | Error Code | Description |
|---|
| 400 | validation_error | The request parameters failed validation |
| 401 | missing_api_key | No API key was provided |
| 401 | invalid_api_key_format | The API key format is invalid |
| 401 | invalid_api_key | The API key is not recognized |
| 403 | forbidden | The API key doesn’t have permissions to perform the request |
| 403 | subscription_inactive | Your subscription is inactive |
| 404 | not_found | The requested resource doesn’t exist |
| 429 | rate_limit_exceeded | Too many requests hit the API too quickly |
| 500 | internal_error | Something went wrong on Kakiyo’s end |
Rate Limiting
The Kakiyo API implements tiered rate limiting to ensure fair usage and system stability. Rate limits are applied per team and vary by endpoint type.
Rate Limit Tiers
| Tier | Requests/Min | Endpoint Types | Examples |
|---|
| High | 60 | Simple read operations | GET /verify, GET /models, GET /webhooks/events |
| Medium | 30 | Standard read operations | GET /campaigns, GET /agents, GET /analytics |
| Low | 15 | Write operations | All POST, PUT, DELETE, GET /prospects/search |
Rate Limit Response
If you exceed the rate limit, you’ll receive a 429 Too Many Requests response:
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Please try again later.",
"retryAfter": 45
}
429 Too Many Requests
Headers:
Retry-After: Seconds until the rate limit resets
Best Practices
- Handle 429 errors: Implement exponential backoff when receiving rate limit errors
- Cache responses: Cache high-tier endpoint responses (models, etc.) to reduce API calls
- Batch operations: Use batch endpoints when adding multiple prospects to minimize API calls
- Respect Retry-After: Wait the specified time before retrying requests
For endpoints that return lists of items, Kakiyo uses cursor-based pagination. These endpoints accept the following parameters:
limit: The number of items to return (default: 20, maximum: 100)after: The cursor to use as the starting point for the next set of results
The response will include:
data: The list of itemshas_more: A boolean indicating if there are more items availablenext_cursor: A cursor to use for the next page of results (only included if has_more is true)
Example:
{
"data": [
{ "id": "campaign_1", "name": "First Campaign" },
{ "id": "campaign_2", "name": "Second Campaign" }
],
"has_more": true,
"next_cursor": "campaign_2"
}
next_cursor value in the after parameter:
GET /v1/campaigns?limit=2&after=campaign_2
Versioning
The Kakiyo API is versioned. The current version is v1. We recommend specifying a version in the URL to ensure API stability for your application.
When we make backwards-incompatible changes to the API, we’ll release a new version. We’ll provide ample notice before deprecating any API versions.
Resources
The Kakiyo API provides access to the following resources:
- Campaigns - Create and manage outreach campaigns
- Prospects - Add and manage prospects
- Products - Manage your product information
- Prompts - Create and manage message templates
- Agents - Manage AI agents that handle conversations
- Workspaces - Manage client workspaces (Agency plan)
SDKs and Libraries
We provide official client libraries for several popular languages to make integrating with Kakiyo easier:
Support
If you have any questions or need help with the API, please contact our support team at support@kakiyo.com or visit our help center.Last modified on April 4, 2026
