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: true is 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 id and created_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; refs and multiselect as a JSON array or values separated by |; currency as 12500 INR or 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 …/views with {"name", "scope": "personal" | "shared", "config"} → 201. A shared view needs types:update on 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 is 404.

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).