Skip to main content

Query API

Detailed guide for the Query API.

Natural Language to SQL​

Convert natural language questions to SQL queries.

Basic Query​

curl -X POST https://actyze.example.com/api/queries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Show revenue by month",
    "datasource_id": "abc-123"
  }'

With Context​

Provide schema context for better results:

curl -X POST https://actyze.example.com/api/queries \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "question": "Show revenue by month",
    "datasource_id": "abc-123",
    "context": {
      "schema": "analytics",
      "tables": ["orders", "customers"],
      "columns": {
        "orders": ["id", "amount", "created_at"],
        "customers": ["id", "name", "email"]
      }
    }
  }'

Execute Query​

Run a generated SQL query:

curl -X POST https://actyze.example.com/api/queries/QUERY_ID/execute \
  -H "Authorization: Bearer $TOKEN"

Query History​

Get query history:

curl https://actyze.example.com/api/queries?limit=10 \
  -H "Authorization: Bearer $TOKEN"

Save Query​

Save a query for reuse:

curl -X PUT https://actyze.example.com/api/queries/QUERY_ID \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Monthly Revenue",
    "description": "Revenue breakdown by month",
    "tags": ["finance", "monthly"]
  }'

Query Explanation​

Get explanation of SQL query:

curl -X POST https://actyze.example.com/api/queries/explain \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "sql": "SELECT * FROM users WHERE created_at > NOW() - INTERVAL 7 days"
  }'

Examples​

Sales Analytics​

{
  "question": "What are the top 10 products by revenue in 2024?",
  "datasource_id": "prod-db"
}

User Metrics​

{
  "question": "Show daily active users for the last 30 days",
  "datasource_id": "analytics-db"
}

Financial Reports​

{
  "question": "Calculate monthly recurring revenue trend",
  "datasource_id": "billing-db"
}