Skip to main content

AutessaDB Tables

The AutessaDB Tables API manages the lifecycle of AutessaDB tables: create regular tables and knowledge bases, inspect and update schemas, control sharing and ownership, analyze trigger cascades, and safely delete tables with a two-step confirmation flow.

All endpoints are POST and accept a JSON body. Requests are scoped to the company that owns the poweruser key.

Base URL​

https://api.autessa.com/autessa_poweruser/autessadb/tables

Authentication​

Pass your poweruser key in the Authorization header (no "Bearer" prefix):

Authorization: pwrusr:{key_id}:{secret}

The examples below use $POWERUSER_KEY as a stand-in for the full pwrusr:... value.

Column types​

Every column in an AutessaDB table has one of twelve types. Text-like types can additionally be vectorized (vectorizeField: true) to make their content available for semantic search.

TypeVectorizableCharacter limitNotes
SHORT_TEXTYes32,000Plain text; limit matches embedding model constraints.
LONG_TEXTYes128,000Long-form text; limit matches long-context embedding constraints.
FILEYes—File stored in S3; content is extracted and analyzed for vectorization.
AUDIOYes—Audio file; transcribed before vectorization.
IMAGENo—Image file reference.
VIDEONo—Video file reference.
INTEGERNo—Whole numbers; supports numberConfiguration bounds.
FLOATNo—Decimal numbers; supports numberConfiguration bounds.
BOOLEANNo—True/false.
SINGLE_SELECTNo—One value from allowedValues.
MULTI_SELECTNo—Multiple values from allowedValues.

Store timestamps as SHORT_TEXT holding UTC ISO-8601 strings (e.g. 2026-07-15T14:30:00Z). DATETIME is a legacy, read-only type: existing DATETIME columns still read back their stored value, but it is rejected when creating a table or adding a column.

Only SHORT_TEXT, LONG_TEXT, FILE, and AUDIO support vectorizeField — the same list returned by /table-options. Setting vectorizeField: true on any other type is rejected.

Schema reference​

A table's structure is described by a schema object. You send one when creating a table, and every read endpoint returns the current schema.

Schema object​

  • Name
    tableName
    Type
    string
    Description

    The table's name. On /create the server sets this from the request's top-level tableName.

  • Name
    columnDefinitions
    Type
    array<object>
    Description

    The user-defined columns. See Column definition below.

  • Name
    builtInColumns
    Type
    array<object>
    Description

    Server-populated on reads: the automatic id (INTEGER), created_at (DATETIME), and updated_at (DATETIME) columns every table has. Do not send these when creating a table.

  • Name
    dbTriggers
    Type
    array<object>
    Description

    Triggers attached to the table. Managed through the AutessaDB Triggers API, not this endpoint group.

  • Name
    triggerSettings
    Type
    object
    Description

    Table-level trigger settings. Also managed through the triggers API.

  • Name
    dbType
    Type
    string
    Description

    One of DEFAULT, KNOWLEDGE_BASE, or DEPENDENT. Defaults to DEFAULT when omitted. KNOWLEDGE_BASE tables are created by /create-knowledge-base; DEPENDENT tables are created by connectors and cannot be shared, transferred, or deleted directly.

  • Name
    tags
    Type
    array<string>
    Description

    Free-form tags on the table.

  • Name
    appendOnly
    Type
    boolean
    Description

    Whether the table is append-only (immutable / audit-grade). When true, rows can be inserted and read but never updated or deleted — every update and delete is rejected for all callers. Additional restrictions apply: computed columns cannot be defined on an append-only table, and column removal is blocked (the schema can only grow). This flag is a one-way latch — it can be turned on but never off. Set it on Create Table; dropping the whole table remains a separate admin operation. Defaults to false.

Column definition​

  • Name
    columnType
    Type
    string
    Description

    One of the twelve column types.

  • Name
    columnName
    Type
    string
    Description

    The column's name. Validated on create; must not collide with built-in columns.

  • Name
    columnComment
    Type
    string
    Description

    Human-readable description of the column.

  • Name
    required
    Type
    boolean
    Description

    Whether a value is required on insert.

  • Name
    numberConfiguration
    Type
    object
    Description

    Bounds for INTEGER/FLOAT columns. Fields: minValue (number), maxValue (number).

  • Name
    textConfiguration
    Type
    object
    Description

    Length constraints for text columns. Fields: maxLength (integer), minLength (integer). maxLength may not exceed the type's character limit (32,000 for SHORT_TEXT, 128,000 for LONG_TEXT).

  • Name
    vectorizeField
    Type
    boolean
    Description

    Index this column's content for semantic search. Only valid on SHORT_TEXT, LONG_TEXT, FILE, and AUDIO columns.

  • Name
    indexed
    Type
    boolean
    Description

    Add an equality index on this column for faster filtering. INTEGER, FLOAT, BOOLEAN, SINGLE_SELECT, and foreign-key columns are always indexed, so the flag is accepted as a no-op for them. SHORT_TEXT can opt in — but once a SHORT_TEXT column is indexed its values are length-capped to 2000 characters. LONG_TEXT, MULTI_SELECT, and media columns cannot be indexed and are rejected.

  • Name
    defaultValue
    Type
    object
    Description

    Hardcoded default as a column-value object. Set columnType plus the matching value field: textValue (string), filePath (string), integerValue (integer), floatValue (float), booleanValue (boolean), or multiSelectValue (array<string>).

  • Name
    computationValue
    Type
    object
    Description

    Computed-column definition. Fields: script (string — AutessaScript source), dependsOn (array<string> — column names the computation reads), type (string — SCRIPT, AGENTIC_FLOW, LLM_CALL, or CUSTOM; defaults to SCRIPT), timeoutMs (integer — computation timeout in milliseconds, default 600000).

  • Name
    allowedValues
    Type
    array<string>
    Description

    The permitted values for SINGLE_SELECT and MULTI_SELECT columns.

  • Name
    valueToDisplayNameMapping
    Type
    object
    Description

    Optional map of allowed value to display name for select columns.

  • Name
    isForeignKey
    Type
    boolean
    Description

    Marks this column as a foreign key. Foreign keys can only reference the id field of another AutessaDB table.

  • Name
    foreignKeyTableId
    Type
    string
    Description

    The referenced table's ID. Required when isForeignKey is true; the table must exist in your company or the create fails.

Example column definition
{
  "columnType": "SHORT_TEXT",
  "columnName": "email",
  "columnComment": "Customer email address",
  "required": true,
  "textConfiguration": {
    "minLength": 3,
    "maxLength": 320
  },
  "vectorizeField": false,
  "isForeignKey": false
}
Foreign key column
{
  "columnType": "INTEGER",
  "columnName": "account_id",
  "columnComment": "Owning account",
  "required": true,
  "isForeignKey": true,
  "foreignKeyTableId": "kTn4vB2p9Q"
}
Computed column
{
  "columnType": "SHORT_TEXT",
  "columnName": "file_name",
  "columnComment": "File name extracted from full_path",
  "required": true,
  "computationValue": {
    "script": "// AutessaScript...",
    "dependsOn": ["full_path"],
    "type": "SCRIPT",
    "timeoutMs": 5000
  }
}

Get Table Options POST/table-options​

Returns which column types support vectorization. Useful for building schema editors without hardcoding the type list.

Request Body​

No request body fields. Send an empty JSON object.

Response​

  • Name
    vectorizableColumns
    Type
    array<string>
    Description

    Column types that allow vectorizeField: true: SHORT_TEXT, LONG_TEXT, FILE, AUDIO.

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/table-options' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'
JSON
{
  "vectorizableColumns": ["SHORT_TEXT", "LONG_TEXT", "FILE", "AUDIO"]
}

Create Table POST/create​

Creates a new AutessaDB table from a schema. The server validates the table name (it must be unique within your company), every column name, text length constraints against the type's character limit, and any foreign key references before creating the table.

Two convenience behaviors happen automatically:

  • For every vectorizable FILE column, a companion notes column is auto-generated to hold extracted file content.
  • For every vectorizable AUDIO column, a companion transcription column is auto-generated.

Every table also gets built-in id, created_at, and updated_at columns — do not define these yourself.

Set schema.appendOnly to true to create an immutable, audit-grade table — rows can be inserted and read but never updated or deleted (every update/delete is rejected for all callers), computed columns cannot be defined, and later column removal is blocked. The flag is a one-way latch (see the Schema object). Set indexed: true on a column definition to add an equality index for faster filtering (see Column definition for which types support it and the 2000-character cap on indexed SHORT_TEXT).

Request Body​

  • Name
    tableName
    Type
    string
    Description

    Name for the new table. Must be unique within your company.

  • Name
    schema
    Type
    object
    Description

    The table schema. See the Schema reference. columnDefinitions is the important part; dbType defaults to DEFAULT when omitted. Set appendOnly: true for an immutable table, and indexed: true on individual columns to index them.

Response​

  • Name
    tableId
    Type
    string
    Description

    ID of the newly created table.

curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/create' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableName": "customers",
    "schema": {
      "columnDefinitions": [
        {
          "columnType": "SHORT_TEXT",
          "columnName": "email",
          "columnComment": "Customer email address",
          "required": true
        },
        {
          "columnType": "LONG_TEXT",
          "columnName": "notes",
          "columnComment": "Free-form account notes",
          "vectorizeField": true
        },
        {
          "columnType": "SINGLE_SELECT",
          "columnName": "tier",
          "allowedValues": ["free", "pro", "enterprise"]
        }
      ],
      "tags": ["crm"]
    }
  }'
JSON
{
  "tableId": "V1StGXR8Z5"
}

Create Knowledge Base POST/create-knowledge-base​

Creates a knowledge base: an AutessaDB table (dbType: KNOWLEDGE_BASE) purpose-built for semantic search over uploaded files. The full workflow is:

  1. Call /generate-knowledge-base-upload-links to get presigned S3 upload URLs.
  2. PUT each file's bytes to its uploadUrl.
  3. Call this endpoint with each file's logical fullPath and the s3Uri returned alongside its upload link.

The table is created with three columns:

  • full_path (SHORT_TEXT, required) — the file's path including folders.
  • file_name (SHORT_TEXT, required, computed) — extracted from full_path.
  • file (FILE, required, vectorizeField: true) — the file content, vectorized for semantic search.

Files are moved from their temporary upload location to permanent storage, then inserted as rows. Row inserts that fail are reported in errors while successful inserts still count toward filesInserted.

Request Body​

  • Name
    tableName
    Type
    string
    Description

    Name for the knowledge base table. Must be unique within your company.

  • Name
    files
    Type
    array<object>
    Description

    At least one file. Each entry has fullPath (string, required — logical path such as docs/handbook.pdf; duplicates are rejected) and s3Uri (string, required — must start with s3://; use the value returned by the upload-links endpoint).

Response​

  • Name
    tableId
    Type
    string
    Description

    ID of the created knowledge base table.

  • Name
    tableName
    Type
    string
    Description

    Name of the created table.

  • Name
    filesInserted
    Type
    integer
    Description

    How many of the requested files were successfully inserted as rows.

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/create-knowledge-base' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableName": "product_docs",
    "files": [
      {
        "fullPath": "docs/getting-started.pdf",
        "s3Uri": "s3://autessa-uploads/temp/knowledge_base/1024/3f9c2a7e"
      },
      {
        "fullPath": "docs/api/reference.md",
        "s3Uri": "s3://autessa-uploads/temp/knowledge_base/1024/8b1d4c5f"
      }
    ]
  }'
JSON
{
  "tableId": "aB3xK9mQ2w",
  "tableName": "product_docs",
  "filesInserted": 2
}

Generate Knowledge Base Upload Links POST/generate-knowledge-base-upload-links​

Generates presigned S3 PUT URLs for uploading knowledge base files. Each link comes with the s3Uri you later pass to /create-knowledge-base.

Links point at a temporary location and expire after 5 minutes — upload promptly, then create the knowledge base (which moves files to permanent storage).

Request Body​

  • Name
    count
    Type
    integer
    Description

    Number of upload links to generate. Must be between 1 and 50.

Response​

  • Name
    uploadLinks
    Type
    array<object>
    Description

    One entry per requested link. Each has uploadUrl (string — presigned S3 PUT URL) and s3Uri (string — the S3 URI to reference in /create-knowledge-base).

  • Name
    expiresInSeconds
    Type
    integer
    Description

    Lifetime of the presigned URLs in seconds (300).

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/generate-knowledge-base-upload-links' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "count": 2
  }'
JSON
{
  "uploadLinks": [
    {
      "uploadUrl": "https://autessa-uploads.s3.amazonaws.com/temp/knowledge_base/1024/3f9c2a7e?X-Amz-Signature=...",
      "s3Uri": "s3://autessa-uploads/temp/knowledge_base/1024/3f9c2a7e"
    },
    {
      "uploadUrl": "https://autessa-uploads.s3.amazonaws.com/temp/knowledge_base/1024/8b1d4c5f?X-Amz-Signature=...",
      "s3Uri": "s3://autessa-uploads/temp/knowledge_base/1024/8b1d4c5f"
    }
  ],
  "expiresInSeconds": 300
}

Get Table POST/get​

Fetches a single table, including its full schema (with server-populated builtInColumns) and your effective access level. Requires at least read access to the table.

Request Body​

  • Name
    tableId
    Type
    string
    Description

    ID of the table to fetch.

Response​

  • Name
    permission
    Type
    string
    Description

    Your access level on the table: READ, WRITE, PUBLISH, or ADMIN.

  • Name
    table
    Type
    object
    Description

    The table. Fields: tableId (string), tableName (string), tableSchema (object — see Schema reference).

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/get' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableId": "V1StGXR8Z5"
  }'
JSON
{
  "permission": "ADMIN",
  "table": {
    "tableId": "V1StGXR8Z5",
    "tableName": "customers",
    "tableSchema": {
      "tableName": "customers",
      "dbType": "DEFAULT",
      "tags": ["crm"],
      "columnDefinitions": [
        {
          "columnType": "SHORT_TEXT",
          "columnName": "email",
          "columnComment": "Customer email address",
          "required": true,
          "isForeignKey": false
        }
      ],
      "builtInColumns": [
        {
          "columnType": "INTEGER",
          "columnName": "id",
          "columnComment": "Unique identifier for each record",
          "required": true,
          "isForeignKey": false
        },
        {
          "columnType": "DATETIME",
          "columnName": "created_at",
          "columnComment": "Timestamp when record was created",
          "required": true,
          "isForeignKey": false
        },
        {
          "columnType": "DATETIME",
          "columnName": "updated_at",
          "columnComment": "Timestamp when record was last updated",
          "required": true,
          "isForeignKey": false
        }
      ],
      "dbTriggers": []
    }
  }
}

List All Tables POST/all​

Lists every table visible to the authenticated user in the current company scope, split into three buckets: tables you own, tables shared company-wide, and tables shared with you individually.

Request Body​

No request body fields. Send an empty JSON object.

Response​

  • Name
    ownedTables
    Type
    array<object>
    Description

    Tables owned by the authenticated user. Each entry has tableId (string), tableName (string), and tableSchema (object).

  • Name
    companySharedTables
    Type
    array<object>
    Description

    Tables shared at the company level. Same shape as ownedTables.

  • Name
    sharedWithMeTables
    Type
    array<object>
    Description

    Tables shared directly with the user. Same shape as ownedTables.

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/all' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'
JSON
{
  "ownedTables": [
    {
      "tableId": "V1StGXR8Z5",
      "tableName": "customers",
      "tableSchema": { "tableName": "customers", "dbType": "DEFAULT" }
    }
  ],
  "companySharedTables": [
    {
      "tableId": "kTn4vB2p9Q",
      "tableName": "orders",
      "tableSchema": { "tableName": "orders", "dbType": "DEFAULT" }
    }
  ],
  "sharedWithMeTables": []
}

Share Table POST/share​

Updates a table's sharing configuration. Requires ADMIN access on the table. DEPENDENT tables (created by connectors) cannot be re-shared — update the linked connector instead.

Sharing levels:

  • PRIVATE — only the owner has access.
  • SPECIFIC_MEMBER — shared with the users in usersToAdd, each at their own access level.
  • COMPANY — everyone in the company gets accessLevel.

Request Body​

  • Name
    tableId
    Type
    string
    Description

    ID of the table to share.

  • Name
    level
    Type
    string
    Description

    Target sharing level: PRIVATE, SPECIFIC_MEMBER, or COMPANY.

  • Name
    accessLevel
    Type
    string
    Description

    Company-wide access level when level is COMPANY: READ, WRITE, PUBLISH, or ADMIN.

  • Name
    usersToAdd
    Type
    array<object>
    Description

    Users to grant access when level is SPECIFIC_MEMBER. Each entry has userId (string), userEmail (string), and accessLevel (string).

  • Name
    usersToRemove
    Type
    array<object>
    Description

    Users whose access should be revoked. Same shape as usersToAdd.

Response​

  • Name
    accessLevel
    Type
    string
    Description

    The access level applied by the request.

  • Name
    level
    Type
    string
    Description

    The sharing level applied by the request.

  • Name
    usersWithAccess
    Type
    array<object>
    Description

    When the table is shared at SPECIFIC_MEMBER level, the users who now have access, each with userId (string) and accessLevel (string). Empty for other levels.

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/share' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableId": "V1StGXR8Z5",
    "level": "SPECIFIC_MEMBER",
    "usersToAdd": [
      {
        "userId": "kTn4vB2p9Q",
        "userEmail": "teammate@example.com",
        "accessLevel": "WRITE"
      }
    ]
  }'
JSON
{
  "level": "SPECIFIC_MEMBER",
  "usersWithAccess": [
    {
      "userId": "kTn4vB2p9Q",
      "accessLevel": "WRITE"
    }
  ]
}

Get Sharing Details POST/get-sharing-details​

Returns a table's current sharing configuration plus the caller's own access level. Requires at least read access to the table.

Request Body​

  • Name
    tableId
    Type
    string
    Description

    ID of the table.

Response​

  • Name
    sharingLevel
    Type
    string
    Description

    The table's sharing level: PRIVATE, SPECIFIC_MEMBER, or COMPANY.

  • Name
    companyPermissionLevel
    Type
    string
    Description

    Access level granted company-wide, when shared at COMPANY level.

  • Name
    sharedWith
    Type
    array<object>
    Description

    Users the table is shared with, each with userId (string), userEmail (string), and accessLevel (string).

  • Name
    userAccessLevel
    Type
    string
    Description

    The caller's effective access level on the table.

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/get-sharing-details' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableId": "V1StGXR8Z5"
  }'
JSON
{
  "sharingLevel": "SPECIFIC_MEMBER",
  "sharedWith": [
    {
      "userEmail": "teammate@example.com",
      "userId": "kTn4vB2p9Q",
      "accessLevel": "WRITE"
    }
  ],
  "userAccessLevel": "ADMIN"
}

Transfer Ownership POST/transfer-ownership​

Transfers table ownership to another user. Only the current owner can transfer, and the new owner must be a member of the company and already have some access to the table (via sharing) before the transfer. DEPENDENT tables cannot be transferred — transfer the linked connector instead.

Request Body​

  • Name
    tableId
    Type
    string
    Description

    ID of the table.

  • Name
    newOwnerId
    Type
    string
    Description

    User ID of the new owner.

Response​

No fields on success. Failures (unknown user, user without prior access, caller not the owner) are reported in errors.

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/transfer-ownership' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableId": "V1StGXR8Z5",
    "newOwnerId": "kTn4vB2p9Q"
  }'
JSON
{}

Delete Table POST/delete​

Starts the two-step delete flow. Deleting a table is destructive — it drops the underlying SQL table, all stored files, and all vector indexes — so this endpoint does not delete anything. It validates that you have ADMIN access, then issues a single-use delete token that is valid for 5 minutes. Pass that token to /confirm-delete to actually delete the table.

The token is bound to the specific tableId it was issued for. If it expires before you confirm, call /delete again to get a fresh token.

DEPENDENT tables cannot be deleted — delete the linked connector instead.

Request Body​

  • Name
    tableId
    Type
    string
    Description

    ID of the table to delete.

Response​

  • Name
    deleteToken
    Type
    string
    Description

    Single-use confirmation token (a UUID). Required by /confirm-delete.

  • Name
    expiresIn
    Type
    integer
    Description

    Token lifetime in seconds (300).

curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/delete' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableId": "V1StGXR8Z5"
  }'
JSON
{
  "deleteToken": "1e8a9c2f-4b7d-4f3a-9c6e-2d5b8a7f1c3e",
  "expiresIn": 300
}

Confirm Delete Table POST/confirm-delete​

Completes the two-step delete flow. Requires ADMIN access and the deleteToken issued by /delete for the same tableId. If the token has expired (or was never issued) you get an error telling you to initiate the delete again; a token mismatch is also rejected.

On a valid confirmation the server:

  1. Deletes all S3 files stored for the table.
  2. Deletes all vector-index entries for the table.
  3. Drops the underlying SQL table.
  4. Soft-deletes the table reference, preserving metadata and trigger event history for audit purposes.

S3 and vector cleanup failures are logged but do not stop the deletion; a failure to drop the SQL table aborts and is returned in errors.

Request Body​

  • Name
    tableId
    Type
    string
    Description

    ID of the table to delete. Must match the table /delete was called for.

  • Name
    deleteToken
    Type
    string
    Description

    The token returned by /delete, still within its 5-minute lifetime.

Response​

No fields on success. Token and deletion failures are reported in errors.

curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/confirm-delete' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableId": "V1StGXR8Z5",
    "deleteToken": "1e8a9c2f-4b7d-4f3a-9c6e-2d5b8a7f1c3e"
  }'
JSON
{}

Update Table Schema POST/update-schema​

Modifies an existing table's schema. Requires ADMIN access. Supports adding columns, removing columns, adding new options to existing select columns, toggling column indexes, and replacing the table's tags — all in one request.

On an append-only table, column removal is rejected (rows are immutable, so the schema can only grow).

Request Body​

  • Name
    tableId
    Type
    string
    Description

    ID of the table to modify.

  • Name
    columnsToAdd
    Type
    array<object>
    Description

    New columns to add, as column definitions.

  • Name
    columnNamesToRemove
    Type
    array<string>
    Description

    Names of existing columns to drop.

  • Name
    selectOptionsToAdd
    Type
    object
    Description

    Map of existing SINGLE_SELECT/MULTI_SELECT column name to an array of new allowed values to add.

  • Name
    indexChanges
    Type
    object
    Description

    Map of existing column name to the desired indexed state (true adds the equality index, false drops it). Columns not listed are unchanged. Only SHORT_TEXT columns gain or lose a physical index; the flag is a no-op for the always-indexed types (see Column definition). Enabling an index on a SHORT_TEXT column length-caps its values to 2000 characters going forward.

  • Name
    tags
    Type
    array<string>
    Description

    Tags to set on the table.

Response​

  • Name
    updatedSchema
    Type
    object
    Description

    The table's schema after the update. See the Schema reference.

  • Name
    indexCreationInProgress
    Type
    array<string>
    Description

    Column names whose index is still building in the background. On a large table an index requested via indexChanges is built asynchronously — the schema update itself has already committed, and each listed column's index becomes usable once its build finishes. Empty when every requested index was created inline.

curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/update-schema' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableId": "V1StGXR8Z5",
    "columnsToAdd": [
      {
        "columnType": "BOOLEAN",
        "columnName": "is_active",
        "columnComment": "Whether the customer is active",
        "required": false
      }
    ],
    "columnNamesToRemove": ["legacy_notes"],
    "selectOptionsToAdd": {
      "tier": ["enterprise_plus"]
    },
    "tags": ["crm", "v2"]
  }'
JSON
{
  "updatedSchema": {
    "tableName": "customers",
    "dbType": "DEFAULT",
    "tags": ["crm", "v2"],
    "columnDefinitions": [
      {
        "columnType": "SHORT_TEXT",
        "columnName": "email",
        "required": true,
        "isForeignKey": false
      },
      {
        "columnType": "BOOLEAN",
        "columnName": "is_active",
        "columnComment": "Whether the customer is active",
        "isForeignKey": false
      }
    ]
  }
}

Analyze Trigger Impact POST/analyze-trigger-impact​

Analyzes what would happen if a database event fired on a table: which triggers match, which tables, tools, and agents the resulting cascade could touch, and whether the trigger graph contains cycles. Use this before schema or trigger changes to understand blast radius. Nothing is executed — this is a static analysis.

The result is a flow graph: flowNodes is a map of node ID to node, starting at rootNodeId. Each node's branches describe the possible next steps (always / conditional / fallback), and affectedResources summarizes everything reachable.

Request Body​

  • Name
    tableId
    Type
    string
    Description

    The source table for the hypothetical event.

  • Name
    eventType
    Type
    string
    Description

    The event to analyze: INSERT, UPDATE, DELETE, or ANY.

  • Name
    maxDepth
    Type
    integer
    Description

    Maximum cascade depth to analyze. Defaults to 10.

  • Name
    includeDisabledTriggers
    Type
    boolean
    Description

    Include triggers that are currently disabled. Defaults to false.

  • Name
    stopAtCycles
    Type
    boolean
    Description

    Stop traversal when a cycle is detected. Defaults to true.

  • Name
    includeSecondaryImpacts
    Type
    boolean
    Description

    Recurse through database operations performed by tools and agents that triggers invoke. Defaults to true.

Response​

  • Name
    sourceTableId
    Type
    string
    Description

    The analyzed source table.

  • Name
    sourceTableName
    Type
    string
    Description

    Name of the source table.

  • Name
    eventType
    Type
    string
    Description

    The analyzed event type.

  • Name
    flowNodes
    Type
    object
    Description

    Map of node ID to flow node. Each node has nodeId (string), depth (integer — distance from the source event), nodeType (string — TABLE_EVENT, TRIGGER_CHECK, ACTION_EXECUTE, TOOL_CALL, AGENT_CALL, or TERMINAL), encodedResourceId (string — the ID of the resource this node refers to, nullable), resourceKind (string — TABLE, TOOL, or AGENT, nullable), resourceName (string), description (string), branches (array<object> — see below), and metadata (object — additional context, nullable).

  • Name
    rootNodeId
    Type
    string
    Description

    ID of the starting node in flowNodes.

  • Name
    totalPossiblePaths
    Type
    integer
    Description

    Number of distinct execution paths through the graph.

  • Name
    maxDepth
    Type
    integer
    Description

    Deepest cascade level reached in the analysis.

  • Name
    affectedResources
    Type
    object
    Description

    Summary of everything reachable. Fields: tables, agents, and tools (each array<object> with encodedResourceId (string), resourceName (string), resourceType (string — TABLE, AGENT, or TOOL), possibleOperations (array<string>), and appearsInPaths (integer)), plus totalResources (integer).

  • Name
    detectedCycles
    Type
    array<object>
    Description

    Cycles found in the trigger graph. Each has cycleNodeIds (array<string>), cycleDescription (string), and severity (string — WARNING or ERROR).

  • Name
    warnings
    Type
    array<string>
    Description

    Non-fatal analysis warnings.

Each entry in a node's branches array has branchId (string), condition (string — human-readable, e.g. an IF expression, ELSE, or ALWAYS), conditionType (string — ALWAYS, CONDITIONAL, or FALLBACK), triggerId (string — UUID of the trigger creating the branch, nullable), triggerName (string, nullable), priority (integer, nullable), nextNodeId (string — the next flow node), and detailedCondition (object — full condition details for programmatic use, nullable).

cURL
curl --request POST \
  --url 'https://api.autessa.com/autessa_poweruser/autessadb/tables/analyze-trigger-impact' \
  -H "Authorization: $POWERUSER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tableId": "V1StGXR8Z5",
    "eventType": "INSERT",
    "maxDepth": 10,
    "includeDisabledTriggers": false,
    "stopAtCycles": true,
    "includeSecondaryImpacts": true
  }'
JSON
{
  "sourceTableId": "V1StGXR8Z5",
  "sourceTableName": "customers",
  "eventType": "INSERT",
  "rootNodeId": "node-0",
  "flowNodes": {
    "node-0": {
      "nodeId": "node-0",
      "depth": 0,
      "nodeType": "TABLE_EVENT",
      "encodedResourceId": "V1StGXR8Z5",
      "resourceKind": "TABLE",
      "resourceName": "customers",
      "description": "INSERT into customers",
      "branches": [
        {
          "branchId": "branch-0",
          "condition": "IF tier = 'enterprise'",
          "conditionType": "CONDITIONAL",
          "triggerId": "1e8a9c2f-4b7d-4f3a-9c6e-2d5b8a7f1c3e",
          "triggerName": "Notify sales agent",
          "priority": 1,
          "nextNodeId": "node-1"
        }
      ]
    },
    "node-1": {
      "nodeId": "node-1",
      "depth": 1,
      "nodeType": "AGENT_CALL",
      "encodedResourceId": "kTn4vB2p9Q",
      "resourceKind": "AGENT",
      "resourceName": "Sales Assistant",
      "description": "Invoke agent Sales Assistant",
      "branches": []
    }
  },
  "totalPossiblePaths": 1,
  "maxDepth": 1,
  "affectedResources": {
    "tables": [],
    "agents": [
      {
        "encodedResourceId": "kTn4vB2p9Q",
        "resourceName": "Sales Assistant",
        "resourceType": "AGENT",
        "possibleOperations": [],
        "appearsInPaths": 1
      }
    ],
    "tools": [],
    "totalResources": 1
  },
  "detectedCycles": [],
  "warnings": []
}

Errors​

Every response can carry an errors field of type array<string>. It is absent on success and populated on failure — server-side exceptions are caught and folded into errors rather than surfacing as raw 5xx bodies. Whenever errors is present the HTTP status is non-2xx. Responses may also include a deprecationWarnings array (array<string>) on successful calls that use deprecated behavior.

Common failure modes:

  • 401 Unauthorized — missing or invalid poweruser key, or the authenticated user lacks the required access level on the table (for example, non-ADMIN callers hitting /share, /delete, /confirm-delete, or /update-schema).
  • Validation errors — duplicate table name, invalid column names, text constraints exceeding the type's character limit, invalid foreign key references, upload-link count outside 1–50, or a missing eventType on /analyze-trigger-impact.
  • Delete-token errors — /confirm-delete with an expired, missing, or mismatched deleteToken.
  • Dependent-table errors — /share, /transfer-ownership, /delete, and /confirm-delete reject tables with dbType: DEPENDENT; manage the linked connector instead.
Error response
{
  "errors": ["A table with name customers already exists"]
}