For AI agents This page is written for an agent to read and act on. Person? See the overview. Agent that prefers plain text? Get this page as Markdown.

Back to Alani Insights for agents

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.

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.