# Builder API reference

> Every builder API endpoint: tables, rows, Flows, templates, automations, /me and /catalog, with the scope each needs and the OpenAPI file.

Source: https://docs.theavoxai.com/avox-api/reference

Every endpoint of the builder API, the scope it needs, and where its full description with
examples lives. Start with [Builder API quick start](https://docs.theavoxai.com/avox-api/builder) for keys, permissions,
paging, versions, retries and limits. An AI assistant should read
[API for AI assistants](https://docs.theavoxai.com/avox-api/ai-assistants) first.

> **Note**
>
> The same list, with the schema of every request body, is the
> OpenAPI 3.1 file at [/openapi.json](https://docs.theavoxai.com/openapi.json). It's generated from the checks the API itself
> runs, so it always matches what the API accepts.

All paths start with `https://api.avox.com`. "Write" endpoints are refused for test keys.

The examples on these pages use this small JavaScript helper:

```js
const avox = (path, init = {}) =>
  fetch(`https://api.avox.com/api/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.AVOX_API_KEY}`, "Content-Type": "application/json", ...init.headers },
  }).then((res) => res.json());
```

## Account

| Endpoint | Scope | What it does |
| --- | --- | --- |
| `GET /api/v1/me` | Any key | The key, its Switchboard and number, its scopes, and every limit with what's used. [Details](#get-apiv1me) |
| `GET /api/v1/catalog` | Any key | Premade tables, Flows, templates and automations with their ids, and the allowed types. [Details](#get-apiv1catalog) |

### GET /api/v1/me

**curl**

```bash
curl https://api.avox.com/api/v1/me -H "Authorization: Bearer $AVOX_API_KEY"
```

**JavaScript**

```js
const { data } = await avox("/me");
```

```json
{
  "ok": true,
  "request_id": "req_4f1c9a0b7e2d36a8c5b1f0e9",
  "data": {
    "key": { "id": "8d2f...", "name": "Booking assistant", "prefix": "avx_live_Qm3", "mode": "live", "scopes": ["send", "tables:read", "tables:write", "rows:read", "rows:write"], "scopesSummary": "Send, Tables (write), Table rows (write)", "createdAt": "2026-10-23T08:00:00Z", "expiresAt": null },
    "switchboard": { "id": "b1c2...", "name": "Riverside Salon", "paused": false },
    "whatsappNumber": { "id": "c3d4...", "name": "Front desk", "number": "+91 98••••3210", "status": "connected" },
    "plan": { "name": "Your plan" },
    "limits": {
      "apiCallsToday": { "reads": { "used": 12, "limit": 1234 }, "writes": { "used": 3, "limit": 123 }, "resetsAt": "2026-10-24T00:00:00.000Z" },
      "tables": { "used": 2, "limit": 9 },
      "rowsPerTable": { "limit": 9999 },
      "columnsPerTable": { "limit": 50 },
      "rowsPerRequest": { "limit": 1000 },
      "flows": { "used": 1, "limit": 9 },
      "templates": { "used": 4, "limit": 9 },
      "automations": { "used": 2, "limit": 9, "active": 1, "activeLimit": 9 },
      "liveRequestsThisMonth": { "used": 140, "limit": 9999 }
    },
    "docs": { "forAiAssistants": "https://docs.avox.com/avox-api/ai-assistants", "openapi": "https://docs.avox.com/openapi.json" }
  }
}
```

The numbers above are made up: yours come from your plan (see [Plans](https://docs.theavoxai.com/plans)).

### GET /api/v1/catalog

**curl**

```bash
curl https://api.avox.com/api/v1/catalog -H "Authorization: Bearer $AVOX_API_KEY"
```

**JavaScript**

```js
const { data } = await avox("/catalog");
const appointments = data.tables.find((t) => t.id === "appointments");
```

```json
{
  "ok": true,
  "request_id": "req_...",
  "data": {
    "tables": [{ "id": "appointments", "name": "Appointments", "kind": "calendar", "columns": [{ "key": "customer", "name": "Customer", "type": "text", "required": true, "unique": false }], "sampleRows": 3 }],
    "flows": [{ "id": "appointment_booking", "title": "Appointment booking", "category": "APPOINTMENT_BOOKING", "live": true, "tables": [{ "ref": "slots", "premadeTableId": "time-slots", "purpose": "The free times customers pick from" }, { "ref": "bookings", "premadeTableId": "appointments", "purpose": "Where each booking is saved" }] }],
    "templates": [{ "id": "booking_reminder", "title": "Booking reminder (day before)", "kind": "custom", "category": "UTILITY", "languages": ["en_US", "hi"], "defaultLanguage": "en_US", "mediaHeader": null, "body": "Hi {{1}}, this is a reminder of your {{2}} booking on {{3}} at {{4}}. ..." }],
    "automations": [{ "id": "booking_reminder_day", "name": "Reminder a day before each booking", "triggerType": "table_date", "needs": { "tables": ["appointments"], "apps": [], "approvedTemplate": true, "publishedFlow": false, "calling": false }, "suggestedTemplate": "booking_reminder", "creditsPerRunAtMost": 2 }],
    "types": { "columnTypes": ["text", "long_text", "number", "currency", "..."], "flowCategories": ["SIGN_UP", "..."], "triggerTypes": ["keyword", "..."], "actionTypes": ["send_text", "..."] },
    "scopes": { "all": ["send", "tables:read", "..."] }
  }
}
```

## Tables and rows

Full descriptions and examples: [Tables and rows](https://docs.theavoxai.com/avox-api/tables).

| Endpoint | Scope | What it does |
| --- | --- | --- |
| `GET /api/v1/tables` | `tables:read` | List tables, with the plan's table limits |
| `POST /api/v1/tables` | `tables:write` | Create a table from your columns or a premade |
| `GET /api/v1/tables/{tableId}` | `tables:read` | One table with its columns |
| `PATCH /api/v1/tables/{tableId}` | `tables:write` | Rename, describe, change API name or settings |
| `DELETE /api/v1/tables/{tableId}` | `tables:write` | Delete a table and its rows |
| `POST /api/v1/tables/{tableId}/archive` | `tables:write` | Archive (read-only, kept) |
| `POST /api/v1/tables/{tableId}/restore` | `tables:write` | Restore an archived table |
| `POST /api/v1/tables/{tableId}/columns` | `tables:write` | Add a column |
| `PATCH /api/v1/tables/{tableId}/columns/{columnId}` | `tables:write` | Change a column (type changes convert values) |
| `DELETE /api/v1/tables/{tableId}/columns/{columnId}` | `tables:write` | Delete a column |
| `GET /api/v1/tables/{tableId}/rows` | `rows:read` | List rows with filters, sort and search |
| `POST /api/v1/tables/{tableId}/rows` | `rows:write` | Add up to 1,000 rows, all or nothing |
| `PATCH /api/v1/tables/{tableId}/rows` | `rows:write` | Change up to 1,000 rows, all or nothing |
| `POST /api/v1/tables/{tableId}/rows/delete` | `rows:write` | Delete up to 1,000 rows, all or nothing |
| `POST /api/v1/tables/{tableId}/rows/import` | `rows:write` | Import CSV text (dry run, then commit) |
| `GET /api/v1/tables/{tableId}/rows/{rowId}` | `rows:read` | One row |
| `PATCH /api/v1/tables/{tableId}/rows/{rowId}` | `rows:write` | Change one row |
| `DELETE /api/v1/tables/{tableId}/rows/{rowId}` | `rows:write` | Delete one row |

## Flows

Full descriptions and examples: [Flows](https://docs.theavoxai.com/avox-api/flows).

| Endpoint | Scope | What it does |
| --- | --- | --- |
| `GET /api/v1/flows` | `flows:read` | List Flows |
| `POST /api/v1/flows` | `flows:write` | Create a draft Flow (premade or your JSON) |
| `POST /api/v1/flows/validate` | `flows:read` | Validate Flow JSON without saving |
| `GET /api/v1/flows/{flowId}` | `flows:read` | The Flow, its JSON, live data settings and checks |
| `PATCH /api/v1/flows/{flowId}` | `flows:write` | Change a draft |
| `DELETE /api/v1/flows/{flowId}` | `flows:write` and **Delete Flows** | Delete a draft |
| `POST /api/v1/flows/{flowId}/validate` | `flows:read` | Validate the saved Flow |
| `POST /api/v1/flows/{flowId}/publish` | `flows:write` | Publish a draft |
| `POST /api/v1/flows/{flowId}/deprecate` | `flows:write` and **Delete Flows** | Retire a published Flow |
| `GET /api/v1/flows/{flowId}/live` | `flows:read` | Live data settings |
| `PUT /api/v1/flows/{flowId}/live` | `flows:write` | Save table links |
| `POST /api/v1/flows/{flowId}/live/mode` | `flows:write` | Switch the live data source, or make a new version |
| `GET /api/v1/flows/{flowId}/logs` | `flows:read` | Live request log |
| `GET /api/v1/flows/{flowId}/sends` | `flows:read` | Every send and how far it got |
| `GET /api/v1/flows/{flowId}/responses` | `flows:read` | The answers people sent |

## Templates

Full descriptions and examples: [Templates](https://docs.theavoxai.com/avox-api/templates).

| Endpoint | Scope | What it does |
| --- | --- | --- |
| `GET /api/v1/templates` | `templates:read` | List templates with their status |
| `POST /api/v1/templates` | `templates:write` | Create a template and send it for review |
| `GET /api/v1/templates/library` | `templates:read` | WhatsApp's own template library |
| `GET /api/v1/templates/{templateId}` | `templates:read` | One template and whether it can be edited now |
| `PATCH /api/v1/templates/{templateId}` | `templates:write` | Edit text and category (reviewed again) |
| `DELETE /api/v1/templates/{templateId}` | `templates:write` and **Delete templates** | Delete this language of a template |

## Automations

Full descriptions and examples: [Automations](https://docs.theavoxai.com/avox-api/automations).

| Endpoint | Scope | What it does |
| --- | --- | --- |
| `GET /api/v1/automations` | `automations:read` | List automations |
| `POST /api/v1/automations` | `automations:write` | Create a draft from a trigger and steps, or a premade |
| `GET /api/v1/automations/{automationId}` | `automations:read` | The trigger, steps and problems |
| `PATCH /api/v1/automations/{automationId}` | `automations:write` | Change name, trigger and steps |
| `DELETE /api/v1/automations/{automationId}` | `automations:write` and **Delete automations** | Delete for good |
| `POST /api/v1/automations/{automationId}/activate` | `automations:write` | Switch on |
| `POST /api/v1/automations/{automationId}/deactivate` | `automations:write` | Switch off |
| `GET /api/v1/automations/{automationId}/runs` | `automations:read` | Run log |
| `GET /api/v1/automations/{automationId}/runs/{runId}` | `automations:read` | One run, step by step |
| `GET /api/v1/automations/{automationId}/credits` | `automations:read` | Credit use |

## Related