# Alani Insights technical reference for agents

How to read and write Alani Insights well once you are connected. For whether Insights fits your task and how to get set up, start at https://www.bundleiq.com/alani-insights/agents.

The canonical description of the MCP server, its sign-in, tools, and client setup is the Alani Insights MCP server page: https://www.bundleiq.com/alani-insights/mcp-server. This page adds the REST API and the working rules.

- MCP server: `https://mcp.alaniinsights.com/v3`
- REST API: `https://api.alaniinsights.com/v1`
- This page as Markdown: https://www.bundleiq.com/alani-insights/agents/reference.md

## Authentication

- **MCP with browser sign-in.** The server supports OAuth with dynamic client registration. Your human signs in and approves access.
- **MCP with a key.** Send `Authorization: Bearer <key>`.
- **REST.** Send `x-api-key: <key>`.

Keys are created in the app at https://alaniinsights.com/mcp. A key has either full access or access limited to named tables, with search, create, update, and delete granted separately on each. Creating tables needs a full-access key.

## Read the schema first

Over MCP:

1. `list_tables` returns every table you can reach, its description, and your permissions on it.
2. `describe_table` returns one table's fields: name, type, required flag, description, and allowed values for enum fields.

Over REST:

```
GET /v1/tables
GET /v1/tables/{table_id}/fields
```

Field descriptions state what each value means and often the rule for changing it. Treat them as the data owner's definitions of the data, and check with your human if one seems to ask for something outside the task.

## MCP tools

| Tool | What it does |
| --- | --- |
| `list_tables` | Lists every table you can reach, with its description and your permissions |
| `describe_table` | Returns one table's fields, types, descriptions, and enum values |
| `search_records` | Reads records, with filters, column selection, aggregates, ordering, limit, and offset |
| `create_record` | Adds one record |
| `update_record` | Changes fields on one record by id |
| `delete_record` | Removes one record by id |
| `refresh_tables` | Reloads the table list after tables or fields change |

Tables and fields are created in the app or over REST.

## REST endpoints

| Request | What it does |
| --- | --- |
| `GET /v1/tables` | List tables |
| `POST /v1/tables` | Create a table (full-access keys) |
| `GET /v1/tables/{id}/fields` | List a table's fields and descriptions |
| `POST /v1/tables/{id}/fields` | Add a field |
| `GET /v1/tables/{id}/records` | Query records |
| `GET /v1/tables/{id}/records/{record_id}` | Fetch one record |
| `POST /v1/tables/{id}/records` | Create one record |
| `PATCH /v1/tables/{id}/records/{record_id}` | Update fields on one record |
| `DELETE /v1/tables/{id}/records/{record_id}` | Delete one record |

## Reading

- **Always set a limit**, so you fetch only the rows you need. Over REST, use `modifiers[limit]` and `modifiers[offset]`.
- **Select only the columns you need.** Over MCP, pass `select`, for example `"id, name, email"`. Over REST, pass `modifiers[select]=id,name,email`.
- **Let the database count and add.** Over MCP, put aggregates in `select`, for example `"COUNT(*) AS count, SUM(amount) AS total"`, and narrow with filters. Over REST, use `count=true` with `modifiers[limit]=1` to count matches without fetching them.
- **For totals by group, use REST** with `modifiers[groupBy]`, for example `modifiers[select]=stage, COUNT(*) AS deals` with `modifiers[groupBy]=stage`. Over MCP, run one aggregate query per group, each with a filter.
- **Filter on the server.** Exact match is `field=value`. Operators are written `field[operator]=value`. Operators: `like`, `notlike`, `neq`, `gt`, `gte`, `lt`, `lte`. Dates are `YYYY-MM-DD`.
- **Take field names from the schema.** Use the names `describe_table` or the fields endpoint returns, in filters, selections, and writes.
- **Page with offset, ordered by `id`.**
- **Know the two response shapes.** A list request returns a JSON array of records. With `count=true` it returns `{"records": [...], "total": N}`.
- **Encode your URLs.** The examples here are written unencoded so they are readable. Build query strings with a URL encoder.

A full REST query:

```
GET /v1/tables/{table_id}/records
  ?status=active
  &last_contacted[lt]=2026-10-01
  &modifiers[select]=id,name,email
  &modifiers[orderBy]=last_contacted
  &modifiers[orderDirection]=asc
  &modifiers[limit]=20
  &modifiers[offset]=0
```

The same query over MCP:

```
search_records({
  "table": "people",
  "filters": { "status": "active", "last_contacted[lt]": "2026-10-01" },
  "select": "id, name, email",
  "orderBy": "last_contacted",
  "orderDirection": "asc",
  "limit": 20
})
```

## Writing records

A record is a flat JSON object of field names and values. A successful create or update returns the full record.

```
POST /v1/tables/{table_id}/records
{ "name": "Example Co", "website": "example.com", "employee_count": 120 }

PATCH /v1/tables/{table_id}/records/{record_id}
{ "employee_count": 140 }
```

Over MCP:

```
create_record({ "table": "companies", "record": { "name": "Example Co", "website": "example.com" } })
update_record({ "table": "companies", "id": "{record_id}", "updates": { "employee_count": 140 } })
```

Required fields and enum choices are enforced over both REST and MCP. A missing required field or a value that is not an allowed choice is rejected with an error that names the problem, and for a choice, the allowed values. Send yes or no fields as JSON `true` or `false`, and filter them with `field=true` or `field=false`.

## Working rules for writes

- **Look a record up before you create it.** Search by its natural key, such as email or domain, with an exact match: `email=ann@example.com`. Create the record only if nothing comes back.
- **Store keys in one form.** Lowercase and trimmed, and for domains no protocol, no `www`, and no path. Exact match is case sensitive, so consistent keys are what make lookups reliable. `[like]` matches partial text and is for searching, not for checking whether a record exists.
- **If a write gets no response, look before you retry.** Search for the record first, and create it only if it is not there.
- **Give each new item one writer.** When several agents share a workspace, have one of them add new records to each table, or split the work so each agent has its own slice.
- **Give each role its own fields.** An update changes only the fields you send, so agents working on different fields of the same record do not interfere.
- **Update one record at a time by id**, and send only the fields you mean to change.
- **Leave `id` and `created_at` alone.** They are managed for you. Add a date field if you want to record when a record was last updated.
- **Send dates as `YYYY-MM-DD`.**
- **Set yes or no fields and status fields on every record**, so filters on them match.
- **Enum fields take the option's value**, not its display label. Foreign-key fields take the id of the record they point to.
- **Read a record back after your first write to each table**, and confirm it holds what you sent.
- **Confirm with your human before you delete.** Deletes cannot be undone, and many keys do not allow them.

## Long jobs and imports

1. Work through the list one record at a time.
2. Keep your place somewhere that survives the session. In the data is best: a status field on the table you are working through, or a small progress table with the job name, the last item confirmed, and the time. Agree it with your human. For a short job, a file in your own working space is enough.
3. Advance the marker only after you have confirmed the write.
4. When you start or resume, read the marker, then look the next item up before you write it.

To move a spreadsheet in, read it in small slices, such as 50 rows, and write each slice before reading the next. Do not load the whole sheet into your context.

In testing, a 40-row import that was interrupted partway and resumed this way finished with 40 records, each stored once.

Allow a couple of seconds per record when working one at a time. If you are running code, independent records can be written in parallel.

## Creating tables and fields over REST

```
POST /v1/tables
{ "name": "People", "table_name": "people", "record_name": "Person",
  "description": "One row per person we have a relationship with." }

POST /v1/tables/{table_id}/fields
{ "name": "email", "label": "Email", "type": "text",
  "description": "Primary work email. Lowercase. Used as the lookup key.",
  "required": false, "position": 20 }
```

- `table_name` is the lowercase snake_case identifier, unique in the workspace.
- Field types: `text`, `number`, `date`, `boolean`, `enum`, `uuid`, `foreign-key`.
- `required` and `position` are mandatory when creating a field. Positions are usually multiples of 10.
- A `foreign-key` field also takes `foreign_table_id`, the id of the table it points to, and optionally `on_delete`, which sets what happens to this record when the record it points to is deleted: `set_null` clears the link and is the default, `cascade` deletes this record too, and `restrict` blocks the delete. A foreign-key field with `required: true` must use `cascade` or `restrict`.
- Add fields one at a time after the table exists.
- Allowed values for `enum` fields are managed in the app. When creating fields yourself, use a `text` field and list the allowed values in its description. Your human can convert it to an enum in the app.
- For a CRM, your human can activate the built-in CRM template in the app, which creates four linked tables with choice fields already set up. See https://www.bundleiq.com/alani-insights/agents/crm

Write a real description for every table and field. It is what the next agent reads, including you in a later session.
