Skip to content

Latest commit

 

History

History
363 lines (246 loc) · 5.02 KB

API.md

File metadata and controls

363 lines (246 loc) · 5.02 KB

API Reference

Complete API documentation for Text2SQL Agent.

Base URL

http://localhost:8000/api/v1

Authentication

All /api/v1 endpoints (except /api/v1/health) require authentication.

  • API key: X-API-Key: <key>
  • JWT: Authorization: Bearer <token>

Mutation/management endpoints require scopes in MUTATION_SCOPES (default: write,admin).

Interactive Documentation

When the server is running, visit:

Core Endpoints

Generate SQL

Convert natural language to SQL with optional execution.

POST /api/v1/query

Request Body:

{
    "query": "Show me all customers from California",
    "database_id": "my_database",
    "execute": true,
    "show_reasoning": true,
    "max_rows": 100
}

Response:

{
    "sql": "SELECT * FROM customers WHERE state = 'California'",
    "confidence": 0.95,
    "execution_time_ms": 1823,
    "dialect": "postgresql",
    "valid_syntax": true,
    "validation_status": "validated",
    "results": [...],
    "reasoning_trace": [
        {
            "step": 1,
            "thought": "Need to filter customers by state",
            "action": "sql_engine",
            "observation": "Query executed successfully"
        }
    ]
}

Batch Query

Process multiple queries in one request.

POST /api/v1/query/batch

Stream Query

Stream SQL generation results in real-time.

POST /api/v1/query/stream

Notes:

  • SQL is generated once; when execute=true, the generated SQL is executed directly and results are streamed in batches.
  • If SQL generation returns an empty string and execute=true, a query_error event is emitted and the stream ends.
  • Results are capped by max_rows and streamed in fixed-size batches (default 100 rows).

Example SSE event:

event: sql_generated
data: {"event":"sql_generated","data":{"sql":"SELECT 1","confidence":0.92},"timestamp":1734370000.0}

Validate SQL

Validate SQL syntax and semantics without execution.

POST /api/v1/validate

Authentication Endpoints

Issue Token

Issue a JWT access token using credentials configured in AUTH_USERS.

POST /api/v1/auth/token

Request Body:

{
    "username": "admin",
    "password": "change_me"
}

Schema Endpoints

Get Schema

GET /api/v1/schema/{database_id}

Register Schema

POST /api/v1/schema/register

Agent Endpoints

Get Reasoning Trace

Retrieve detailed reasoning for a specific query.

GET /api/v1/agent/reasoning/{query_id}

Retry Query

Retry a failed query with correction hints.

POST /api/v1/agent/retry

Database Management

Register Database

POST /api/v1/databases

Request Body:

{
    "database_id": "analytics",
    "connection_string": "postgresql://user:pass@host/db",
    "display_name": "Analytics Database",
    "pool_size": 10
}

List Databases

GET /api/v1/databases

Get Database Details

GET /api/v1/databases/{database_id}

Check Database Health

GET /api/v1/databases/{database_id}/health

Delete Database

DELETE /api/v1/databases/{database_id}

Health Check All

GET /api/v1/databases/health/all

Explanation and Visualization

Explain SQL

Generate natural language explanation of a SQL query.

POST /api/v1/explain

Visualize Query

Generate query structure visualization.

POST /api/v1/visualize

Get Cached Explanation

GET /api/v1/explain/{query_id}

Batch Explain

POST /api/v1/explain/batch

Few-Shot Learning

Add Example

POST /api/v1/examples

Search Examples

POST /api/v1/examples/search

List Examples

GET /api/v1/examples

Get/Update/Delete Example

GET /api/v1/examples/{example_id}
PATCH /api/v1/examples/{example_id}
DELETE /api/v1/examples/{example_id}

Feedback

Submit Feedback

POST /api/v1/feedback

List Feedback

GET /api/v1/feedback

Get Feedback

GET /api/v1/feedback/{feedback_id}

Update Feedback Status

PATCH /api/v1/feedback/{feedback_id}/status

Model Versioning

List Versions

GET /api/v1/models/versions

Get Active Version

GET /api/v1/models/versions/active

Register Version

POST /api/v1/models/versions

Activate Version

POST /api/v1/models/versions/{version_id}/activate

Management

Health Check

GET /api/v1/health

Model Info

GET /api/v1/models/info

Prometheus Metrics

GET /monitoring/metrics

Cache Stats

GET /api/v1/cache/stats

Invalidate Cache

POST /api/v1/cache/invalidate

Supports namespace invalidation for query, model, prompt, schema, inference, and validation.