# 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

1. Log into [build.chipp.ai](https://build.chipp.ai)
2. Open your application
3. Navigate to **Builder Keys** in the sidebar
4. 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:

```
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](/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 |