Submit an async natural language query

POST

/api/v1/{bucket}/ask

• Production
• Development

Submits a natural language question to be answered by querying the tenant’s warehouse database. Creates a DynamoDB job, invokes the ask_worker Lambda asynchronously, and returns 202 with a job_id.

The worker generates SQL via MotherDuck’s prompt_sql(), validates it, executes it, and stores the result. Poll via GET /api/v1/{bucket}/ask/jobs/{jobId}.

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

question

required

Natural language question about the tenant’s data.

string

<= 1000 characters

Example

How many active members do we have?

Examples

Simple question

{
  "question": "How many active members do we have?"
}

Payment question

{
  "question": "Total payments by currency for 2024"
}

Responses

202

Job submitted successfully

object

data

required

object

job_id

required

string format: uuid

Example

a6220339-7ed3-42cf-b93a-67f78043567a

status

required

string

Allowed values: processing

Example

processing

400

Invalid request

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": "bad_request",
    "message": "Missing 'sql' field"
  }
}

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'"
  }
}