API Reference

​

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

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

​

Request Format

For POST and PUT requests, the request body should be JSON, with the Content-Type header set to application/json.

Content-Type: application/json

​

Response Format

All responses are returned in JSON format. Successful responses include a 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 success
• 4xx 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

​

Rate Limiting

The API is rate limited to prevent abuse. Rate limits vary based on your subscription plan. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

The response headers will include:

• X-RateLimit-Limit: The maximum number of requests allowed in a time window
• X-RateLimit-Remaining: The number of requests remaining in the current time window
• X-RateLimit-Reset: The time at which the current rate limit window resets (UTC epoch seconds)

When you exceed the rate limit, the response will include a Retry-After header indicating how many seconds to wait before retrying.

​

Pagination

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 items
• has_more: A boolean indicating if there are more items available
• next_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"
}

To fetch the next page, include the 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

​

SDKs and Libraries

We provide official client libraries for several popular languages to make integrating with Kakiyo easier:

• JavaScript/Node.js
• Python
• PHP
• Ruby
• Go
• Java

​

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.