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

The simplest way — no code — is to ask the Alchemist (the AI assistant on the right side of the builder):

“Create a Builder API key for this app called ‘My integration’.”

The Alchemist returns the raw key once and walks you through saving it as an encrypted secret variable. For a full end-to-end walkthrough including a custom HTTP action and an optional weekly Heartbeat report, see Get Your App’s Own Usage Stats.

If you’re scripting the setup and already have a builder session cookie, you can hit the management endpoint directly:

bash

curl -X POST https://build.chipp.ai/api/applications/YOUR_APP_ID/builder-keys \
  -H "Cookie: session_id=<your-builder-session>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My integration"}'

The response contains data.rawKey — copy it immediately; it’s returned exactly once.

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

Requesting Write Scopes

The default behavior of the management endpoint above is to grant read access on every resource. For the POST /conversations/log endpoint (used by n8n / Zapier / Make.com to push chat turns into the Conversations tab) and the POST /consumers/auth endpoint (used by the embedded widget’s setUser({ token }) flow), the key needs write access on the relevant resource. Pass an explicit scopes object:

bash

curl -X POST https://build.chipp.ai/api/applications/YOUR_APP_ID/builder-keys \
  -H "Cookie: session_id=<your-builder-session>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "n8n write key",
    "scopes": {
      "sessions": "write",
      "consumers": "write",
      "feedback": "read",
      "tags": "read",
      "knowledge": "read",
      "memories": "read",
      "analytics": "read"
    }
  }'

When scopes is provided, any resource not listed defaults to none (no access). Asking the Alchemist for an API key is the recommended path — it grants write on sessions + consumers by default so the new endpoints work out of the box.

Valid access levels per resource: read, write, none. Builder API has no destructive operations — write means “additive” (append a message, mint a session token), not “delete” or “overwrite”.

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