For the complete documentation index, see llms.txt. This page is also available as Markdown.

Text-to-SQL API

Generate and run SQL from a natural language question

The Text-to-SQL API converts a natural language question into SQL, runs it against the app's datasets, and returns the result. A companion endpoint returns the context block — the dataset schemas, SQL dialect details, and function list that Spice supplies to the model — so the same information can be inspected or reused elsewhere.

Runtime Endpoint: These endpoints are served by your Spice runtime instance (e.g. https://<app-cname>.spiceai.io), not the Management API (https://api.spice.ai). Authenticate with your app API key, not a Personal Access Token.

A model capable of SQL generation must be configured in the app's spicepod. When the request omits model, Spice uses the single compatible model configured in the spicepod; if none or more than one is configured, the request fails and the model must be named explicitly.

Generate and run SQL

POST https://<app-cname>.spiceai.io/v1/nsql

Headers

Header
Type
Description

X-API-Key

string

Your app API key

Content-Type

string

application/json

Body

Field
Type
Default
Description

query

string

The natural language question. Required.

model

string

The model used for SQL generation. When omitted, the single compatible model configured in the spicepod is used.

stream

boolean

false

Stream the response instead of waiting for completion.

sample_data_enabled

boolean

false

Include sample data in the context supplied to the model.

datasets

string[]

Datasets to sample from when building the model context. A sampling hint only — it does not restrict which tables a query can target.

prompt_cache_key

string

A stable key forwarded to the model for provider-specific prompt caching.

curl -X POST https://<app-cname>.spiceai.io/v1/nsql \
  -H "X-API-Key: <app-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How many taxi trips were there last month?",
    "sample_data_enabled": true
  }'

Get the SQL generation context

GET https://<app-cname>.spiceai.io/v1/nsql/context

Returns the context block Spice injects into /v1/nsql model requests: the in-scope dataset schemas, the SQL dialect and engine details, and the available function groups. Use it to inspect or tune what the model sees.

Headers

Header
Type
Description

X-API-Key

string

Your app API key

Accept

string

text/markdown (used when the header is absent), text/plain, or application/json. Any other value returns a 406.

Query parameters

Parameter
Type
Default
Description

model

string

The model whose dataset allowlist is used. When omitted, the single compatible model is used.

include_sampling

boolean

false

Include distinct-value samples per column. Also accepts sample_data_enabled.

sampling_limit

integer

3

Maximum rows per distinct-value sample. Maximum 100.

include_examples

boolean

include_sampling

Include example rows. Defaults to whatever include_sampling is set to.

examples_limit

integer

3

Maximum example rows per dataset. Maximum 100.

datasets

string

all in scope

Repeat the parameter to name several datasets. When omitted, every dataset in scope is included.

Response

With Accept: application/json, the body contains:

Field
Description

context

The rendered context block injected into /v1/nsql model requests.

instructions

High-level SQL generation instructions.

sql

SQL engine and dialect details — engine, version, dialect, parser, notes.

datasets

In-scope datasets with schema, metadata, relationship, key, and index details.

functions

Available function groups, filtered to the app's query context.

samples

Sample blocks, present when sampling or examples are requested.

With text/markdown or text/plain, the body is the rendered context block itself.

Returned when a named dataset does not exist, when a limit is set to 0 while its corresponding option is enabled, when a limit exceeds 100, or when model is omitted and the spicepod has no compatible model — or more than one.

The Accept header requested a type other than text/markdown, text/plain, or application/json.

In the Portal

Both endpoints have an interactive console in the Playground under APIsNSQL and NSQL Context. The NSQL Context console builds the request from the options above and shows the returned block. See Playground.

Last updated

Was this helpful?