> 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](https://docs.concurrence.com/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](https://docs.concurrence.com/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](https://docs.concurrence.com/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="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/tables" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Example

```bash
curl -X POST "https://platform.api-us.concurrence.com/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).

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/tables" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Example

```bash
curl "https://platform.api-us.concurrence.com/v1/{workspace_id}/tables" \
  -H "Authorization: Bearer <api-key>"
```

## Get Table Details

Returns the table definition with its current schema, indexes, and constraints.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/tables/{table\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Example

```bash
curl "https://platform.api-us.concurrence.com/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.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/tables/{table\_id}" method="patch" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Example

```bash
curl -X PATCH "https://platform.api-us.concurrence.com/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.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/tables/{table\_id}" method="delete" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Example

```bash
curl -X DELETE "https://platform.api-us.concurrence.com/v1/{workspace_id}/tables/{table_id}" \
  -H "Authorization: Bearer <api-key>"
```

## Execute a Query

Runs one SQL statement scoped to the workspace's tables, under the workspace's own role: a `SELECT` (with its `WITH`, `UNION` and the like), `INSERT`, `UPDATE`, `DELETE` or `TRUNCATE`. The statement may call only built-in functions that run no SQL text and change no session state, written unquoted and unqualified. Anything else is refused with `422` before it runs.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/query" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### SQL Validation Rules

A request runs only if its SQL passes these rules, and a saved [workspace data query](https://docs.concurrence.com/developer-guide/platform-api/functions/workspace-data-queries.md) is held to the same ones. The rules keep a request to reading and changing the workspace's data, and refuse the commands and calls that change database session state or run SQL text the platform cannot check.

* **One statement.** More than one statement in a request is refused, and so is SQL that does not parse.
* **Accepted statements.** `SELECT` (with its `WITH`, `UNION` and the like), `INSERT`, `UPDATE`, `DELETE` and `TRUNCATE`. A `WITH` clause can hold an `INSERT`, `UPDATE` or `DELETE`.
* **Refused statements.** Every other statement, including `CREATE`, `ALTER`, `DROP`, `GRANT`, `COPY`, `MERGE`, `EXPLAIN`, `CALL` and `DO`. `SELECT ... INTO` is refused too, because it creates a table. Use the table operations above to change a schema.
* **Refused session and transaction commands.** `SET` in any form, including `SET ROLE` and `SET SESSION AUTHORIZATION`, and `RESET`, `SHOW`, `BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `LISTEN`, `PREPARE`, `DISCARD` and `DECLARE`.
* **Function calls.** A call must be to a built-in function on the [accepted list](#accepted-functions), written unquoted and without a schema: `lower(note)` is accepted, and `"lower"(note)` and `public.lower(note)` are refused. Every other function is refused, including `set_config`, `current_setting`, `random`, `nextval`, `pg_sleep`, the advisory-lock functions, and functions that run the SQL text they are given, such as `query_to_xml` and `ts_stat`.
* **Other refusals.** Any `U&` in the SQL text, even inside a string or a comment, and any reference to the `pg_settings` view, even to read it.

A refused request returns `422` and nothing runs. Errors raised by the database while running an accepted statement are returned as `400` with the database message. Each request runs in its own transaction, so a statement that fails changes nothing.

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.

### Accepted Functions <a href="#accepted-functions" id="accepted-functions"></a>

A statement may call the built-in functions below. SQL syntax, such as `CAST(...)`, `EXISTS (...)` and `IN (...)`, and a type with modifiers, such as `numeric(10, 2)`, are not function calls and are accepted.

<details>

<summary>Show the accepted functions</summary>

* **Aggregates and windows:** `array_agg`, `avg`, `bit_and`, `bit_or`, `bool_and`, `bool_or`, `corr`, `count`, `covar_pop`, `covar_samp`, `cume_dist`, `dense_rank`, `every`, `first_value`, `json_agg`, `json_object_agg`, `jsonb_agg`, `jsonb_object_agg`, `lag`, `last_value`, `lead`, `max`, `min`, `mode`, `nth_value`, `ntile`, `percent_rank`, `percentile_cont`, `percentile_disc`, `rank`, `row_number`, `stddev`, `stddev_pop`, `stddev_samp`, `string_agg`, `sum`, `var_pop`, `var_samp`, `variance`
* **Conditionals:** `coalesce`, `greatest`, `least`, `nullif`, `num_nonnulls`, `num_nulls`
* **Text:** `ascii`, `btrim`, `char_length`, `character_length`, `chr`, `concat`, `concat_ws`, `decode`, `encode`, `format`, `initcap`, `left`, `length`, `lower`, `lpad`, `ltrim`, `md5`, `octet_length`, `overlay`, `position`, `quote_ident`, `quote_literal`, `quote_nullable`, `regexp_count`, `regexp_like`, `regexp_match`, `regexp_matches`, `regexp_replace`, `regexp_split_to_array`, `regexp_split_to_table`, `regexp_substr`, `repeat`, `replace`, `reverse`, `right`, `rpad`, `rtrim`, `split_part`, `starts_with`, `string_to_array`, `strpos`, `substr`, `substring`, `to_hex`, `translate`, `trim`, `upper`
* **Full-text search and text similarity:** `phraseto_tsquery`, `plainto_tsquery`, `similarity`, `strict_word_similarity`, `to_tsquery`, `to_tsvector`, `ts_headline`, `ts_rank`, `ts_rank_cd`, `websearch_to_tsquery`, `word_similarity`
* **Numbers:** `abs`, `cbrt`, `ceil`, `ceiling`, `div`, `exp`, `floor`, `ln`, `log`, `log10`, `mod`, `pi`, `power`, `round`, `sign`, `sqrt`, `trunc`, `width_bucket`
* **Dates and times:** `age`, `clock_timestamp`, `current_time`, `current_timestamp`, `date_bin`, `date_part`, `date_trunc`, `extract`, `isfinite`, `justify_days`, `justify_hours`, `justify_interval`, `localtime`, `localtimestamp`, `make_date`, `make_interval`, `make_time`, `make_timestamp`, `make_timestamptz`, `now`, `statement_timestamp`, `timezone`, `to_char`, `to_date`, `to_number`, `to_timestamp`, `transaction_timestamp`
* **JSON:** `json_array_elements`, `json_array_elements_text`, `json_array_length`, `json_build_array`, `json_build_object`, `json_each`, `json_each_text`, `json_extract_path`, `json_extract_path_text`, `json_object_keys`, `json_strip_nulls`, `json_to_record`, `json_to_recordset`, `json_typeof`, `jsonb_array_elements`, `jsonb_array_elements_text`, `jsonb_array_length`, `jsonb_build_array`, `jsonb_build_object`, `jsonb_each`, `jsonb_each_text`, `jsonb_exists`, `jsonb_exists_all`, `jsonb_exists_any`, `jsonb_extract_path`, `jsonb_extract_path_text`, `jsonb_insert`, `jsonb_object_keys`, `jsonb_path_exists`, `jsonb_path_match`, `jsonb_path_query`, `jsonb_path_query_array`, `jsonb_path_query_first`, `jsonb_pretty`, `jsonb_set`, `jsonb_strip_nulls`, `jsonb_to_record`, `jsonb_to_recordset`, `jsonb_typeof`, `row_to_json`, `to_json`, `to_jsonb`
* **Arrays and series:** `array_append`, `array_cat`, `array_dims`, `array_length`, `array_lower`, `array_position`, `array_positions`, `array_prepend`, `array_remove`, `array_replace`, `array_to_string`, `array_upper`, `cardinality`, `generate_series`, `generate_subscripts`, `unnest`
* **UUIDs and input checks:** `gen_random_uuid`, `pg_input_is_valid`

</details>

### Example

```bash
curl -X POST "https://platform.api-us.concurrence.com/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

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

### Refused Request Example <a href="#refused-request-example" id="refused-request-example"></a>

This request calls a function that is not accepted:

```bash
curl -X POST "https://platform.api-us.concurrence.com/v1/{workspace_id}/query" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT set_config('\''statement_timeout'\'', '\''0'\'', false)"}'
```

The response is `422`. The message names the statement or the call that was refused and does not repeat the rest of the SQL:

```json
{
  "detail": [
    {
      "loc": ["body", "sql"],
      "msg": "Value error, the call to set_config() is not allowed: workspace SQL may call only the built-in functions that run no SQL text and change no session state",
      "type": "value_error"
    }
  ]
}
```

A refused statement gets its own message in the same field, for example `session-state and transaction commands (SET and the like) are not allowed` or `DROP statements are not allowed, only SELECT, INSERT, UPDATE, DELETE and TRUNCATE`. SQL that does not parse gets a message that contains `invalid SQL`.

## 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 that breaks the rules above.                  |


---

# 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=<question>&goal=<user_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.
