Execute read-only SQL scoped to a bucket

POST

/api/v1/{bucket}/query

• Production
• Development

Execute a read-only SQL query against the tenant’s warehouse database. Authentication proves the caller has access to the specified bucket. The query runs in the tenant’s database — no bucket filtering needed.

Returns DuckDB error details on SQL failures so callers can self-correct their queries.

Authorizations

• BearerAuth
• ApiKeyAuth

Parameters

Path Parameters

bucket

required

string

/^[a-zA-Z0-9][a-zA-Z0-9\-]*$/

Flock bucket ID. The caller must have access to this bucket.

Example

example

Request Body ^required

object

sql

required

Read-only SQL statement.

string

Example

SELECT count(*) FROM person

Example

{
  "sql": "SELECT count(*) FROM person"
}

Responses

200

Query results

object

data

required

object

columns

required

Column names from the result set.

Array<string>

Example

[
  "uid",
  "first_name",
  "last_name"
]

rows

required

Result rows. Each row is an array of values matching the columns.

Array<Array>

Example

[
  [
    "abc123",
    "Jane",
    "Smith"
  ]
]

400

Invalid SQL or query execution error

object

error

required

object

code

required

Machine-readable error code.

string

Example

unauthorized

message

required

Human-readable error message.

string

Example

Authentication required

Examples

SQL validation failure

{
  "error": {
    "code": "bad_request",
    "message": "Only SELECT, PRAGMA, DESCRIBE, SHOW, and WITH statements are allowed (got DROP)"
  }
}

DuckDB execution error

{
  "error": {
    "code": "query_error",
    "message": "SQL error: Table 'foo' does not exist"
  }
}

401

Authentication required

object

error

required

object

code

required

Machine-readable error code.

string

Example

unauthorized

message

required

Human-readable error message.

string

Example

Authentication required

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}

403

Access denied to bucket

object

error

required

object

code

required

Machine-readable error code.

string

Example

unauthorized

message

required

Human-readable error message.

string

Example

Authentication required

Example

{
  "error": {
    "code": "forbidden",
    "message": "Access denied to bucket 'example'"
  }
}