Skip to main content

NL2SQL API

FastAPI REST service for the NL2SQL engine (nl2sql-engine). At startup it loads the .env next to nl2sql.yaml (never overriding a variable already set), builds one engine with NL2SQL.from_config() from the same config as the CLI (NL2SQL_CONFIG, else ./nl2sql.yaml), calls engine.check(), and serves it under /api/v1. A datasource marked required: true that cannot connect stops it from starting; any other one that fails is left out.

Running the API

pip install nl2sql-api
nl2sql-api serve --config nl2sql-demo/nl2sql.yaml --port 8000     # 127.0.0.1, one worker
# or: python -m nl2sql_api serve ..., or: NL2SQL_CONFIG=... uvicorn nl2sql_api.main:app
nl2sql-api serve --demo                  # the demo project; add --hosted for the public demo (anonymous sessions, limits)

Interactive docs: Swagger UI at /docs, ReDoc at /redoc, the schema at /openapi.json.

The API's own settings are the api section of nl2sql.yaml; the engine ignores it:

api:
  auth: static                   # api_keys | proxy | static | none (default none)
  static_role: admin             # auth: static only
  cors_origins: []               # browser origins allowed to call the API

api.auth picks who is asking; the request body never carries the caller. With no identity the routes answer HTTP 401. Under the default none only a request made straight to localhost is answered, and serve refuses to bind another host. Every error is one envelope, {"error": {"code", "message", "fix", "details", "request_id"}}, with the request id also in the X-Request-ID header.

The routes that change datasources, LLMs or the index need a role listed in policies.admin_roles (default [admin]), else HTTP 403.

The Docker image (the Dockerfile at the repository root, which also builds the web app) reads /etc/nl2sql/nl2sql.yaml: mount a config folder there, and a volume for storage.path.

Endpoints

  • POST /api/v1/query - Ask a question as the configured role
  • POST /api/v1/query/stream - The same, as Server-Sent Events: each step as it runs, the result manifest, the answer as it is written, then the /query response
  • GET /api/v1/health - Liveness check
  • GET /api/v1/ready - Readiness from the engine's check, kept 10 seconds: 200 ready or 503 not_ready; an admin also gets problems. The API starts even when a required datasource fails; this is where it says so
  • GET /api/v1/meta - The mode, the identity source and request_llm (no caller needed)
  • GET /api/v1/about - What the engine is
  • GET /api/v1/datasource-types - The adapters the engine can name, each with its connection schema (admin only)
  • POST /api/v1/datasources/test - Test a connection without registering it; returns the failed stage and the fix (admin only)
  • POST /api/v1/datasources - Register a datasource in the running process (config is one datasources entry); save: true also writes datasources/<id>.yaml (admin only)
  • GET /api/v1/datasources, GET /api/v1/datasources/{datasource_id} - The datasources the caller reaches, with status, masked connection and sample questions
  • DELETE /api/v1/datasources/{datasource_id} - Take a datasource out of the running process (admin only)
  • GET /api/v1/datasources/{datasource_id}/schema, GET /api/v1/datasources/{datasource_id}/diagram - The caller's view of the schema, as JSON or a Mermaid erDiagram
  • GET /api/v1/index - Index health (status, entries by type, embedding model, problems)
  • DELETE /api/v1/index - Clear the vector store (admin only)
  • GET /api/v1/index/check - Drift check against the live schemas (admin only)
  • GET /api/v1/index/inspect, POST /api/v1/index/inspect - The retrieval inspector
  • POST /api/v1/jobs/index, POST /api/v1/jobs/profile - Start the index or profile job (admin only, 202)
  • GET /api/v1/knowledge, GET /api/v1/knowledge/sources, POST /api/v1/knowledge/reload, POST /api/v1/knowledge/choices - What the engine knows; reload (admin) and file a clarification choice
  • GET /api/v1/proposals, GET /api/v1/proposals/{proposal_id}, POST /api/v1/proposals/accept|reject|examples - Review proposed knowledge changes (admin only)
  • PUT /api/v1/settings/llm - Replace the whole llm section in the running process (admin only; 422 with the config error)
  • PATCH /api/v1/settings/llm - Change only the provider and model of named agents (admin only; every other llm setting stays; in memory, this process only)
  • GET /api/v1/llm - Each agent and the model it runs on
  • GET /api/v1/llm/providers - The LLM providers: key present, verified models, the shape a key must have
  • GET /api/v1/api-keys, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{key_id} - List, create (the token is returned once) and revoke API keys (admin only)
  • GET /api/v1/evals/suites, GET /api/v1/evals/scorers - The configured eval suites and the scorer names (admin only)
  • POST /api/v1/jobs/eval - Run the configured eval suites as a job (admin only, 202; 422 when no suite is configured or named)
  • POST /api/v1/jobs/demo - Add the sample databases and index them, as a job (admin only, 202)
  • GET /api/v1/events/catalog - Every event the engine publishes, with its data's JSON Schema

Reference: https://github.com/nadeem4/nl2sql/blob/main/docs/api/rest/index.md.

Metadata

Release files for nl2sql-api 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nl2sql-api 0.10.0
File Size Uploaded Provenance Actions
nl2sql_api-0.10.0.tar.gz 6.3 MB Without provenance Details for nl2sql_api-0.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nl2sql-api 0.10.0
File Interpreter ABI Platform Actions
nl2sql_api-0.10.0-py3-none-any.whl Python 3 none any Details for nl2sql_api-0.10.0-py3-none-any.whl

Total release size: 12.6 MB

Release files / nl2sql_api-0.10.0.tar.gz

Download URL nl2sql_api-0.10.0.tar.gz
Size 6.3 MB
Tags Source
SHA-256 checksum
How to use checksums
08646b57df642e227e48fa70e5339baf6a8470b94ea1f72693ac6239a50bfc71
BLAKE2b-256 checksum
How to use checksums
d385af57f4fd389ab4b33344ddfae39cf331a6e2065e1ebb922f2419a26032a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / nl2sql_api-0.10.0-py3-none-any.whl

Download URL nl2sql_api-0.10.0-py3-none-any.whl
Size 6.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
f8af1a8f8dd823025bc8f1e8fdafc0f65367d40c834790cc5d5edcf33ae77a63
BLAKE2b-256 checksum
How to use checksums
39f0f8ea7fb0395529eb91a2e1d7f759c9beb880535b3289fede7bed46c74780
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Security for nl2sql-api 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page