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

workspace_id

string

required

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

Response

workspace_id

string

The identifier of the workspace.

name

string

The human-readable name of the workspace.

dialect

string

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

database_url_masked

string

The database connection URL with credentials redacted for safe display.

schema

string | null

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

include_tables

string[]

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

read_only

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

workspace_id

string

required

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

No request body is required.

Response

workspace_id

string

The identifier of the workspace that was tested.

connected

boolean

true if the connection succeeded, false if it failed.

dialect

string

The SQL dialect of the source database.

database_url_masked

string

The database connection URL with credentials redacted.

message

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

workspace_id

string

required

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

Response

workspace_id

string

The identifier of the workspace.

source

object

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

tables

object[]

List of tables in the workspace schema.

Show WorkspaceTableInfo fields

name

string

The table name.

schema

string | null

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

columns

object[]

List of columns in the table.

Show WorkspaceColumnInfo fields

name

string

The column name.

type

string

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

nullable

boolean

Whether the column accepts NULL values.

primary_key

boolean

Whether this column is part of the primary key.

primary_key

string[]

List of column names that form the primary key.

foreign_keys

object[]

List of foreign key constraints on the table.

Show WorkspaceForeignKeyInfo fields

constrained_columns

string[]

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

referred_table

string | null

The table being referenced.

referred_columns

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

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​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

Build docs developers (and LLMs) love

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