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

POST /v1/{workspace_id}/tables

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

Request Body

Field	Type	Required	Description
table_name	string	Yes	Table name. Must match ^[a-z][a-z0-9_]{0,62}$. Unique per workspace.
columns	Column[]	Yes	1-100 column definitions.
primary_key	string[]	No	Column names forming the primary key.
unique	string[][]	No	List of unique constraint column groups. Each group has 1-32 columns.
indexes	Index[]	No	List of indexes to create.

Column Object

Field	Type	Required	Description
name	string	Yes	Column name. Must match ^[a-z][a-z0-9_]{0,62}$.
type	string	Yes	Column type. See supported types below.
nullable	boolean	No	Whether the column allows nulls. Default: true.
default	Default	No	Default value specification.

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

Default Object

Field	Type	Required	Description
kind	string	Yes	One of: literal, uuid_v4, now, current_date.
value	string | number | boolean | null	No	Only used when kind is literal. Other kinds ignore this field.

Index Object

Field	Type	Required	Description
columns	string[]	Yes	1-32 column names to index.

Response (201)

Field	Type	Description
id	string (uuid)	Table registry ID.
workspace_id	string (uuid)	Owning workspace ID.
table_name	string	Workspace-facing table name.
physical_name	string	Platform-assigned storage name.

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

GET /v1/{workspace_id}/tables

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

Response (200)

Field	Type	Description
items	Item[]	List of table registry entries.

Item Object

Field	Type	Description
id	string (uuid)	Table registry ID.
workspace_id	string (uuid)	Owning workspace ID.
table_name	string	Workspace-facing table name.
physical_name	string	Platform-assigned storage name.
created_at	string (datetime)	When the table was created.

Example

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

Get Table Details

GET /v1/{workspace_id}/tables/{table_id}

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.

Response (200)

Field	Type	Description
id	string (uuid)	Table registry ID.
workspace_id	string (uuid)	Owning workspace ID.
table_name	string	Workspace-facing table name.
physical_name	string	Platform-assigned storage name.
created_at	string (datetime)	When the table was created.
columns	Column[]	Live column definitions from the storage catalog.
indexes	Index[]	Current indexes on the table.
constraints	Constraint[]	Current constraints on the table.

Response Column Object

Field	Type	Description
name	string	Column name.
data_type	string	Storage-reported type (e.g. uuid, text, timestamp with time zone).
is_nullable	boolean	Whether the column allows nulls.
default	string | null	Default expression text, or null if no default.

Response Index Object

Field	Type	Description
name	string	Index name.
definition	string	Full index definition statement.

Response Constraint Object

Field	Type	Description
name	string	Constraint name.
definition	string	Constraint definition.

Example

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

Alter a Table

PATCH /v1/{workspace_id}/tables/{table_id}

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

Request Body

Field	Type	Required	Description
actions	AlterAction[]	Yes	1-50 alter operations to apply.

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.

Response (200)

Field	Type	Description
id	string (uuid)	Table registry ID.
workspace_id	string (uuid)	Owning workspace ID.
table_name	string	Workspace-facing table name.
physical_name	string	Platform-assigned storage name.

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

DELETE /v1/{workspace_id}/tables/{table_id}

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

Response

204 No Content on success. 404 if the table is not found.

Example

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

Execute a Query

POST /v1/{workspace_id}/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.

Request Body

Field	Type	Required	Description
sql	string	Yes	A single SQL statement (1-16,384 characters).

Response (200)

Field	Type	Description
columns	string[]	Column names from the result set. Empty for non-SELECT statements.
rows	object[]	Result rows as key-value objects. Empty for non-SELECT statements.
row_count	integer	Number of rows returned (SELECT) or affected (INSERT/UPDATE/DELETE).

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 execution error against the database (valid statement, runtime failure).
404	Table not found (for get, alter, delete operations).
409	Table name already exists in the workspace (for create).
422	SQL validation failure: multi-statement batch, DDL/session-state command, or unparseable SQL.