> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/data-world-model/workspace-tables.md). # 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. ## Application-Owned User Records An application can maintain a users table here and expose selected reads or writes through [Workspace Data Queries](/developer-guide/platform-api/functions/workspace-data-queries.md). This is an application data pattern; creating a row does not create a login principal, verify identity, or automatically create a world-model person. 1. Define the user table and a stable identifier under your application's ownership. 2. Register parameterized queries for the operations the agent needs, and expose only those tools in its Context Graph. 3. Declare the permitted start-time identifier in the service's `accepted_context`, then [bind the tool parameter from conversation context](/developer-guide/guides/conversation-context.md). 4. Test with synthetic users that the supplied identifier selects the intended record and that unauthorized record selection is rejected by your application or tool. Context binding controls parameter selection, not authorization. A separate `memoryid` can support [service-scoped memory](/developer-guide/platform-api/data-world-model/service-memory.md) when processing and readers are configured; no automatic mapping from a users-table row to memory is implied. ## 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://platform.api-us.concurrence.com/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://platform.api-us.concurrence.com/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://platform.api-us.concurrence.com/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://platform.api-us.concurrence.com/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://platform.api-us.concurrence.com/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. The statement runs as written. This operation does not take bind parameters, so a colon sequence inside a string literal, such as `:true` in `'{"a":true}'`, is passed through as literal text. Write values directly into the SQL text. ### Example ```bash curl -X POST "https://platform.api-us.concurrence.com/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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.concurrence.com/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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.