Builder API Overview

Programmatic access to your Chipp app data -- chat logs, consumers, analytics, and more

The Builder API gives you read access to your Chipp application’s data through a standard REST API. Use it to pull chat transcripts into your CRM, sync consumer data with Google Sheets, build custom dashboards, or connect to automation platforms like Zapier and Make.

ℹ️

The Builder API is separate from the Chat Completions API. The Chat API sends messages to your app. The Builder API reads data from your app.

Quick Start

1. Get Your API Key

Log into build.chipp.ai
Open your application
Navigate to Builder Keys in the sidebar
Create a new key or copy an existing one

API keys use the chipp_ prefix (e.g., chipp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6).

2. Make Your First Request

bash

curl https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/sessions \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"

That’s it. You’ll get back a JSON response with your app’s recent chat sessions.

Base URL

All Builder API endpoints are scoped to a specific application:

plaintext

https://build.chipp.ai/api/v1/apps/{appId}

Replace {appId} with your application’s ID (a UUID).

Authentication

Every request requires a Bearer token in the Authorization header:

bash

Authorization: Bearer chipp_YOUR_API_KEY

Keys are scoped to a single application. A key for App A cannot access App B’s data.

Response Format

All responses use a consistent JSON envelope.

List Endpoints

json

{
  "data": [
    { "id": "...", "..." : "..." }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6...",
    "limit": 25
  }
}

Some endpoints use offset-based pagination instead of cursors:

json

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "total": 142,
    "limit": 25,
    "offset": 0
  }
}

Single Resource Endpoints

json

{
  "data": {
    "id": "...",
    "...": "..."
  }
}

Error Format

Errors return a JSON object with an error field containing code and message:

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Status Codes

Code	Description
200	Success
400	Invalid request parameters
401	Missing or invalid API key
403	Key does not have access to this resource
404	Resource not found
429	Rate limit exceeded
500	Server error

Common Error Responses

Missing API Key (401)

json

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

Invalid Key Format (401)

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key format"
  }
}

Invalid API Key (401)

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Expired API Key (401)

json

{
  "error": {
    "code": "expired",
    "message": "API key has expired"
  }
}

Wrong App (403)

json

{
  "error": {
    "code": "forbidden",
    "message": "API key does not match application"
  }
}

Not Found (404)

json

{
  "error": {
    "code": "not_found",
    "message": "Session not found"
  }
}

Rate Limited (429)

json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

The Retry-After response header contains the number of seconds to wait before retrying.

Rate Limiting

The Builder API allows 120 requests per minute per API key.

Rate limit status is included in successful responses via headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window (120)
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

These X-RateLimit-* headers are only present on successful (non-429) responses. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header containing the number of seconds to wait before retrying.

JavaScript Example

javascript

const APP_ID = "your-app-id";
const API_KEY = "chipp_your_api_key";

async function fetchSessions() {
  const response = await fetch(
    `https://build.chipp.ai/api/v1/apps/${APP_ID}/sessions`,
    {
      headers: {
        Authorization: `Bearer ${API_KEY}`,
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const { data, pagination } = await response.json();
  console.log(`Fetched ${data.length} sessions`);
  console.log(`Has more: ${pagination.has_more}`);
  return data;
}

Paginating Through All Results

javascript

async function fetchAllSessions() {
  const sessions = [];
  let cursor = undefined;

  while (true) {
    const url = new URL(
      `https://build.chipp.ai/api/v1/apps/${APP_ID}/sessions`
    );
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const { data, pagination } = await response.json();

    sessions.push(...data);

    if (!pagination.has_more) break;
    cursor = pagination.next_cursor;
  }

  return sessions;
}

Available Endpoints

Endpoint	Description
Sessions	List sessions, get session details, read messages
Consumers	List and look up consumers
Feedback	Message ratings
Tags	Message tags
Knowledge Sources	Training data status
Memories	User memory entries
Analytics	Usage and token analytics