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:
list_tablesreturns every table you can reach, its description, and your permissions on it.describe_tablereturns 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]andmodifiers[offset]. - Select only the columns you need. Over MCP, pass
select, for example"id, name, email". Over REST, passmodifiers[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, usecount=truewithmodifiers[limit]=1to count matches without fetching them. - For totals by group, use REST with
modifiers[groupBy], for examplemodifiers[select]=stage, COUNT(*) AS dealswithmodifiers[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 writtenfield[operator]=value. Operators:like,notlike,neq,gt,gte,lt,lte. Dates areYYYY-MM-DD. - Take field names from the schema. Use the names
describe_tableor 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=trueit 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
idandcreated_atalone. 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
- Work through the list one record at a time.
- 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.
- Advance the marker only after you have confirmed the write.
- 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_nameis the lowercase snake_case identifier, unique in the workspace.- Field types:
text,number,date,boolean,enum,uuid,foreign-key. requiredandpositionare mandatory when creating a field. Positions are usually multiples of 10.- A
foreign-keyfield also takesforeign_table_id, the id of the table it points to, and optionallyon_delete, which sets what happens to this record when the record it points to is deleted:set_nullclears the link and is the default,cascadedeletes this record too, andrestrictblocks the delete. A foreign-key field withrequired: truemust usecascadeorrestrict. - Add fields one at a time after the table exists.
- Allowed values for
enumfields are managed in the app. When creating fields yourself, use atextfield 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.