# 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. > **Note:** 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](/docs/guides/programmatic-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=" \ -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`](/docs/builder-api/sessions#log-a-conversation) endpoint (used by n8n / Zapier / Make.com to push chat turns into the Conversations tab) and the [`POST /consumers/auth`](/docs/builder-api/consumers#authenticate-a-consumer-server-side) 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=" \ -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 resources: `sessions`, `consumers`, `feedback`, `tags`, `knowledge`, `memories`, `analytics`, `circles`. Valid access levels per resource: `read`, `write`, `none`. Builder API has no delete operations. Most `write` operations are additive (append a message, mint a session token), but a few update settings in place: `PATCH /access-ttl-settings` and `PATCH /consumers/{id}/access-ttl` (`consumers` write) and `PUT /circles/{id}/memory` (replaces a circle's memory, circle admins only). ### 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: ``` 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 **Invalid Request Parameters (400)** A query parameter or request body that fails validation returns `invalid_parameter`. The `message` names the first problem found: ```json { "error": { "code": "invalid_parameter", "message": "Number must be less than or equal to 100" } } ``` **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](/docs/builder-api/sessions) | List sessions, get session details, read messages | | [Consumers](/docs/builder-api/consumers) | List and look up consumers | | [Feedback](/docs/builder-api/feedback) | Message ratings | | [Tags](/docs/builder-api/tags) | Message tags | | [Knowledge Sources](/docs/builder-api/knowledge-sources) | Training data status | | [Memories](/docs/builder-api/memories) | User memory entries | | [Analytics](/docs/builder-api/analytics) | Usage and token analytics | | [Circles](/docs/builder-api/circles) | Shared memory and events for connected apps |