Records API
Create, read, search, filter, sort, update and delete records, import and export CSV, and read the change history.
Records are the rows of your workspace: invoices, customers, products, or any record type you create. This API creates, reads, searches, updates and deletes them, changes many at once, restores them from the trash, imports CSV and Excel files, exports CSV, keeps saved list views and reads their change history.
Every record type works the same way, so one set of routes covers all of them. {typeKey} is the key of the record type, such as invoices. List your types with GET /types.
Endpoints
| Method | Path | Permission | What it does |
|---|---|---|---|
POST |
/orgs/{orgId}/records/{typeKey} |
records:create |
Create a record |
GET |
/orgs/{orgId}/records/{typeKey} |
records:read |
List records, or search, filter and sort them |
GET |
/orgs/{orgId}/records/{typeKey}/{recordId} |
records:read |
Get one record |
PUT |
/orgs/{orgId}/records/{typeKey}/{recordId}/values |
records:update |
Change field values |
GET |
/orgs/{orgId}/records/{typeKey}/{recordId}/values |
records:read |
Read just the values |
DELETE |
/orgs/{orgId}/records/{typeKey}/{recordId} |
records:delete |
Move a record to the trash |
POST |
/orgs/{orgId}/records/{typeKey}/bulk |
records:update or records:delete, per record |
Update or delete many records |
GET |
/orgs/{orgId}/records/{typeKey}/trash |
records:read + records:delete |
List trashed records |
POST |
/orgs/{orgId}/records/{typeKey}/{recordId}/restore |
records:read + records:delete |
Restore a trashed record |
DELETE |
/orgs/{orgId}/records/{typeKey}/{recordId}/purge |
records:read + records:delete |
Delete a trashed record for good |
GET |
/orgs/{orgId}/records/{typeKey}/export |
records:export |
Download CSV (optionally filtered) |
POST |
/orgs/{orgId}/records/{typeKey}/import |
records:import |
Create records from CSV (simple, up to 500 rows) |
POST |
/orgs/{orgId}/records/{typeKey}/import/preview |
records:import |
Upload a CSV or Excel file and check it |
POST |
/orgs/{orgId}/records/{typeKey}/import/check |
records:import |
Re-check an upload with your column mapping |
POST |
/orgs/{orgId}/records/{typeKey}/import/commit |
records:import |
Start a mapped import (create, upsert or update) |
GET |
/orgs/{orgId}/records/{typeKey}/import/{jobId} |
the importer | Import progress |
GET |
/orgs/{orgId}/records/{typeKey}/import/{jobId}/errors.csv |
the importer | Failed rows as CSV |
GET POST |
/orgs/{orgId}/records/{typeKey}/views |
records:read |
List or save list views |
PATCH DELETE |
/orgs/{orgId}/records/{typeKey}/views/{viewId} |
view owner | Change or delete a view |
GET |
/orgs/{orgId}/audit |
audit:read |
Change history |
Permissions can be limited to a record type (the resource is the type key) and can carry conditions such as "only records you own". A record that fails the condition reads as not found. See Policy format.
The record object
{
"id": "0190f0aa-7c1e-7a3b-9d52-4f0e6c1b2a10",
"object_type": "invoices",
"created_by": "0190f0a0-3b44-7d10-8a21-90c4e7f01d55",
"created_at": "2026-10-04T09:30:00Z",
"updated_at": "2026-10-04T09:30:00Z",
"values": {
"number": "INV-1001",
"status": "open",
"issue_date": "2026-10-04",
"amount": { "amount": 12500, "code": "INR" }
}
}
values is keyed by field key. Fields your role may not read are left out.
Value formats
| Field type | Send | Read back |
|---|---|---|
string, text, email, url |
string. Email must be a valid address; URL must be absolute http or https |
string |
number |
number or numeric string, up to 14 digits before and 6 after the decimal point | number |
currency |
{"amount": 12500, "code": "INR"}, or a bare number |
{"amount": …, "code": "INR"} |
bool |
true or false (the strings "true"/"false" are accepted) |
boolean |
date |
"2026-10-04" |
string |
datetime |
RFC 3339, such as "2026-10-04T09:30:00Z" |
RFC 3339 in UTC |
select |
one of the field's options | string |
multiselect |
array of options, no duplicates, at most 100 | array |
ref |
the UUID of another record | string |
refs |
array of record UUIDs, at most 100 | array |
file |
a Drive key (text) | string |
Text limits: string up to 500 characters, text up to 100,000. Sending null clears a field unless it is required. Computed fields (formula fields) are read-only: any value you send for them is ignored.
POST /orgs/{orgId}/records/{typeKey}
Create a record. Permission: records:create.
Request
| Field | Type | Required | Notes |
|---|---|---|---|
values |
object | No | Field values by key. Required fields must be present unless they have a default or an auto-numbering pattern. An empty body creates an empty record if no field is required |
curl -s -X POST https://axisiq.co/api/v1/orgs/$ORG/records/invoices \
-H "Authorization: Bearer $AXIS_KEY" -H "Content-Type: application/json" \
-d '{"values": {"number": "INV-1002", "status": "open", "amount": {"amount": "980.50", "code": "INR"}}}'
Response 201 with the record object.
Errors
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR |
A value breaks its field's type or rules, or a required field is missing |
| 403 | FORBIDDEN |
The role lacks records:create for this type, or a condition fails on the new values |
| 404 | NOT_FOUND |
No such record type |
| 402 | LIMIT_EXCEEDED |
A free-plan cap was reached |
| 409 | DUPLICATE_VALUE |
A unique field already holds the value |
GET /orgs/{orgId}/records/{typeKey}
List records. Newest first. Permission: records:read.
There are two modes. The mode is chosen by the parameters you send.
Plain listing (cursor paging)
| Parameter | Notes |
|---|---|
limit |
1 to 200, default 50 |
cursor |
The next_cursor from the previous page |
ref_field and ref_id |
Together: only records whose reference field ref_field points at the record ref_id. For example the lines of one order |
{
"data": {
"records": [ { "id": "0190f0aa-…", "object_type": "invoices", "values": { "…": "…" } } ],
"next_cursor": "0190f0a9-…"
}
}
When there are no more pages next_cursor is absent. Records your role may not read are skipped, so a page can hold fewer than limit items even when more exist; keep following next_cursor until it is absent.
Search mode (offset paging)
Use any of q, filter, sort, page or offset to search.
| Parameter | Notes |
|---|---|
q |
Text to find. Matches any text field (string or text type) that contains it |
filter |
A JSON array of conditions, URL-encoded. All conditions must match, except those sharing a group number (1 to 20), which match if any one of them does |
sort |
A field key, or created_at. Default is newest first |
dir |
asc or desc. Default desc |
limit |
1 to 200, default 50 |
page |
1-based page number |
offset |
Start position, instead of page |
{ "data": { "records": [ … ], "total": 137 } }
total counts only the records you may read.
Filter syntax
[
{ "field": "status", "op": "eq", "value": "open" },
{ "field": "amount", "op": "gte", "value": "10000" },
{ "field": "issue_date", "op": "lt", "value": "2026-10-01" }
]
value is always a string. The operators you can use depend on the field type:
| Field type | Operators |
|---|---|
string, text, select, email, url |
eq, ne, contains (the default when op is omitted) |
number, currency |
eq (default), ne, gt, gte, lt, lte. The value must be a number. Currency compares the amount |
date, datetime |
eq (default), ne, gt, gte, lt, lte. The value is YYYY-MM-DD or RFC 3339 |
bool |
eq, with "true" or "false" |
ref |
eq, with a record id |
refs, multiselect |
contains (or eq) with one record id or one option: matches when the list holds it. Not sortable |
Either-or conditions: give them the same group. This finds open or pending invoices for one customer:
[
{ "field": "status", "op": "eq", "value": "open", "group": 1 },
{ "field": "status", "op": "eq", "value": "pending", "group": 1 },
{ "field": "customer", "op": "eq", "value": "019f…" }
]
Conditions without a group are always required, so filters written before groups existed keep their meaning.
Fields your role cannot read cannot be filtered on, sorted by, or matched by q. Doing so is a 400 VALIDATION_ERROR.
curl -s -G https://axisiq.co/api/v1/orgs/$ORG/records/invoices \
-H "Authorization: Bearer $AXIS_KEY" \
--data-urlencode 'q=acme' \
--data-urlencode 'filter=[{"field":"status","op":"eq","value":"open"}]' \
--data-urlencode 'sort=due_date' --data-urlencode 'dir=asc' \
--data-urlencode 'limit=100'
Errors: 400 VALIDATION_ERROR (bad limit, page, offset, or a filter that is not a JSON array of {field, op, value}), 403 FORBIDDEN (no way to read this type), 404 NOT_FOUND (no such type).
GET /orgs/{orgId}/records/{typeKey}/{recordId}
Get one record. Permission: records:read. Returns the record object. A record you may not read answers 404 NOT_FOUND.
PUT /orgs/{orgId}/records/{typeKey}/{recordId}/values
Change values on a record. Fields you do not send are left alone. Permission: records:update.
Request
{ "values": { "status": "paid", "amount": { "amount": "980.50", "code": "INR" } } }
| Field | Type | Required | Notes |
|---|---|---|---|
values |
object | Yes | Field values by key. null clears a field |
Response 204 No Content.
Fields marked write-once (immutable) cannot be changed after creation. A required field cannot be cleared.
Errors
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR |
Body is not {"values": {...}}, or a value breaks its rules |
| 403 | FORBIDDEN |
The role lacks records:update for this record |
| 404 | NOT_FOUND |
No such record, or you may not read it |
| 409 | DUPLICATE_VALUE |
A unique field already holds the value |
GET /orgs/{orgId}/records/{typeKey}/{recordId}/values
Returns {"data": {"values": { … }}} with the readable values.
DELETE /orgs/{orgId}/records/{typeKey}/{recordId}
Move a record to the trash. Permission: records:delete. Returns 204 No Content.
The record disappears from every list, search and export at once. It stays in the trash for 30 days, then it is deleted for good. Other records that reference it keep the id. A unique value held only by a trashed record does not block a new record: the trashed holder is deleted for good to make room.
POST /orgs/{orgId}/records/{typeKey}/bulk
Update or delete many records in one call. Each id runs through the same path as a single update or delete — permission and conditions per record, validation, locked documents, audit and record events — so one refusal never stops the rest.
Request
| Field | Type | Required | Notes |
|---|---|---|---|
action |
string | Yes | update or delete (to the trash) |
ids |
array | Yes | Up to 500 record ids. Duplicates run once |
values |
object | For update |
Field values by key, as for PUT …/values |
curl -s -X POST https://axisiq.co/api/v1/orgs/$ORG/records/orders/bulk \
-H "Authorization: Bearer $AXIS_KEY" -H "Content-Type: application/json" \
-d '{"action": "update", "ids": ["0190f0aa-…", "0190f0ab-…"], "values": {"status": "shipped"}}'
Response 200
{ "data": { "results": [ { "id": "0190f0aa-…", "ok": true }, { "id": "0190f0ab-…", "ok": false, "error": "record not found" } ], "succeeded": 1, "failed": 1 } }
An id you may not read reads record not found.
Trash
GET /orgs/{orgId}/records/{typeKey}/trash
The type's trashed records you may read and delete, newest delete first, at most 200.
{ "data": { "records": [ { "id": "0190f0aa-…", "object_type": "invoices", "values": { "…": "…" }, "deleted_at": "2026-10-14T08:12:00Z", "deleted_by": "0190f0a0-…" } ], "retention_days": 30 } }
deleted_by is absent when it is not known.
POST /orgs/{orgId}/records/{typeKey}/{recordId}/restore
Bring a trashed record back with its values exactly as deleted. Returns 200 with the record object. Restoring counts as an update (record events say updated, never created). A live or unknown id is 404 NOT_FOUND; lacking records:delete is 403 FORBIDDEN; a free-plan cap is 402 LIMIT_EXCEEDED.
DELETE /orgs/{orgId}/records/{typeKey}/{recordId}/purge
Delete a trashed record for good. Returns 204. A live id is 404 NOT_FOUND.
GET /orgs/{orgId}/records/{typeKey}/export
Download the records of a type as CSV. Permission: records:export (and read access to the type).
Optional q, filter, sort and dir take the same values as search mode and export exactly that list. Without them every record is exported.
- The first row is
id,created_at, then every field key. - Only records and fields your role may read are included.
- At most 10,000 records. If there were more, the response header
X-Export-Truncated: trueis set. - A cell that a spreadsheet could read as a formula (starting with
=,+,-,@) gets a leading'. Plain numbers and phone numbers are left as they are. Import removes the same'. - Currency cells read
12500 INR. List cells (refs,multiselect) are JSON arrays.
curl -s https://axisiq.co/api/v1/orgs/$ORG/records/invoices/export \
-H "Authorization: Bearer $AXIS_KEY" -o invoices.csv
POST /orgs/{orgId}/records/{typeKey}/import
Create records from a CSV. Permission: records:import.
Send either a multipart upload with a file field, or the CSV as the raw body with Content-Type: text/csv.
curl -s -X POST https://axisiq.co/api/v1/orgs/$ORG/records/invoices/import \
-H "Authorization: Bearer $AXIS_KEY" -H "Content-Type: text/csv" \
--data-binary @invoices.csv
- The first row is a header. Each column name must be a field key; other columns (including
idandcreated_at) are ignored. - Up to 500 data rows per request. More is a
400 VALIDATION_ERROR: split the file. - Empty cells are left unset, so defaults and auto-numbering still apply.
- Cell formats: booleans
true/false;refsandmultiselectas a JSON array or values separated by|; currency as12500 INRor a bare amount. - Rows are independent. A bad row is reported and skipped and the others are still created.
Response
{
"data": {
"created": 48,
"failed": 2,
"errors": [
{ "row": 7, "message": "amount: expected a number" },
{ "row": 19, "message": "a unique field already holds this value" }
]
}
}
row counts data rows starting at 1, not counting the header.
Mapped import (CSV or Excel)
A three-step import for larger or messier files: upload and check, map columns, then run in the background. Permission: records:import, plus records:create or records:update on each row it writes.
POST …/import/preview
Multipart upload: file (.csv, .tsv, .txt, .xlsx, .xlsm, up to 10 MB and 10,000 data rows), optional sheet (Excel sheet name) and header_row (1-based; found automatically if omitted).
{
"data": {
"import_id": "c1f0…",
"name": "customers.xlsx",
"sheets": ["Customers", "Notes"],
"sheet": "Customers",
"header_row": 1,
"columns": [ { "index": 0, "name": "Mobile", "samples": ["98200 12345"], "suggested": "phone" } ],
"total": 50, "valid": 48, "invalid": 2,
"rows": [ { "row": 7, "cells": ["…"], "errors": { "2": "not a valid email address" } } ],
"missing_required": ["name"]
}
}
rows holds the first 50 rows; errors is keyed by column index ("row" for the whole row). The upload is kept for 6 hours and only you can use its import_id. The check covers value formats and field rules; unique values and permissions are only known when rows are saved. Dates are read day first (14/10/2026), and Excel date cells are converted.
POST …/import/check
{"import_id", "mapping", "mode", "match_field"} → the same shape as preview, for that mapping. mapping has one entry per column: a field key, or "" to skip it.
POST …/import/commit
{ "import_id": "c1f0…", "mapping": ["name", "phone", ""], "mode": "upsert", "match_field": "phone" }
mode |
Meaning |
|---|---|
create |
Every row is a new record |
upsert |
Update the record whose match_field equals the row's value; create one when none matches |
update |
Update matching records only; a row with no match fails with no record matches |
match_field is a mapped field key, or id for a column headed id. It is required for upsert and update. A row matching several records fails. Blank cells are skipped, so an update never clears a field. Reference fields take record ids.
Response 202 with the job: {"id", "status": "running", "total", "done", "created", "updated", "failed", "errors": [{"row", "message"}]}.
GET …/import/{jobId}
The job as above; status becomes done or failed (message says why). Poll about once a second. Only the person who started the import can read it.
GET …/import/{jobId}/errors.csv
The failed rows as uploaded, plus an error column.
Saved views
Saved list views are stored per record type. A view's config is a JSON object (up to 16 KB) such as {"columns": ["name", "city"], "filters": [{"field": "city", "op": "eq", "value": "Pune"}], "sort": "created_at", "dir": "desc"}.
GET …/views→{"views": [{"id", "type_key", "scope", "owner_id", "name", "config", "mine", "can_edit", "updated_at"}], "can_share"}— shared views and your own personal ones.POST …/viewswith{"name", "scope": "personal" | "shared", "config"}→201. Asharedview needstypes:updateon the type. At most 100 views per type; names up to 60 characters.PATCH …/views/{viewId}with{"name"?, "config"?}→200;DELETE→204. Personal views belong to their creator; another person's personal view is404.
Saved views appear after the owner applies the workspace update that adds them; before that these routes answer 404.
GET /orgs/{orgId}/audit
The change history of records. Permission: audit:read.
| Parameter | Notes |
|---|---|
object_type |
Record type key |
record_id |
One record |
actor |
A person's or service account's id |
action |
record.created, record.updated, record.deleted, record.restored or record.purged |
from, to |
RFC 3339 range |
limit |
Default 50, maximum 200 |
offset |
Start position |
{
"data": {
"entries": [
{
"id": "0190f0ab-…",
"actor_id": "0190f0a0-…",
"actor_type": "service",
"action": "record.updated",
"object_type": "invoices",
"record_id": "0190f0aa-…",
"before": { "status": "open" },
"after": { "status": "paid" },
"request_id": "9f2c41a0b7d3e655",
"created_at": "2026-10-04T10:02:11Z"
}
],
"total": 1
}
}
actor_type is user, service (an access key) or system (a change made by the platform itself with no signed-in caller).
Related
- Record types and fields
- Permissions reference
- In the product: Records