AutessaDB Query

Row-level operations on AutessaDB tables: insert and update rows, run filtered and joined queries, delete in bulk with WHERE conditions, upload files into FILE/IMAGE/AUDIO/VIDEO columns, and run semantic vector search over indexed text.

All paths on this page are relative to https://api.autessa.com/autessa_poweruser/autessadb/query. Every request is a POST with a JSON body, and the target table is selected by the tableId field (a string) in the body — unlike the client AutessaDB API, there is no resourceId query parameter. See the Poweruser API overview for authentication and conventions.

The poweruser key acts as its linked user. Mutating endpoints (insert, update, batch-update, bulk-insert, bulk-update-by-ids, bulk-delete-by-ids, delete-row, batch-delete, generate-upload-link) require WRITE or ADMIN access on the table; read endpoints (including aggregate) work with any access to the table. Table lifecycle (create, schema changes, delete) lives in the AutessaDB Tables API.

Read and aggregation endpoints (get-data, query, join-query, aggregate) are rate-limited per company on a rolling per-minute and per-day basis; the ceiling is generous for normal use. Bulk writes are governed by a per-call row cap instead.

Column values

Every cell travels as an AutessaDbColumnValue object: the column's type plus the matching value field. You send these in values maps on writes, and reads return them in columnData / rowData maps keyed by column name.

Name
columnType
Type
string
Description
One of: SHORT_TEXT, LONG_TEXT, FILE, AUDIO, IMAGE, VIDEO, INTEGER, FLOAT, BOOLEAN, SINGLE_SELECT, MULTI_SELECT. DATETIME is legacy and read-only — it still appears on reads of pre-existing DATETIME columns and on the built-in created_at/updated_at, but new columns cannot be created with it; store timestamps as SHORT_TEXT holding UTC ISO-8601 strings instead.
Name
textValue
Type
string
Description
Value for SHORT_TEXT, LONG_TEXT, SINGLE_SELECT, and DATETIME (ISO-8601, e.g. "2026-06-30T15:30:00").
Name
filePath
Type
string
Description
S3 URI for FILE, AUDIO, IMAGE, and VIDEO columns. Obtain it from /generate-upload-link.
Name
presignedUrl
Type
string
Description
Read-only: pre-signed GET URL for FILE/IMAGE values (10-minute expiry), populated on /get-single-row.
Name
integerValue
Type
integer
Description
Value for INTEGER columns.
Name
floatValue
Type
number
Description
Value for FLOAT columns.
Name
booleanValue
Type
boolean
Description
Value for BOOLEAN columns.
Name
multiSelectValue
Type
array<string>
Description
Values for MULTI_SELECT columns. Each must be in the column's allowedValues.
Name
variableValue
Type
string
Description
Placeholder used by tool configs for type-aware variable replacement; not needed for direct API calls.

Rows returned by reads also include the built-in id, created_at, and updated_at fields.

Text, number, boolean
{
  "name":      { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
  "age":       { "columnType": "INTEGER", "integerValue": 30 },
  "rating":    { "columnType": "FLOAT", "floatValue": 4.5 },
  "is_active": { "columnType": "BOOLEAN", "booleanValue": true }
}

Selects and datetime
{
  "tier":     { "columnType": "SINGLE_SELECT", "textValue": "pro" },
  "channels": { "columnType": "MULTI_SELECT", "multiSelectValue": ["email", "sms"] },
  "signup":   { "columnType": "DATETIME", "textValue": "2026-06-30T15:30:00" }
}

Files (after generate-upload-link)
{
  "resume": {
    "columnType": "FILE",
    "filePath": "s3://autessa-files/company-cP2mK7dX4v/customers/resume/3f9c2a7e.pdf"
  }
}

WHERE conditions

/query, /join-query, /batch-update, and /batch-delete filter rows with the same structure: a list of groups, each holding a list of conditions.

Conditions inside a group are combined with the group's logicalOperator ("AND" or "OR").
Groups are combined with the request's groupsLogicalOperator ("AND" or "OR", default "OR").

WhereGroup

Name
logicalOperator
Type
string
Description
"AND" or "OR" — how to combine the conditions within this group.
Name
conditions
Type
array<WhereCondition>
Description
The conditions in this group.

WhereCondition

Name
columnName
Type
string
Description
The column to filter on. Built-in columns (id, created_at, updated_at) can be used too.
Name
operator
Type
string
Description
One of the operators below (case-insensitive). Defaults to EQUALS when omitted.
Name
value
Type
any
Description
The value to compare against. Scalar for most operators, an array for IN/NOT_IN, omitted for IS_NULL/IS_NOT_NULL.

Operators

Operator	Meaning
`EQUALS` / `NOT_EQUALS`	Exact match / not equal
`GREATER_THAN` / `LESS_THAN`	Greater than / less than
`GREATER_THAN_OR_EQUAL` / `LESS_THAN_OR_EQUAL`	Greater than or equal / less than or equal
`IN` / `NOT_IN`	Value in / not in a list (value must be an array)
`IS_NULL` / `IS_NOT_NULL`	Null check (no value needed)
`CONTAINS`	Substring match
`STARTS_WITH` / `ENDS_WITH`	Prefix / suffix match

Not every operator applies to every column type — invalid combinations are rejected with a descriptive error:

Column type	Supported operators
`SHORT_TEXT`, `LONG_TEXT`	All operators
`INTEGER`, `FLOAT`	All except `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`
`BOOLEAN`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`, `IS_NULL`, `IS_NOT_NULL`
`SINGLE_SELECT`, `MULTI_SELECT`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`, `IS_NULL`, `IS_NOT_NULL`
`FILE`, `IMAGE`, `AUDIO`, `VIDEO`	`IS_NULL`, `IS_NOT_NULL` only

Active adults (AND within a group)
{
  "whereGroups": [
    {
      "logicalOperator": "AND",
      "conditions": [
        { "columnName": "age", "operator": "GREATER_THAN_OR_EQUAL", "value": 18 },
        { "columnName": "status", "operator": "EQUALS", "value": "active" }
      ]
    }
  ]
}

Admins or moderators (OR between groups)
{
  "whereGroups": [
    {
      "logicalOperator": "AND",
      "conditions": [
        { "columnName": "role", "operator": "EQUALS", "value": "admin" }
      ]
    },
    {
      "logicalOperator": "AND",
      "conditions": [
        { "columnName": "role", "operator": "EQUALS", "value": "moderator" }
      ]
    }
  ],
  "groupsLogicalOperator": "OR"
}

IN, IS_NULL, and text search
{
  "whereGroups": [
    {
      "logicalOperator": "AND",
      "conditions": [
        { "columnName": "status", "operator": "IN", "value": ["active", "pending"] },
        { "columnName": "deleted_reason", "operator": "IS_NULL" },
        { "columnName": "email", "operator": "ENDS_WITH", "value": "@example.com" }
      ]
    }
  ]
}

Insert a row

POST/query/insert

Inserts a new row. Required columns must be present, select values must be in the column's allowedValues, and text/number constraints from the schema are enforced. If the table has computed columns, they are calculated in the background — the response carries computationStatus: "COMPUTING" until they land. Inserts fire the table's INSERT triggers.

Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table to insert into.
Name
values
Type
object
Description
Map of column name to column value.

Response

Name
insertedId
Type
integer
Description
Row ID of the new row. Row IDs are plain integers.
Name
newRow
Type
object
Description
The complete inserted row as a map of column name to column value, including built-in fields.
Name
computationStatus
Type
string
Description
"COMPUTING" while computed columns are being calculated in the background; absent otherwise.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
JavaScript
Python

curl https://api.autessa.com/autessa_poweruser/autessadb/query/insert \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "values": {
      "name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
      "email": { "columnType": "SHORT_TEXT", "textValue": "john@example.com" },
      "age": { "columnType": "INTEGER", "integerValue": 30 }
    }
  }'

const response = await fetch(
  'https://api.autessa.com/autessa_poweruser/autessadb/query/insert',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.POWERUSER_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tableId: 'V1StGXR8Z5',
      values: {
        name: { columnType: 'SHORT_TEXT', textValue: 'John Doe' },
        email: { columnType: 'SHORT_TEXT', textValue: 'john@example.com' },
        age: { columnType: 'INTEGER', integerValue: 30 }
      }
    })
  }
);

const { insertedId } = await response.json();

import os
import requests

response = requests.post(
    'https://api.autessa.com/autessa_poweruser/autessadb/query/insert',
    headers={'Authorization': os.environ['POWERUSER_KEY']},
    json={
        'tableId': 'V1StGXR8Z5',
        'values': {
            'name': {'columnType': 'SHORT_TEXT', 'textValue': 'John Doe'},
            'email': {'columnType': 'SHORT_TEXT', 'textValue': 'john@example.com'},
            'age': {'columnType': 'INTEGER', 'integerValue': 30}
        }
    }
)

inserted_id = response.json()['insertedId']

Response
{
  "insertedId": 12345,
  "newRow": {
    "name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
    "email": { "columnType": "SHORT_TEXT", "textValue": "john@example.com" },
    "age": { "columnType": "INTEGER", "integerValue": 30 }
  },
  "errors": []
}

Update a row

POST/query/update

Updates a single row by ID. Only the columns present in values are modified; everything else is untouched. Computed columns that depend on the changed values are recomputed in the background. Updates fire the table's UPDATE triggers.

Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table containing the row.
Name
rowId
Type
integer
Description
The row to update.
Name
values
Type
object
Description
Map of column name to column value for the columns to change.

Response

Name
updatedId
Type
integer
Description
Row ID of the updated row.
Name
oldRow
Type
object
Description
The row before the update, as a column-value map.
Name
newRow
Type
object
Description
The row after the update.
Name
computationStatus
Type
string
Description
"COMPUTING" while computed columns are recalculating; absent otherwise.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/update \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "rowId": 12345,
    "values": {
      "age": { "columnType": "INTEGER", "integerValue": 31 }
    }
  }'

Response
{
  "updatedId": 12345,
  "oldRow": {
    "name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
    "age": { "columnType": "INTEGER", "integerValue": 30 }
  },
  "newRow": {
    "name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
    "age": { "columnType": "INTEGER", "integerValue": 31 }
  },
  "errors": []
}

Batch update rows

POST/query/batch-update

Applies the same values to every row matching the WHERE conditions. whereGroups is required — to update every row, send a condition that explicitly matches all rows. If the match would exceed the server's batch cap (500 rows by default) the whole operation aborts and rolls back with an error telling you to narrow the conditions. Fires the table's UPDATE triggers for each changed row.

Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table to update.
Name
values
Type
object
Description
Map of column name to column value applied to every matching row.
Name
whereGroups
Type
array<WhereGroup>
Description
Condition groups selecting the rows to update.
Name
groupsLogicalOperator
Type
string
Description
"AND" or "OR" — how to combine the groups. Defaults to "OR".

Response

Name
updatedCount
Type
integer
Description
Number of rows updated.
Name
results
Type
array<object>
Description
Per-row detail: rowId (integer), oldRow (object), newRow (object).
Name
computationStatus
Type
string
Description
"COMPUTING" while computed columns are recalculating; absent otherwise.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/batch-update \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "values": {
      "status": { "columnType": "SINGLE_SELECT", "textValue": "archived" }
    },
    "whereGroups": [
      {
        "logicalOperator": "AND",
        "conditions": [
          { "columnName": "status", "operator": "EQUALS", "value": "inactive" },
          { "columnName": "last_login", "operator": "IS_NULL" }
        ]
      }
    ]
  }'

Response (truncated)
{
  "updatedCount": 5,
  "results": [
    {
      "rowId": 12345,
      "oldRow": { "status": { "columnType": "SINGLE_SELECT", "textValue": "inactive" } },
      "newRow": { "status": { "columnType": "SINGLE_SELECT", "textValue": "archived" } }
    }
  ],
  "errors": []
}

Delete a row

POST/query/delete-row

Deletes a single row by ID and returns the deleted data. Fires the table's DELETE triggers.

Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table containing the row.
Name
rowId
Type
integer
Description
The row to delete.

Response

Name
deletedId
Type
integer
Description
Row ID of the deleted row.
Name
oldRow
Type
object
Description
The deleted row as a column-value map.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/delete-row \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "rowId": 12345
  }'

Response
{
  "deletedId": 12345,
  "oldRow": {
    "name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
    "age": { "columnType": "INTEGER", "integerValue": 31 }
  },
  "errors": []
}

Batch delete rows

POST/query/batch-delete

Deletes every row matching the WHERE conditions. whereGroups is required — to delete every row, send a condition that explicitly matches all rows. If the match would exceed the server's batch cap (500 rows by default) the whole operation aborts and rolls back. Fires the table's DELETE triggers for each removed row.

Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table to delete from.
Name
whereGroups
Type
array<WhereGroup>
Description
Condition groups selecting the rows to delete.
Name
groupsLogicalOperator
Type
string
Description
"AND" or "OR" — how to combine the groups. Defaults to "OR".

Response

Name
deletedCount
Type
integer
Description
Number of rows deleted.
Name
results
Type
array<object>
Description
Per-row detail: rowId (integer) and oldRow (object).
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/batch-delete \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "whereGroups": [
      {
        "logicalOperator": "AND",
        "conditions": [
          { "columnName": "status", "operator": "EQUALS", "value": "archived" }
        ]
      }
    ]
  }'

Response (truncated)
{
  "deletedCount": 3,
  "results": [
    {
      "rowId": 12345,
      "oldRow": { "status": { "columnType": "SINGLE_SELECT", "textValue": "archived" } }
    }
  ],
  "errors": []
}

Bulk insert rows

POST/query/bulk-insert

Inserts many rows into a table in a single call. Returns a per-row result list so you can correlate individual outcomes.

Bulk writes suppress the table's triggers by default — a deliberate divergence from single-row insert, whose triggers always fire. Set triggerMode to "PER_ROW" or "BATCH_CONTEXT" to opt in. The row count per call is capped (a generous first-party limit); requests above the cap are rejected. Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table to insert into.
Name
rows
Type
array<object>
Description
List of rows to insert. Each is a column-name → column value map (same shape as a single insert's values).
Name
atomicity
Type
string
Description
"ALL_OR_NOTHING" (default) writes the whole call as one transaction; "BEST_EFFORT_PER_CHUNK" writes in chunks and reports failures per row while earlier chunks stay committed.
Name
indexingMode
Type
string
Description
"IMMEDIATE" (default), "DEFERRED", or "SKIP" — when semantic-search indexing of the written rows happens.
Name
computeMode
Type
string
Description
"IMMEDIATE" (default), "DEFERRED", or "SKIP" — when computed fields are calculated.
Name
triggerMode
Type
string
Description
"SUPPRESS" (default), "PER_ROW", or "BATCH_CONTEXT".

Response

Name
insertedCount
Type
integer
Description
Number of rows actually written.
Name
results
Type
array<object>
Description
One entry per input row: inputIndex (its position in the request), insertedId, newRow, and errors.
Name
computationStatus
Type
string
Description
"COMPUTING" if computed fields are being calculated in the background.
Name
errors
Type
array<string>
Description
Top-level errors when the whole call was rejected.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/bulk-insert \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "rows": [
      { "name": { "columnType": "SHORT_TEXT", "textValue": "Ada" } },
      { "name": { "columnType": "SHORT_TEXT", "textValue": "Grace" } }
    ]
  }'

Response (truncated)
{
  "insertedCount": 2,
  "results": [
    { "inputIndex": 0, "insertedId": 12345, "newRow": { }, "errors": [] },
    { "inputIndex": 1, "insertedId": 12346, "newRow": { }, "errors": [] }
  ],
  "errors": []
}

Bulk update rows by IDs

POST/query/bulk-update-by-ids

Updates many rows by id in a single call. Each update is a partial patch — only the columns you supply change. Same mode fields and defaults as bulk insert (triggers suppressed by default). Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table to update.
Name
updates
Type
array<object>
Description
List of per-row updates. Each is { "id": <rowId>, "values": { ... } }, where values is a partial column-name → column value map.
Name
atomicity
Type
string
Description
"ALL_OR_NOTHING" (default) or "BEST_EFFORT_PER_CHUNK".
Name
indexingMode
Type
string
Description
"IMMEDIATE" (default), "DEFERRED", or "SKIP".
Name
computeMode
Type
string
Description
"IMMEDIATE" (default), "DEFERRED", or "SKIP".
Name
triggerMode
Type
string
Description
"SUPPRESS" (default), "PER_ROW", or "BATCH_CONTEXT".

Response

Name
updatedCount
Type
integer
Description
Number of rows actually written.
Name
results
Type
array<object>
Description
One entry per input row: inputIndex, updatedId, oldRow, newRow, and errors. An id not found or outside your access is reported per-row.
Name
computationStatus
Type
string
Description
"COMPUTING" if computed fields are being recalculated.
Name
errors
Type
array<string>
Description
Top-level errors when the whole call was rejected.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/bulk-update-by-ids \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "updates": [
      { "id": 12345, "values": { "status": { "columnType": "SINGLE_SELECT", "textValue": "done" } } },
      { "id": 12346, "values": { "status": { "columnType": "SINGLE_SELECT", "textValue": "open" } } }
    ]
  }'

Response (truncated)
{
  "updatedCount": 2,
  "results": [
    { "inputIndex": 0, "updatedId": 12345, "oldRow": { }, "newRow": { }, "errors": [] },
    { "inputIndex": 1, "updatedId": 12346, "oldRow": { }, "newRow": { }, "errors": [] }
  ],
  "errors": []
}

Bulk delete rows by IDs

POST/query/bulk-delete-by-ids

Deletes many rows by id in a single call. Only atomicity and triggerMode apply (there is nothing to index or compute on a delete). Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table to delete from.
Name
ids
Type
array<integer>
Description
List of row ids to delete.
Name
atomicity
Type
string
Description
"ALL_OR_NOTHING" (default) or "BEST_EFFORT_PER_CHUNK".
Name
triggerMode
Type
string
Description
"SUPPRESS" (default), "PER_ROW", or "BATCH_CONTEXT".

Response

Name
deletedCount
Type
integer
Description
Number of rows actually removed.
Name
results
Type
array<object>
Description
One entry per input id: inputIndex, deletedId, and errors. An id not found or outside your access is reported per-row.
Name
errors
Type
array<string>
Description
Top-level errors when the whole call was rejected.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/bulk-delete-by-ids \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "ids": [12345, 12346, 12347]
  }'

Response (truncated)
{
  "deletedCount": 3,
  "results": [
    { "inputIndex": 0, "deletedId": 12345, "errors": [] },
    { "inputIndex": 1, "deletedId": 12346, "errors": [] },
    { "inputIndex": 2, "deletedId": 12347, "errors": [] }
  ],
  "errors": []
}

Get table data

POST/query/get-data

Returns paginated rows from a table without filtering, ordered by updated_at (newest first). Use /query to filter.

Request parameters

Name
tableId
Type
string
Description
The table to read.
Name
orderBy
Type
array<OrderBy>
Description
Sort terms in priority order. Each is { "columnName": "...", "direction": "ASC" | "DESC" } (direction defaults to DESC).
Name
page
Type
integer
Description
Page number (1-based). Defaults to 1. Ignored when cursor is set.
Name
pageSize
Type
integer
Description
Rows per page. Defaults to 50; values above 100 are clamped to 100.
Name
cursor
Type
string
Description
Opaque cursor from a prior response's nextCursor, for efficient seek pagination through large tables. When set, page is ignored and the same orderBy must be reused.
Name
includeTotal
Type
boolean
Description
Whether to compute totalRows/totalPages. Offset requests default to true; cursor requests default to false.

Response

Name
schema
Type
object
Description
The table schema (see the schema reference).
Name
rows
Type
array<Row>
Description
Rows on this page. Each has id (integer), columnData (map of column name to column value), columnMetadata, createdAt, and updatedAt.
Name
currentPage
Type
integer
Description
The page returned.
Name
pageSize
Type
integer
Description
Rows per page.
Name
totalRows
Type
integer
Description
Total rows matching the request. null on a cursor request unless includeTotal was set.
Name
totalPages
Type
integer
Description
Total number of pages. null on a cursor request unless includeTotal was set.
Name
nextCursor
Type
string
Description
Cursor to fetch the next page; null when there are no more rows.
Name
hasMore
Type
boolean
Description
Whether another page exists beyond this one.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/get-data \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "page": 1,
    "pageSize": 50
  }'

Response (truncated)
{
  "schema": {
    "tableName": "customers",
    "dbType": "DEFAULT",
    "columnDefinitions": [
      { "columnName": "name", "columnType": "SHORT_TEXT", "required": true },
      { "columnName": "age", "columnType": "INTEGER" }
    ]
  },
  "rows": [
    {
      "id": 12345,
      "columnData": {
        "name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
        "age": { "columnType": "INTEGER", "integerValue": 31 }
      },
      "createdAt": "2026-06-29T10:00:00",
      "updatedAt": "2026-06-30T15:30:00"
    }
  ],
  "currentPage": 1,
  "pageSize": 50,
  "totalRows": 150,
  "totalPages": 3,
  "errors": []
}

Query table data

POST/query/query

Returns paginated rows matching the WHERE conditions. The response has the same shape as /get-data.

Request parameters

Name
tableId
Type
string
Description
The table to query.
Name
whereGroups
Type
array<WhereGroup>
Description
Condition groups to filter by.
Name
groupsLogicalOperator
Type
string
Description
"AND" or "OR" — how to combine the groups. Defaults to "OR".
Name
orderBy
Type
array<OrderBy>
Description
Sort terms in priority order. Each is { "columnName": "...", "direction": "ASC" | "DESC" } (direction defaults to DESC).
Name
page
Type
integer
Description
Page number (1-based). Defaults to 1. Ignored when cursor is set.
Name
pageSize
Type
integer
Description
Rows per page. Defaults to 50, maximum 100.
Name
cursor
Type
string
Description
Opaque cursor from a prior response's nextCursor for seek pagination. When set, page is ignored and the same orderBy must be reused. The response also carries nextCursor / hasMore, and totalRows / totalPages are null unless includeTotal is set.
Name
includeTotal
Type
boolean
Description
Whether to compute totalRows/totalPages. Offset requests default to true; cursor requests default to false.

Response

Same fields as /get-data: schema, rows, currentPage, pageSize, totalRows (matching rows), totalPages, and errors.

cURL
JavaScript
Python

curl https://api.autessa.com/autessa_poweruser/autessadb/query/query \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "whereGroups": [
      {
        "logicalOperator": "AND",
        "conditions": [
          { "columnName": "age", "operator": "GREATER_THAN_OR_EQUAL", "value": 18 },
          { "columnName": "status", "operator": "EQUALS", "value": "active" }
        ]
      }
    ],
    "page": 1,
    "pageSize": 50
  }'

const response = await fetch(
  'https://api.autessa.com/autessa_poweruser/autessadb/query/query',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.POWERUSER_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tableId: 'V1StGXR8Z5',
      whereGroups: [
        {
          logicalOperator: 'AND',
          conditions: [
            { columnName: 'age', operator: 'GREATER_THAN_OR_EQUAL', value: 18 },
            { columnName: 'status', operator: 'EQUALS', value: 'active' }
          ]
        }
      ]
    })
  }
);

const { rows, totalRows } = await response.json();

import os
import requests

response = requests.post(
    'https://api.autessa.com/autessa_poweruser/autessadb/query/query',
    headers={'Authorization': os.environ['POWERUSER_KEY']},
    json={
        'tableId': 'V1StGXR8Z5',
        'whereGroups': [
            {
                'logicalOperator': 'AND',
                'conditions': [
                    {'columnName': 'age', 'operator': 'GREATER_THAN_OR_EQUAL', 'value': 18},
                    {'columnName': 'status', 'operator': 'EQUALS', 'value': 'active'}
                ]
            }
        ]
    }
)

rows = response.json()['rows']

Response (truncated)
{
  "schema": { "tableName": "customers" },
  "rows": [
    {
      "id": 12345,
      "columnData": {
        "name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
        "status": { "columnType": "SINGLE_SELECT", "textValue": "active" }
      },
      "createdAt": "2026-06-29T10:00:00",
      "updatedAt": "2026-06-30T15:30:00"
    }
  ],
  "currentPage": 1,
  "pageSize": 50,
  "totalRows": 25,
  "totalPages": 1,
  "errors": []
}

Join query

POST/query/join-query

Joins the main table with one or more other tables and returns the combined rows, optionally filtered by WHERE conditions applied after the join. Joined column names are prefixed with their table name (orders.user_id, users.name).

Request parameters

Name
tableId
Type
string
Description
The main (left) table.
Name
joins
Type
array<JoinCondition>
Description
The tables to join. Each entry has rightTableId (string — the ID of the table to join with), joinType ("INNER", "LEFT", or "RIGHT"; defaults to "INNER"), leftColumnName (column on the main table), and rightColumnName (column on the right table).
Name
whereGroups
Type
array<WhereGroup>
Description
Optional condition groups applied to the joined result.
Name
groupsLogicalOperator
Type
string
Description
"AND" or "OR" — how to combine the groups. Defaults to "OR".
Name
orderBy
Type
array<OrderBy>
Description
Sort terms (main-table columns) in priority order. Each is { "columnName": "...", "direction": "ASC" | "DESC" }.
Name
page
Type
integer
Description
Page number (1-based). Defaults to 1. Ignored when cursor is set.
Name
pageSize
Type
integer
Description
Rows per page. Defaults to 50, maximum 100.
Name
cursor
Type
string
Description
Opaque cursor from a prior response's nextCursor for seek pagination. When set, page is ignored and the same orderBy must be reused. The response carries nextCursor / hasMore; totalRows / totalPages are null unless includeTotal is set.
Name
includeTotal
Type
boolean
Description
Whether to compute totalRows/totalPages. Offset requests default to true; cursor requests default to false.

Response

Name
mainSchema
Type
object
Description
Schema of the main table.
Name
joinedSchemas
Type
object
Description
Map of joined table ID to that table's schema.
Name
rows
Type
array<JoinedRow>
Description
Joined rows. Each has sourceTableId (ID of the main table), sourceRowId (integer), columnData (all joined columns, prefixed by table name), createdAt, and updatedAt.
Name
currentPage
Type
integer
Description
The page returned.
Name
pageSize
Type
integer
Description
Rows per page.
Name
totalRows
Type
integer
Description
Total joined rows.
Name
totalPages
Type
integer
Description
Total number of pages.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/join-query \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "joins": [
      {
        "rightTableId": "kTn4vB2p9Q",
        "joinType": "INNER",
        "leftColumnName": "user_id",
        "rightColumnName": "id"
      }
    ],
    "whereGroups": [
      {
        "logicalOperator": "AND",
        "conditions": [
          { "columnName": "status", "operator": "EQUALS", "value": "active" }
        ]
      }
    ]
  }'

Response (truncated)
{
  "mainSchema": { "tableName": "orders" },
  "joinedSchemas": {
    "790": { "tableName": "users" }
  },
  "rows": [
    {
      "sourceTableId": "V1StGXR8Z5",
      "sourceRowId": 12345,
      "columnData": {
        "orders.order_id": { "columnType": "SHORT_TEXT", "textValue": "ORD-1042" },
        "orders.user_id": { "columnType": "INTEGER", "integerValue": 88 },
        "users.name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" }
      },
      "createdAt": "2026-06-29T10:00:00",
      "updatedAt": "2026-06-30T15:30:00"
    }
  ],
  "currentPage": 1,
  "pageSize": 50,
  "totalRows": 42,
  "totalPages": 1,
  "errors": []
}

Aggregate

POST/query/aggregate

Runs a grouped aggregation over a table: filter, group by up to a few columns, compute aggregates (COUNT / SUM / AVG / MIN / MAX), optionally filter groups and sort, and return a capped set of groups. Works with any access to the table. Columns hidden from your access are treated as not existing, and columns you may only see in masked form cannot be grouped or aggregated (the request is rejected).

Request parameters

Name
tableId
Type
string
Description
The table to aggregate.
Name
whereGroups
Type
array<WhereGroup>
Description
Optional pre-aggregation filter.
Name
groupsLogicalOperator
Type
string
Description
"AND" or "OR" — how to combine the groups. Defaults to "OR".
Name
groupBy
Type
array<string>
Description
Columns to group by (a small maximum applies). Omit to aggregate the filtered set into a single group.
Name
aggregates
Type
array<object>
Description
The aggregates to compute. Each is { "function": "COUNT" | "SUM" | "AVG" | "MIN" | "MAX", "column": "...", "alias": "..." }. column may be omitted for COUNT. alias is required, unique, and is how the value is returned and referenced by having / orderBy.
Name
having
Type
array<object>
Description
Post-aggregation filters on aggregate aliases. Each is { "alias": "...", "operator": "=" | "!=" | ">" | "<" | ">=" | "<=", "value": <number> }. Multiple conditions are ANDed.
Name
orderBy
Type
array<OrderBy>
Description
Sort by a groupBy column or an aggregate alias.
Name
limit
Type
integer
Description
Maximum number of groups to return (clamped to the configured maximum).

Response

Name
groups
Type
array<object>
Description
One entry per group: key (groupBy column → value; empty when there is no grouping) and values (aggregate alias → numeric value).
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/aggregate \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "groupBy": ["status"],
    "aggregates": [
      { "function": "COUNT", "alias": "count" },
      { "function": "AVG", "column": "age", "alias": "avg_age" }
    ],
    "orderBy": [{ "columnName": "count", "direction": "DESC" }]
  }'

Response (truncated)
{
  "groups": [
    { "key": { "status": "active" }, "values": { "count": 120, "avg_age": 34.2 } },
    { "key": { "status": "inactive" }, "values": { "count": 30, "avg_age": 41.7 } }
  ],
  "errors": []
}

Get a single row

POST/query/get-single-row

Fetches one row by ID. FILE and IMAGE values come back with a presignedUrl (10-minute expiry) so the content can be downloaded directly.

Request parameters

Name
tableId
Type
string
Description
The table containing the row.
Name
rowId
Type
integer
Description
The row to fetch.

Response

Name
schema
Type
object
Description
The table schema.
Name
row
Type
Row
Description
The row: id, columnData, columnMetadata, createdAt, updatedAt.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/get-single-row \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "rowId": 12345
  }'

Response (truncated)
{
  "schema": { "tableName": "customers" },
  "row": {
    "id": 12345,
    "columnData": {
      "name": { "columnType": "SHORT_TEXT", "textValue": "John Doe" },
      "avatar": {
        "columnType": "IMAGE",
        "filePath": "s3://autessa-files/company-cP2mK7dX4v/customers/avatar/2b7c.png",
        "presignedUrl": "https://s3.amazonaws.com/..."
      }
    },
    "createdAt": "2026-06-29T10:00:00",
    "updatedAt": "2026-06-30T15:30:00"
  },
  "errors": []
}

Generate an upload link

POST/query/generate-upload-link

Generates a pre-signed S3 PUT URL for a FILE, IMAGE, AUDIO, or VIDEO column. Upload the bytes to uploadUrl (with the matching Content-Type), then use the returned s3Uri as the column's filePath in /insert or /update. Links expire after 5 minutes.

The fileType must match the column's type:

Column type	Allowed file types
`FILE`	`DOCX`, `DOC`, `PDF`, `TXT`, `XLSX`, `XLS`, `EML`
`IMAGE`	`PNG`, `JPG`, `JPEG`, `GIF`, `WEBP`, `AVIF`, `BMP`, `ICO`, `TIFF`, `TIF`, `HEIC`, `HEIF`
`AUDIO`	`MP3`, `M4A`, `WAV`
`VIDEO`	`MP4`, `AVI`, `MOV`, `WMV`, `FLV`, `MKV`, `WEBM`, `MPEG`, `MPG`

Requires WRITE or ADMIN access on the table.

Request parameters

Name
tableId
Type
string
Description
The table the file belongs to.
Name
columnName
Type
string
Description
The FILE/IMAGE/AUDIO/VIDEO column the file will be stored in.
Name
fileType
Type
string
Description
File extension from the table above, e.g. "PDF".

Response

Name
uploadUrl
Type
string
Description
Pre-signed URL; PUT the file bytes here.
Name
s3Uri
Type
string
Description
S3 URI to use as filePath in insert/update requests.
Name
expiresInSeconds
Type
integer
Description
Lifetime of the upload URL in seconds (300).
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/generate-upload-link \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "columnName": "resume",
    "fileType": "PDF"
  }'

# Then upload the file:
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary '@resume.pdf'

Response
{
  "uploadUrl": "https://s3.amazonaws.com/autessa-files/...",
  "s3Uri": "s3://autessa-files/company-cP2mK7dX4v/customers/resume/3f9c2a7e.pdf",
  "expiresInSeconds": 300,
  "errors": []
}

Semantic search

POST/query/search

Runs semantic vector search over one column. The column must have vectorizeField: true in the table schema, and rows must be indexed (indexing happens automatically on insert/update; use /index-record to reindex manually). Results are ordered by similarity score, highest first, with the full row data attached.

Search strategy adapts to the column type — SHORT_TEXT columns are embedded whole, LONG_TEXT (and extracted FILE/AUDIO content) is also chunked, so matches can point into a specific part of a long document.

Semantic searches are metered and count against the company's semantic search limits; a request over the limit is rejected.

Request parameters

Name
tableId
Type
string
Description
The table to search.
Name
query
Type
string
Description
The natural-language search query.
Name
columnName
Type
string
Description
The vectorized column to search within.
Name
limit
Type
integer
Description
Maximum results. Defaults to 10, maximum 100.
Name
scoreThreshold
Type
number
Description
Minimum similarity score, 0.0–1.0. Defaults to 0.0.
Name
page
Type
integer
Description
Page number (1-based). Defaults to 1.
Name
includeDetails
Type
boolean
Description
Include per-result match details (which embedding matched, character positions for chunked matches, all matching embeddings with scores). Defaults to false.

Response

Name
schema
Type
object
Description
The table schema.
Name
results
Type
array<SearchResult>
Description
Matches ordered by relevance. Each has recordId (integer), score (0.0–1.0), rank (1-based), contentHash, rowData (full row as a column-value map), columnMetadata, createdAt, updatedAt, and — when includeDetails is true — details (embedType, embedIndex, charPosition, allMatches).
Name
totalResults
Type
integer
Description
Total matches before pagination.
Name
currentPage
Type
integer
Description
The page returned.
Name
totalPages
Type
integer
Description
Total number of pages.
Name
metadata
Type
object
Description
Search metadata: query, columnName, columnType, searchStrategy, targetEmbeddingTypes, executionTimeMs.
Name
errors
Type
array<string>
Description
Error messages, if any occurred (unknown column, column not vectorized).

cURL
JavaScript
Python

curl https://api.autessa.com/autessa_poweruser/autessadb/query/search \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "query": "machine learning engineer",
    "columnName": "job_description",
    "limit": 10,
    "scoreThreshold": 0.7
  }'

const response = await fetch(
  'https://api.autessa.com/autessa_poweruser/autessadb/query/search',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.POWERUSER_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tableId: 'V1StGXR8Z5',
      query: 'machine learning engineer',
      columnName: 'job_description',
      limit: 10,
      scoreThreshold: 0.7
    })
  }
);

const { results } = await response.json();
results.forEach(r => console.log(r.score, r.recordId));

import os
import requests

response = requests.post(
    'https://api.autessa.com/autessa_poweruser/autessadb/query/search',
    headers={'Authorization': os.environ['POWERUSER_KEY']},
    json={
        'tableId': 'V1StGXR8Z5',
        'query': 'machine learning engineer',
        'columnName': 'job_description',
        'limit': 10,
        'scoreThreshold': 0.7
    }
)

for result in response.json()['results']:
    print(result['score'], result['recordId'])

Response (truncated)
{
  "schema": { "tableName": "jobs" },
  "results": [
    {
      "recordId": 12345,
      "score": 0.92,
      "rank": 1,
      "contentHash": "8f3a1c2e",
      "rowData": {
        "job_title": { "columnType": "SHORT_TEXT", "textValue": "Senior ML Engineer" },
        "job_description": { "columnType": "LONG_TEXT", "textValue": "We are looking for..." }
      },
      "createdAt": "2026-06-29T10:00:00",
      "updatedAt": "2026-06-30T15:30:00"
    }
  ],
  "totalResults": 25,
  "currentPage": 1,
  "totalPages": 3,
  "metadata": {
    "query": "machine learning engineer",
    "columnName": "job_description",
    "columnType": "LONG_TEXT",
    "searchStrategy": "HYBRID",
    "targetEmbeddingTypes": ["FULL", "CHUNK"],
    "executionTimeMs": 45
  },
  "errors": []
}

Index a record

POST/query/index-record

Rebuilds the vector index for one row: every vectorizable column (SHORT_TEXT, LONG_TEXT, FILE, AUDIO with vectorizeField: true) with non-blank content is re-embedded. Indexing normally happens automatically on insert/update — use this to backfill rows written before a column was vectorized or to repair an index.

If the table has no vectorizable columns the call succeeds with columnsIndexed: 0.

Request parameters

Name
tableId
Type
string
Description
The table containing the row.
Name
rowId
Type
integer
Description
The row to index.

Response

Name
recordId
Type
integer
Description
The indexed row ID.
Name
columnsIndexed
Type
integer
Description
Number of columns that were indexed.
Name
vectorsCreated
Type
integer
Description
Total vectors created (long content produces multiple chunk vectors).
Name
indexingDurationMs
Type
integer
Description
Time taken, in milliseconds.
Name
indexedColumns
Type
array<string>
Description
Names of the columns that were indexed.
Name
errors
Type
array<string>
Description
Error messages, if any occurred (for example row not found).

cURL
curl https://api.autessa.com/autessa_poweruser/autessadb/query/index-record \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "rowId": 12345
  }'

Response
{
  "recordId": 12345,
  "columnsIndexed": 2,
  "vectorsCreated": 15,
  "indexingDurationMs": 234,
  "indexedColumns": ["job_title", "job_description"],
  "errors": []
}

Errors

Every response can carry an errors array of strings; it is empty or absent on success.

Status	When
`200`	Success — still check `errors` for row-level validation messages.
`401`	Missing or invalid poweruser key, or the linked user lacks WRITE/ADMIN access for a mutating endpoint.
`403`	Scoped key without the endpoint in its allow-list.
`408`	Server-side error; `errors` contains the message.

Common validation failures (returned in errors):

Schema violations — missing required column, value not in allowedValues, text/number constraint breaches, unknown column names.
WHERE errors — unknown column in a condition, an operator the column's type doesn't support, IN/NOT_IN without a list value, an invalid operator name (the message lists the valid operators), or a missing whereGroups on batch endpoints.
Batch caps — a batch update/delete matching more rows than the server's cap (500 by default) aborts and rolls back.
Upload-link errors — unknown column, non-file column, or a fileType that doesn't match the column type.
Search errors — column not found, column not vectorized, or the company's semantic search limit exceeded.

Error response
{
  "errors": [
    "Operator 'CONTAINS' is not supported for column 'age' of type INTEGER. Use comparison operators (=, <, >, etc.) instead."
  ]
}

Poweruser API overview
AutessaDB Tables API — create tables, manage schemas, sharing, and deletion
AutessaDB Triggers API — react to inserts, updates, and deletes
Client AutessaDB API — the same row operations with client API keys
AutessaDB tables guide

Column values​

WHERE conditions​

WhereGroup​

WhereCondition​

Operators​

Insert a row​

Request parameters​

Response​

Update a row​

Request parameters​

Response​

Batch update rows​

Request parameters​

Response​

Delete a row​

Request parameters​

Response​

Batch delete rows​

Request parameters​

Response​

Bulk insert rows​

Request parameters​

Response​

Bulk update rows by IDs​

Request parameters​

Response​

Bulk delete rows by IDs​

Request parameters​

Response​

Get table data​

Request parameters​

Response​

Query table data​

Request parameters​

Response​

Join query​

Request parameters​

Response​

Aggregate​

Request parameters​

Response​

Get a single row​

Request parameters​

Response​

Generate an upload link​

Request parameters​

Response​

Semantic search​

Request parameters​

Response​

Index a record​

Request parameters​

Response​

Errors​

Related​

Column values

WHERE conditions

WhereGroup

WhereCondition

Operators

Insert a row

Request parameters

Response

Update a row

Request parameters

Response

Batch update rows

Request parameters

Response

Delete a row

Request parameters

Response

Batch delete rows

Request parameters

Response

Bulk insert rows

Request parameters

Response

Bulk update rows by IDs

Request parameters

Response

Bulk delete rows by IDs

Request parameters

Response

Get table data

Request parameters

Response

Query table data

Request parameters

Response

Join query

Request parameters

Response

Aggregate

Request parameters

Response

Get a single row

Request parameters

Response

Generate an upload link

Request parameters

Response

Semantic search

Request parameters

Response

Index a record

Request parameters

Response

Errors

Related