> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/data-world-model/workspace-tables.md). # Workspace 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. ## 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. {% openapi src="" path="/v1/{workspace\_id}/tables" method="post" %} {% endopenapi %} ### Example ```bash curl -X POST "https://api.platform.amigo.ai/v1/{workspace_id}/tables" \ -H "Authorization: Bearer " \ -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). {% openapi src="" path="/v1/{workspace\_id}/tables" method="get" %} {% endopenapi %} ### Example ```bash curl "https://api.platform.amigo.ai/v1/{workspace_id}/tables" \ -H "Authorization: Bearer " ``` ## Get Table Details Returns the table definition with its current schema, indexes, and constraints. {% openapi src="" path="/v1/{workspace\_id}/tables/{table\_id}" method="get" %} {% endopenapi %} ### Example ```bash curl "https://api.platform.amigo.ai/v1/{workspace_id}/tables/{table_id}" \ -H "Authorization: Bearer " ``` ## Alter a Table Applies one or more typed alter operations to an existing table. Operations are applied in order within a single transaction. {% openapi src="" path="/v1/{workspace\_id}/tables/{table\_id}" method="patch" %} {% endopenapi %} ### Example ```bash curl -X PATCH "https://api.platform.amigo.ai/v1/{workspace_id}/tables/{table_id}" \ -H "Authorization: Bearer " \ -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. {% openapi src="" path="/v1/{workspace\_id}/tables/{table\_id}" method="delete" %} {% endopenapi %} ### Example ```bash curl -X DELETE "https://api.platform.amigo.ai/v1/{workspace_id}/tables/{table_id}" \ -H "Authorization: Bearer " ``` ## 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. {% openapi src="" path="/v1/{workspace\_id}/query" method="post" %} {% endopenapi %} ### 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 ```bash curl -X POST "https://api.platform.amigo.ai/v1/{workspace_id}/query" \ -H "Authorization: Bearer " \ -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 ```json { "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. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/platform-api/data-world-model/workspace-tables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.