Workspace API — inspect schema and test connections

The workspace endpoints let you inspect how a workspace is configured, verify that its database connection is healthy, and browse the full schema available to the AI query engine. The default workspace ID is "default".

GET /api/v1/workspaces//source

Returns the data source configuration for a workspace, including the database dialect and the list of approved tables.

Path parameters

string

required

The workspace identifier. Use "default" for the default workspace.

Response

string

The identifier of the workspace.

string

The human-readable name of the workspace.

string

The SQL dialect of the source database (e.g., "postgresql").

string

The database connection URL with credentials redacted for safe display.

string | null

The database schema to use, if configured. null means the database default.

string[]

The list of table names approved for querying by the AI.

boolean

Whether the workspace operates in read-only mode. Always true for source workspaces.

Example

curl http://localhost:8000/api/v1/workspaces/default/source

{
  "workspace_id": "default",
  "name": "Default Workspace",
  "dialect": "postgresql",
  "database_url_masked": "postgresql+psycopg://boardpulse:***@postgres:5432/boardpulse",
  "schema": null,
  "include_tables": ["sales_orders", "invoices", "inventory_items"],
  "read_only": true
}

POST /api/v1/workspaces//test-connection

Tests the database connection for a workspace and returns whether the connection succeeded.

Path parameters

string

required

The workspace identifier. Use "default" for the default workspace.

No request body is required.

Response

string

The identifier of the workspace that was tested.

boolean

true if the connection succeeded, false if it failed.

string

The SQL dialect of the source database.

string

The database connection URL with credentials redacted.

string

A human-readable message describing the connection result.

Example

curl -X POST http://localhost:8000/api/v1/workspaces/default/test-connection

{
  "workspace_id": "default",
  "connected": true,
  "dialect": "postgresql",
  "database_url_masked": "postgresql+psycopg://boardpulse:***@postgres:5432/boardpulse",
  "message": "Connection successful"
}

GET /api/v1/workspaces//schema

Returns the full table and column schema for a workspace, including column types, nullability, primary keys, and foreign key relationships.

Path parameters

string

required

The workspace identifier. Use "default" for the default workspace.

Response

string

The identifier of the workspace.

object

The workspace source configuration. Same structure as the /source endpoint response.

object[]

List of tables in the workspace schema.

Show WorkspaceTableInfo fields

string

The table name.

string | null

The database schema the table belongs to. null means the database default.

object[]

List of columns in the table.

Show WorkspaceColumnInfo fields

string

The column name.

string

The SQL data type (e.g., "VARCHAR", "INTEGER", "TIMESTAMP").

boolean

Whether the column accepts NULL values.

boolean

Whether this column is part of the primary key.

string[]

List of column names that form the primary key.

object[]

List of foreign key constraints on the table.

Show WorkspaceForeignKeyInfo fields

string[]

Columns in this table that are part of the foreign key.

string | null

The table being referenced.

string[]

Columns in the referenced table.

Example

curl http://localhost:8000/api/v1/workspaces/default/schema

{
  "workspace_id": "default",
  "source": {
    "workspace_id": "default",
    "name": "Default Workspace",
    "dialect": "postgresql",
    "database_url_masked": "postgresql+psycopg://boardpulse:***@postgres:5432/boardpulse",
    "schema": null,
    "include_tables": ["sales_orders", "invoices", "inventory_items"],
    "read_only": true
  },
  "tables": [
    {
      "name": "sales_orders",
      "schema": null,
      "columns": [
        {"name": "id", "type": "INTEGER", "nullable": false, "primary_key": true},
        {"name": "region", "type": "VARCHAR", "nullable": true, "primary_key": false},
        {"name": "amount", "type": "NUMERIC", "nullable": true, "primary_key": false},
        {"name": "order_date", "type": "TIMESTAMP", "nullable": true, "primary_key": false}
      ],
      "primary_key": ["id"],
      "foreign_keys": []
    }
  ]
}

Overview

Endpoints

Workspace API — inspect schema and test connections

GET /api/v1/workspaces//source

Path parameters

Response

Example

POST /api/v1/workspaces//test-connection

Path parameters

Response

Example

GET /api/v1/workspaces//schema

Path parameters

Response

Example

​GET /api/v1/workspaces//source

​Path parameters

​Response

​Example

​POST /api/v1/workspaces//test-connection

​Path parameters

​Response

​Example

​GET /api/v1/workspaces//schema

​Path parameters

​Response

​Example

GET /api/v1/workspaces//source

Path parameters

Response

Example

POST /api/v1/workspaces//test-connection

Path parameters

Response

Example

GET /api/v1/workspaces//schema

Path parameters

Response

Example