Workspace Tables

Create, manage, and query workspace-owned custom data tables.

Workspace Tables let you create and manage custom data tables scoped to your workspace. You define table schemas through typed requests, alter them with structured operations, and run scoped queries - all through the Platform API.

Endpoints

Method	Path	Description
POST	/v1/{workspace_id}/tables	Create a new workspace table
GET	/v1/{workspace_id}/tables	List all workspace tables
GET	/v1/{workspace_id}/tables/{table_id}	Get table details including live schema
PATCH	/v1/{workspace_id}/tables/{table_id}	Alter a table with typed operations
DELETE	/v1/{workspace_id}/tables/{table_id}	Drop a table and remove its registry entry
POST	/v1/{workspace_id}/query	Execute a scoped SQL query

Authentication

All endpoints require a valid API key with the appropriate workspace permissions. Create and alter operations require Workspace.update permission. List and get operations require Workspace.view permission. Query execution requires Workspace.update permission.

Create a Table

Creates a new workspace-owned table with the specified columns, constraints, and indexes.

Create Workspace Table

post

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

application/json

table_namestring · min: 1 · max: 63RequiredPattern: ^[a-z][a-z0-9_]{0,62}$

primary_keystring[] · nullableOptional

Responses

201

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

table_namestringRequired

physical_namestringRequired

422

Validation Error

application/json

post/v1/{workspace_id}/tables

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/tables HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 199

{
  "table_name": "text",
  "columns": [
    {
      "name": "text",
      "type": "text",
      "nullable": true,
      "default": {
        "kind": "literal",
        "value": "text"
      }
    }
  ],
  "primary_key": [
    "text"
  ],
  "unique": [
    [
      "text"
    ]
  ],
  "indexes": [
    {
      "columns": [
        "text"
      ]
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "table_name": "text",
  "physical_name": "text"
}

Supported Column Types

Type	Description
text	Variable-length text
int	32-bit integer
bigint	64-bit integer
numeric	Arbitrary precision number
boolean	True/false
uuid	Universally unique identifier
timestamptz	Timestamp with time zone
date	Calendar date
time	Time of day
jsonb	Structured object data
bytea	Binary data

Example

curl -X POST "https://api.platform.amigo.ai/v1/{workspace_id}/tables" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "patient_notes",
    "columns": [
      {"name": "id", "type": "uuid", "nullable": false, "default": {"kind": "uuid_v4"}},
      {"name": "patient_id", "type": "uuid", "nullable": false},
      {"name": "note", "type": "text", "nullable": false},
      {"name": "created_at", "type": "timestamptz", "nullable": false, "default": {"kind": "now"}}
    ],
    "primary_key": ["id"],
    "indexes": [{"columns": ["patient_id"]}]
  }'

List Tables

Returns all tables owned by the workspace, ordered by creation time (most recent first).

List Workspace Tables

get

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

get/v1/{workspace_id}/tables

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/tables HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "table_name": "text",
      "physical_name": "text",
      "created_at": "2026-07-10T22:36:56.058Z"
    }
  ]
}

Example

curl "https://api.platform.amigo.ai/v1/{workspace_id}/tables" \
  -H "Authorization: Bearer <api-key>"

Get Table Details

Returns the table registry entry along with the live schema, indexes, and constraints read from the storage catalog. The returned shape always reflects the current state of the table.

Get Workspace Table

get

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

table_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

table_namestringRequired

physical_namestringRequired

created_atstring · date-timeRequired

422

Validation Error

application/json

get/v1/{workspace_id}/tables/{table_id}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/tables/{table_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "table_name": "text",
  "physical_name": "text",
  "created_at": "2026-07-10T22:36:56.058Z",
  "columns": [
    {
      "name": "text",
      "data_type": "text",
      "is_nullable": true,
      "default": "text"
    }
  ],
  "indexes": [
    {
      "name": "text",
      "definition": "text"
    }
  ],
  "constraints": [
    {
      "name": "text",
      "definition": "text"
    }
  ]
}

Example

curl "https://api.platform.amigo.ai/v1/{workspace_id}/tables/{table_id}" \
  -H "Authorization: Bearer <api-key>"

Alter a Table

Applies one or more typed alter operations to an existing table. Operations are applied in order within a single transaction.

Update Workspace Table

patch

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

table_idstring · uuidRequired

Body

application/json

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

table_namestringRequired

physical_namestringRequired

422

Validation Error

application/json

patch/v1/{workspace_id}/tables/{table_id}

HTTPcURLJavaScriptPython

PATCH /v1/{workspace_id}/tables/{table_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "actions": [
    {
      "op": "text",
      "column": {
        "name": "text",
        "type": "text",
        "nullable": true,
        "default": {
          "kind": "literal",
          "value": "text"
        }
      }
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "table_name": "text",
  "physical_name": "text"
}

Alter Actions

Each action has an op field that determines its type:

add_column

Adds a new column to the table.

Field	Type	Description
op	"add_column"
column	Column	Column definition (same schema as create).

drop_column

Removes a column from the table.

Field	Type	Description
op	"drop_column"
name	string	Column name to drop.

rename_column

Renames an existing column.

Field	Type	Description
op	"rename_column"
from	string	Current column name.
to	string	New column name.

change_column_type

Changes the data type of an existing column.

Field	Type	Description
op	"change_column_type"
name	string	Column name.
new_type	string	New column type (same values as create).

set_column_nullable

Sets whether a column allows null values.

Field	Type	Description
op	"set_column_nullable"
name	string	Column name.
nullable	boolean	Whether the column allows nulls.

set_column_default

Sets or changes the default value for a column.

Field	Type	Description
op	"set_column_default"
name	string	Column name.
default	Default	New default specification.

drop_column_default

Removes the default value from a column.

Field	Type	Description
op	"drop_column_default"
name	string	Column name.

add_unique

Adds a unique constraint.

Field	Type	Description
op	"add_unique"
columns	string[]	1-32 column names.
constraint_name	string | null	Optional constraint name.

drop_constraint

Drops a named constraint.

Field	Type	Description
op	"drop_constraint"
name	string	Constraint name to drop.

add_index

Creates an index.

Field	Type	Description
op	"add_index"
index_name	string	Index name.
columns	string[]	1-32 column names.

drop_index

Drops a named index.

Field	Type	Description
op	"drop_index"
index_name	string	Index name to drop.

Example

curl -X PATCH "https://api.platform.amigo.ai/v1/{workspace_id}/tables/{table_id}" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {"op": "add_column", "column": {"name": "status", "type": "text", "nullable": false, "default": {"kind": "literal", "value": "active"}}},
      {"op": "add_index", "index_name": "idx_status", "columns": ["status"]}
    ]
  }'

Delete a Table

Drops the table and removes its registry entry. Both operations happen in a single transaction - if the drop fails, the registry entry is preserved.

Delete Workspace Table

delete

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

table_idstring · uuidRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

delete/v1/{workspace_id}/tables/{table_id}

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/tables/{table_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Example

curl -X DELETE "https://api.platform.amigo.ai/v1/{workspace_id}/tables/{table_id}" \
  -H "Authorization: Bearer <api-key>"

Execute a Query

Runs a single SQL statement scoped to the workspace's tables. Only data manipulation statements are allowed: SELECT, INSERT, UPDATE, DELETE, and WITH ... SELECT. The platform rejects multi-statement batches, DDL, and session-state commands.

Execute Workspace Query

post

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

application/json

sqlstring · min: 1 · max: 16384Required

One SQL statement: SELECT / WITH ... SELECT / INSERT / UPDATE / DELETE. Multi-statement, DDL, and session-state commands (SET ROLE, RESET, SET SESSION AUTHORIZATION) reject with 422 at the Pydantic boundary. pg_* function calls reject with 400 at execute time (no grant).

Responses

200

Successful Response

application/json

columnsstring[]Required

row_countintegerRequired

422

Validation Error

application/json

post/v1/{workspace_id}/query

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/query HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "sql": "text"
}

{
  "columns": [
    "text"
  ],
  "rows": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "row_count": 1
}

SQL Validation Rules

• Only one statement per request.
• Allowed statements: SELECT, WITH ... SELECT, INSERT, UPDATE, DELETE.
• Rejected: DDL (CREATE, ALTER, DROP), session commands (SET ROLE, RESET, SET SESSION AUTHORIZATION), multi-statement batches.
• Structural validation failures (multi-statement batches; session-state commands such as SET ROLE, RESET, SET SESSION AUTHORIZATION; unparseable SQL) are rejected with 422 at the request boundary. Errors raised by the database while running a valid statement are returned as 400 with the upstream message.

Example

curl -X POST "https://api.platform.amigo.ai/v1/{workspace_id}/query" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT id, note FROM patient_notes WHERE patient_id = '\''a1b2c3d4-...'\'' ORDER BY created_at DESC LIMIT 10"}'

Response Example

{
  "columns": ["id", "note"],
  "rows": [
    {"id": "f8e7d6c5-...", "note": "Follow-up scheduled for next week."},
    {"id": "a1b2c3d4-...", "note": "Initial intake completed."}
  ],
  "row_count": 2
}

Error Handling

Status	Description
400	Query or alter execution error against the database (valid statement, runtime failure).
404	Table not found (for get, alter, delete operations).
422	Request validation failure, including SQL validation: multi-statement batch, DDL/session-state command, or unparseable SQL.