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. This is an application data pattern; creating a row does not create a login principal, verify identity, or automatically create a world-model person.

Define the user table and a stable identifier under your application's ownership.
Register parameterized queries for the operations the agent needs, and expose only those tools in its Context Graph.
Declare the permitted start-time identifier in the service's accepted_context, then bind the tool parameter from conversation context.
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 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.

Create Workspace Table

post

Authorizations

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

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

POST /v1/{workspace_id}/tables HTTP/1.1
Host: platform.api-us.concurrence.com
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"
}

Example

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).

List Workspace Tables

get

Authorizations

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

GET /v1/{workspace_id}/tables HTTP/1.1
Host: platform.api-us.concurrence.com
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-01-01T00:00:00.000Z"
    }
  ]
}

Example

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.

Get Workspace Table

get

Authorizations

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}

GET /v1/{workspace_id}/tables/{table_id} HTTP/1.1
Host: platform.api-us.concurrence.com
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-01-01T00:00:00.000Z",
  "columns": [
    {
      "name": "text",
      "data_type": "text",
      "is_nullable": true,
      "default": "text"
    }
  ],
  "indexes": [
    {
      "name": "text",
      "definition": "text"
    }
  ],
  "constraints": [
    {
      "name": "text",
      "definition": "text"
    }
  ]
}

Example

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.

Update Workspace Table

patch

Authorizations

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

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}

PATCH /v1/{workspace_id}/tables/{table_id} HTTP/1.1
Host: platform.api-us.concurrence.com
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"
}

Example

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.

Delete Workspace Table

delete

Authorizations

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}

DELETE /v1/{workspace_id}/tables/{table_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Example

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

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

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

POST /v1/{workspace_id}/query HTTP/1.1
Host: platform.api-us.concurrence.com
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.

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

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

{
  "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.

PreviousEntity Resolve

NextCustomer Data Intake

Last updated 6 days ago

Was this helpful?