explorer
Operations of the Org Database Pool API. Paths are relative to your deployment's API host.
GET /api/org-database-pool-api/databases/{databaseId}/explorer/columns
List columns of a table or view
Capability required: org_database:explore. Includes primary-key flag and foreign-key target (string form <schema>.<table>.<column>).
Authentication: none
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
databaseId | path | string | yes | |
schema | query | string | no | |
table | query | string | yes | Table name to introspect. |
| Status | Description | Body |
|---|---|---|
| 200 | application/json ExplorerColumnsResponseDtoDataEnvelope |
POST /api/org-database-pool-api/databases/{databaseId}/explorer/mutate
Run an ad-hoc INSERT/UPDATE/DELETE statement
Capability required: org_database:mutate. AST-validated: INSERT/UPDATE/DELETE only, single statement (RETURNING allowed). Executed under the per-schema *_rw role inside a transaction.
Authentication: none
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
databaseId | path | string | yes | |
X-Db-Surface-Id | header | string | no | When present, the response includes a surface: DbResultSurfaceEvent carrying mutationKind and affectedRows. |
Request body: application/json ExplorerMutateDto
| Status | Description | Body |
|---|---|---|
| 201 | application/json object |
POST /api/org-database-pool-api/databases/{databaseId}/explorer/query
Run an ad-hoc SELECT statement
Capability required: org_database:query. AST-validated: SELECT only, single statement, no mutating CTEs. Executed under the per-schema *_ro role inside a transaction with SET LOCAL statement_timeout.
Authentication: none
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
databaseId | path | string | yes | |
X-Db-Surface-Id | header | string | no | When present, the response includes a surface: DbResultSurfaceEvent. |
Request body: application/json ExplorerQueryDto
| Status | Description | Body |
|---|---|---|
| 200 | application/json ExplorerQueryResponseDtoDataEnvelope |
GET /api/org-database-pool-api/databases/{databaseId}/explorer/rows
Paginated row preview of a table or view
Capability required: org_database:query. Hard row cap is ExplorerService.RESULT_ROW_CAP (500); requests above the cap are truncated and truncated: true flagged on the response.
Authentication: none
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
databaseId | path | string | yes | |
limit | query | number | no | Row limit (default 100, hard max 500 — see ExplorerService.RESULT_ROW_CAP). |
offset | query | number | no | Row offset for keyset-less pagination (default 0). |
schema | query | string | no | |
table | query | string | yes | Table name to read rows from. |
X-Db-Surface-Id | header | string | no | When present, the response includes a surface field carrying the matching DbResultSurfaceEvent for the UI to bind. SSE delivery is deferred to Phase H5. |
| Status | Description | Body |
|---|---|---|
| 200 | application/json ExplorerRowsResponseDtoDataEnvelope |
GET /api/org-database-pool-api/databases/{databaseId}/explorer/schemas
List schemas exposed by an org database
Capability required: org_database:explore. Returns the singleton schema bound to the OrgDatabase row (H1 ships one-schema-per-database).
Authentication: none
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
databaseId | path | string | yes |
| Status | Description | Body |
|---|---|---|
| 200 | application/json ExplorerSchemasResponseDtoDataEnvelope |
GET /api/org-database-pool-api/databases/{databaseId}/explorer/tables
List tables and views in a schema
Capability required: org_database:explore.
Authentication: none
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
databaseId | path | string | yes | |
schema | query | string | no | Override schema. Defaults to OrgDatabase.schemaName when omitted. |
| Status | Description | Body |
|---|---|---|
| 200 | application/json ExplorerTablesResponseDtoDataEnvelope |