Reference

API Reference

Complete reference for Keak's REST API

Overview

The Keak API is a RESTful API that provides programmatic access to all of Keak's features. You can use it to create and manage A/B tests, track conversions, retrieve analytics data, and more.

Base URL

https://api.keak.com/v1

Authentication

API Keys

All API requests require authentication using an API key. Include your API key in the Authorization header as a Bearer token.

Example Request:

curl https://api.keak.com/v1/tests \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Endpoints

Tests

Manage your A/B tests programmatically

GET/tests

List all tests in your account

GET /v1/tests?status=active&limit=10&offset=0

Query Parameters:

  • status - Filter by test status (active, paused, completed)
  • limit - Number of results (default: 20, max: 100)
  • offset - Pagination offset (default: 0)
GET/tests/:id

Get detailed information about a specific test

GET /v1/tests/test_abc123
POST/tests

Create a new A/B test

POST /v1/tests
Content-Type: application/json

{
  "name": "Product Page CTA Test",
  "url": "https://example.com/product",
  "variations": [
    {
      "name": "Control",
      "traffic_split": 50,
      "changes": []
    },
    {
      "name": "Green Button",
      "traffic_split": 50,
      "changes": [
        {
          "selector": ".cta-button",
          "type": "css",
          "property": "background-color",
          "value": "#00ff00"
        }
      ]
    }
  ],
  "goals": [
    {
      "name": "Purchase",
      "event": "purchase",
      "primary": true
    }
  ]
}
PATCH/tests/:id

Update an existing test

DELETE/tests/:id

Delete a test

Conversions

Track conversion events

POST/conversions

Track a conversion event

POST /v1/conversions
Content-Type: application/json

{
  "event": "purchase",
  "user_id": "user_123",
  "test_id": "test_abc123",
  "variation_id": "var_002",
  "value": 99.99,
  "currency": "USD",
  "metadata": {
    "order_id": "ord_456"
  }
}
GET/conversions

List conversions with optional filters

Analytics

Retrieve analytics and test results

GET/tests/:id/results

Get comprehensive results for a test

GET /v1/tests/test_abc123/results?date_from=2024-01-01&date_to=2024-01-31

Error Handling

The API uses standard HTTP response codes to indicate success or failure.

200Success

Request completed successfully

400Bad Request

Invalid request parameters or body

401Unauthorized

Invalid or missing API key

404Not Found

Resource not found

429Rate Limited

Too many requests

500Server Error

Internal server error

Error Response Format:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: name",
    "field": "name"
  }
}

Rate Limits

API requests are rate-limited to ensure system stability and fair usage.

Standard Rate Limit

100 requests per minute per API key

Burst Rate Limit

1000 requests per hour per API key

SDKs and Libraries

While you can use the API directly with any HTTP client, we provide official SDKs for popular languages.

JavaScript / TypeScript

npm install @keak/sdk

Python

Coming soon

Ruby

Coming soon

PHP

Coming soon

Ready to start building?

Get your API key and start integrating with Keak