### List Examples with Agent Token

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/AgentExamplesApi.md

Demonstrates how to list examples using the AgentExamplesApi with an agent token for authentication. Includes setup for API client, authentication, and making the API call with optional parameters.

```java
// Import classes:
import com.firefly.flyquery.ApiClient;
import com.firefly.flyquery.ApiException;
import com.firefly.flyquery.Configuration;
import com.firefly.flyquery.auth.*;
import com.firefly.flyquery.models.*;
import com.firefly.flyquery.api.AgentExamplesApi;

import java.util.UUID;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("http://localhost");
        
        // Configure API key authorization: AgentToken
        ApiKeyAuth AgentToken = (ApiKeyAuth) defaultClient.getAuthentication("AgentToken");
        AgentToken.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //AgentToken.setApiKeyPrefix("Token");

        AgentExamplesApi apiInstance = new AgentExamplesApi(defaultClient);
        String xAgentToken = "fqt_live_aBcDeF1234567890aBcDeF1234567890"; // String | Machine-to-machine bearer token. Replaces X-Tenant-Id and X-Workspace-Id on agent-tier endpoints -- the token's claims encode the tenant + workspace + scopes. Issue via ``POST /api/v1/agent-tokens``.
        String quality = "quality_example"; // String | 
        String datasetId = "datasetId_example"; // String | 
        Integer limit = 100; // Integer | 
        Integer offset = 0; // Integer | 
        UUID xCorrelationId = UUID.fromString("550e8400-e29b-41d4-a716-446655440000"); // UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header.
        try {
            PaginatedExampleRead result = apiInstance.listExamples(xAgentToken, quality, datasetId, limit, offset, xCorrelationId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AgentExamplesApi#listExamples");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Add Curated Example for SQL Generation

Source: https://github.com/firefly-operationos/flyquery/blob/main/docs/troubleshooting.md

Provide a curated example to guide the GenerationAgent when generating SQL for similar questions. This acts as a few-shot anchor.

```bash
# Add a curated example
POST /api/v1/examples
  {"question": "Total revenue by month",
   "generated_sql": "SELECT strftime('%Y-%m', order_date) AS month, SUM(amount) FROM ...",
   "dataset_id": "ds_01"}
```

--------------------------------

### Python Query API Explain Example

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/python/docs/QueryApi.md

Demonstrates how to use the explain method from the flyquery_sdk to get a preview of generated SQL. It shows setup for API key authentication for both WorkspaceContext and TenantContext.

```python
import flyquery_sdk
from flyquery_sdk.models.explain_response import ExplainResponse
from flyquery_sdk.models.query_request import QueryRequest
from flyquery_sdk.rest import ApiException
from pprint import pprint
import os
from uuid import UUID

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = flyquery_sdk.Configuration(
    host = "http://localhost"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: WorkspaceContext
configuration.api_key['WorkspaceContext'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['WorkspaceContext'] = 'Bearer'

# Configure API key authorization: TenantContext
configuration.api_key['TenantContext'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['TenantContext'] = 'Bearer'

# Enter a context with an instance of the API client
async with flyquery_sdk.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = flyquery_sdk.QueryApi(api_client)
    x_tenant_id = 'acme-corp' # str | Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.
    x_workspace_id = '00000000-0000-0000-0000-000000000001' # str | Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.
    query_request = flyquery_sdk.QueryRequest() # QueryRequest | 
    x_correlation_id = UUID('550e8400-e29b-41d4-a716-446655440000') # UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header. (optional)
    idempotency_key = 'ingest-2026-05-23-abc123' # str | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h. (optional)

    try:
        # Run Grounding + Generation but stop before AST/execution.
        api_response = await api_instance.explain(x_tenant_id, x_workspace_id, query_request, x_correlation_id=x_correlation_id, idempotency_key=idempotency_key)
        print("The response of QueryApi->explain:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling QueryApi->explain: %s\n" % e)

```

--------------------------------

### Fetch a single example by ID

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/python/docs/ExamplesApi.md

Demonstrates how to fetch a single example using its ID with the Python SDK. Includes setup for API key authentication for both WorkspaceContext and TenantContext, and error handling.

```python
import flyquery_sdk
from flyquery_sdk.models.example_read import ExampleRead
from flyquery_sdk.rest import ApiException
from pprint import pprint
import os
from uuid import UUID

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = flyquery_sdk.Configuration(
    host = "http://localhost"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: WorkspaceContext
configuration.api_key['WorkspaceContext'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['WorkspaceContext'] = 'Bearer'

# Configure API key authorization: TenantContext
configuration.api_key['TenantContext'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['TenantContext'] = 'Bearer'

# Enter a context with an instance of the API client
async with flyquery_sdk.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = flyquery_sdk.ExamplesApi(api_client)
    example_id = 'example_id_example' # str | 
    x_tenant_id = 'acme-corp' # str | Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.
    x_workspace_id = '00000000-0000-0000-0000-000000000001' # str | Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.
    x_correlation_id = UUID('550e8400-e29b-41d4-a716-446655440000') # UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header. (optional)

    try:
        # Fetch a single example by id. Returns 404 if not found.
        api_response = await api_instance.get_example(example_id, x_tenant_id, x_workspace_id, x_correlation_id=x_correlation_id)
        print("The response of ExamplesApi->get_example:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling ExamplesApi->get_example: %s\n" % e)

```

--------------------------------

### Flyquery Cold Start Checklist and Deployment

Source: https://github.com/firefly-operationos/flyquery/blob/main/docs/operations-runbook.md

This snippet outlines the essential steps for deploying flyquery for the first time, including database setup, role creation, migrations, and service startup. It also includes verification steps for pgvector and role permissions.

```bash
# 1. Create Postgres database
psql -c "CREATE DATABASE flyquery;"

# 2. Create roles (copy-paste safe; idempotent on re-run)
psql flyquery << 'SQL'
DO $$
BEGIN
  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'flyquery_admin') THEN
    CREATE ROLE flyquery_admin LOGIN PASSWORD 'CHANGE_ME';
  END IF;
  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'flyquery_app') THEN
    CREATE ROLE flyquery_app LOGIN PASSWORD 'CHANGE_ME';
  END IF;
END $$;
GRANT ALL PRIVILEGES ON DATABASE flyquery TO flyquery_admin;
SQL

# 3. Run migrations (uses flyquery_admin role via FLYQUERY_DATABASE_URL_ADMIN)
export FLYQUERY_DATABASE_URL_ADMIN="postgresql+asyncpg://flyquery_admin:CHANGE_ME@localhost:5432/flyquery"
export FLYQUERY_DATABASE_URL="postgresql+asyncpg://flyquery_app:CHANGE_ME@localhost:5432/flyquery"
uv run alembic upgrade head

# 4. Verify pgvector is enabled
psql flyquery -c "SELECT extname FROM pg_extension WHERE extname='vector';"
# If missing: CREATE EXTENSION vector;

# 5. Verify role split
psql "postgresql://flyquery_app:CHANGE_ME@localhost:5432/flyquery" \
  -c "SELECT current_user, pg_has_role('flyquery_app', 'BYPASSRLS', 'MEMBER');"
# pg_has_role should return 'f' (false) — app role must NOT bypass RLS

# 6. Start the service
task serve   # dev
# or: docker compose up flyquery-api flyquery-worker

# 7. Health check
curl -s http://localhost:8520/actuator/health | jq .status
# → "UP"

# 8. Version check
curl -s http://localhost:8520/api/v1/version
# → {"version": "26.5.3", ...}
```

--------------------------------

### FlyqueryClient Quick Start

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/python/README.md

Initialize the FlyqueryClient and perform common operations like workspace/dataset setup, file uploads, and asking questions.

```python
import asyncio
from flyquery_sdk import FlyqueryClient


async def main() -> None:
    async with FlyqueryClient(
        base_url="https://flyquery.example.com",
        tenant_id="acme-corp",
        workspace_id="finance",
    ) as fly:

        # 1) Idempotent workspace + dataset setup
        ws = await fly.find_or_create_workspace("finance", name="Finance")
        ds = await fly.find_or_create_dataset(
            "orders_2026",
            description="Order fact table + customer dimension.",
        )

        # 2) Upload a single file
        await fly.upload(ds.id, "examples/csv/sales_orders.csv")

        # 3) Or bulk-upload every supported file in a directory --
        #    runs through the same per-file pipeline in PARALLEL on
        #    the server side; per-file failures don't abort the bulk.
        outcome = await fly.upload_directory(ds.id, "examples/")
        print(f"uploaded {outcome.succeeded}/{outcome.total_files}")
        for r in outcome.results:
            print(f"  {r.original_filename}: {r.status} ({len(r.tables)} tables)")

        # 4) Ask one question
        ans = await fly.ask(ds.id, "What was last quarter's total revenue?")
        print(ans.sql)
        print(ans.preview)
        print(ans.explanation)

        # 5) Or ask many in parallel -- one batched HTTP round-trip,
        #    the server fans them out through asyncio.gather. Each
        #    result carries the same shape as ``ans`` above plus a
        #    ``status`` field that distinguishes OK from FAILED.
        batch = await fly.ask_batch(ds.id, [
            "Top 5 customers by revenue?",
            "Average order size by country?",
            "Refund rate this quarter?",
        ])
        for r in batch.results:
            print(f"#{r.index} {r.status}: {(r.sql or '')[:80]}")


asyncio.run(main())

```

--------------------------------

### Create Workspace Example

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/WorkspacesApi.md

Demonstrates how to create a new workspace using the WorkspacesApi in the Java SDK. Includes setup, API key configuration for WorkspaceContext and TenantContext, and error handling.

```java
// Import classes:
import com.firefly.flyquery.ApiClient;
import com.firefly.flyquery.ApiException;
import com.firefly.flyquery.Configuration;
import com.firefly.flyquery.auth.*;
import com.firefly.flyquery.models.*;
import com.firefly.flyquery.api.WorkspacesApi;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("http://localhost");
        
        // Configure API key authorization: WorkspaceContext
        ApiKeyAuth WorkspaceContext = (ApiKeyAuth) defaultClient.getAuthentication("WorkspaceContext");
        WorkspaceContext.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //WorkspaceContext.setApiKeyPrefix("Token");

        // Configure API key authorization: TenantContext
        ApiKeyAuth TenantContext = (ApiKeyAuth) defaultClient.getAuthentication("TenantContext");
        TenantContext.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //TenantContext.setApiKeyPrefix("Token");

        WorkspacesApi apiInstance = new WorkspacesApi(defaultClient);
        String xTenantId = "acme-corp"; // String | Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.
        String xWorkspaceId = "00000000-0000-0000-0000-000000000001"; // String | Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.
        WorkspaceCreate workspaceCreate = new WorkspaceCreate(); // WorkspaceCreate | 
        UUID xCorrelationId = UUID.fromString("550e8400-e29b-41d4-a716-446655440000"); // UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header.
        String idempotencyKey = "ingest-2026-05-23-abc123"; // String | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h.
        try {
            WorkspaceRead result = apiInstance.create(xTenantId, xWorkspaceId, workspaceCreate, xCorrelationId, idempotencyKey);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling WorkspacesApi#create");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Explain Query Example

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/QueryApi.md

Demonstrates how to use the explain method of the QueryApi to get a preview of the generated SQL. Ensure you have configured API key authorization for WorkspaceContext and TenantContext.

```java
import com.firefly.flyquery.ApiClient;
import com.firefly.flyquery.ApiException;
import com.firefly.flyquery.Configuration;
import com.firefly.flyquery.auth.*;
import com.firefly.flyquery.models.*;
import com.firefly.flyquery.api.QueryApi;
import java.util.UUID;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("http://localhost");
        
        // Configure API key authorization: WorkspaceContext
        ApiKeyAuth WorkspaceContext = (ApiKeyAuth) defaultClient.getAuthentication("WorkspaceContext");
        WorkspaceContext.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //WorkspaceContext.setApiKeyPrefix("Token");

        // Configure API key authorization: TenantContext
        ApiKeyAuth TenantContext = (ApiKeyAuth) defaultClient.getAuthentication("TenantContext");
        TenantContext.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //TenantContext.setApiKeyPrefix("Token");

        QueryApi apiInstance = new QueryApi(defaultClient);
        String xTenantId = "acme-corp"; // String | Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.
        String xWorkspaceId = "00000000-0000-0000-0000-000000000001"; // String | Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.
        QueryRequest queryRequest = new QueryRequest(); // QueryRequest | 
        UUID xCorrelationId = UUID.fromString("550e8400-e29b-41d4-a716-446655440000"); // UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header.
        String idempotencyKey = "ingest-2026-05-23-abc123"; // String | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h.
        try {
            ExplainResponse result = apiInstance.explain(xTenantId, xWorkspaceId, queryRequest, xCorrelationId, idempotencyKey);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling QueryApi#explain");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Boot the Flyquery Stack

Source: https://github.com/firefly-operationos/flyquery/blob/main/QUICKSTART.md

Starts the necessary Docker services (Postgres, Redis, MinIO), installs dependencies, migrates the database, and serves the Flyquery API.

```bash
docker compose up -d postgres redis minio
task install
task migrate
task serve   # listens on :8520
```

--------------------------------

### Create Example using Python SDK

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/python/docs/ExamplesApi.md

Demonstrates how to create an example using the Examples API. This snippet shows setting up the SDK configuration, authentication, and making the API call to create an example. It includes handling optional parameters like correlation ID and idempotency key.

```python
import flyquery_sdk
from flyquery_sdk.models.example_create import ExampleCreate
from flyquery_sdk.models.example_read import ExampleRead
from flyquery_sdk.rest import ApiException
from pprint import pprint
import os
from uuid import UUID

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = flyquery_sdk.Configuration(
    host = "http://localhost"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: WorkspaceContext
configuration.api_key['WorkspaceContext'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['WorkspaceContext'] = 'Bearer'

# Configure API key authorization: TenantContext
configuration.api_key['TenantContext'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['TenantContext'] = 'Bearer'

# Enter a context with an instance of the API client
async with flyquery_sdk.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = flyquery_sdk.ExamplesApi(api_client)
    x_tenant_id = 'acme-corp' # str | Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.
    x_workspace_id = '00000000-0000-0000-0000-000000000001' # str | Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.
    example_create = flyquery_sdk.ExampleCreate() # ExampleCreate | 
    x_correlation_id = UUID('550e8400-e29b-41d4-a716-446655440000') # UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header. (optional)
    idempotency_key = 'ingest-2026-05-23-abc123' # str | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h. (optional)

    try:
        # Create an example; defaults to source=USER_CURATED, quality=PROPOSED.
        api_response = await api_instance.create(x_tenant_id, x_workspace_id, example_create, x_correlation_id=x_correlation_id, idempotency_key=idempotency_key)
        print("The response of ExamplesApi->create:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling ExamplesApi->create: %s\n" % e)

```

--------------------------------

### Python Example: AgentQueryApi Explain with API Key Authentication

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/python/docs/AgentQueryApi.md

Demonstrates how to authenticate using an AgentToken and call the explain method. Ensure you have the flyquery_sdk installed and your API key set as an environment variable.

```python
import flyquery_sdk
from flyquery_sdk.models.explain_response import ExplainResponse
from flyquery_sdk.models.query_request import QueryRequest
from flyquery_sdk.rest import ApiException
from pprint import pprint
import os
from uuid import UUID

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = flyquery_sdk.Configuration(
    host = "http://localhost"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: AgentToken
configuration.api_key['AgentToken'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['AgentToken'] = 'Bearer'

# Enter a context with an instance of the API client
async with flyquery_sdk.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = flyquery_sdk.AgentQueryApi(api_client)
    x_agent_token = 'fqt_live_aBcDeF1234567890aBcDeF1234567890' # str | Machine-to-machine bearer token. Replaces X-Tenant-Id and X-Workspace-Id on agent-tier endpoints -- the token's claims encode the tenant + workspace + scopes. Issue via ``POST /api/v1/agent-tokens``.
    query_request = flyquery_sdk.QueryRequest() # QueryRequest | 
    x_correlation_id = UUID('550e8400-e29b-41d4-a716-446655440000') # UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header. (optional)
    idempotency_key = 'ingest-2026-05-23-abc123' # str | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h. (optional)

    try:
        # Run Grounding + Generation only (agent-tier).
        api_response = await api_instance.explain(x_agent_token, query_request, x_correlation_id=x_correlation_id, idempotency_key=idempotency_key)
        print("The response of AgentQueryApi->explain:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling AgentQueryApi->explain: %s\n" % e)

```

--------------------------------

### getExample

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/ExamplesApi.md

Fetches a single example by its ID. It returns a 404 status code if the example is not found.

```APIDOC
## getExample

### Description
Fetches a single example by its ID. Returns 404 if not found.

### Method
GET

### Endpoint
/examples/{exampleId}

### Parameters
#### Path Parameters
- **exampleId** (String) - Required - The ID of the example to fetch.

#### Header Parameters
- **xTenantId** (String) - Required - Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.
- **xWorkspaceId** (String) - Required - Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.
- **xCorrelationId** (UUID) - Optional - Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header.

### Response
#### Success Response (200)
- **ExampleRead** (object) - Successful response containing the example data.

### Authorization
- WorkspaceContext
- TenantContext
```

--------------------------------

### getExample

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/ExamplesApi.md

Fetch a single example by its ID. Returns 404 if the example is not found.

```APIDOC
## GET /api/v1/examples/{example_id}

### Description
Fetch a single example by id. Returns 404 if not found.

### Method
GET

### Endpoint
/api/v1/examples/{example_id}

### Parameters
#### Path Parameters
- **example_id** (string) - Required - The ID of the example to fetch.
```

--------------------------------

### Add Example

Source: https://github.com/firefly-operationos/flyquery/blob/main/docs/api-reference.md

Adds a user-curated (question, SQL) pair to the example store. The quality parameter determines if the example is immediately available for retrieval or requires approval.

```APIDOC
## POST /api/v1/examples

### Description
Add a user-curated `(question, SQL)` pair to the example store.

### Method
POST

### Endpoint
/api/v1/examples

### Parameters
#### Request Body
- **question** (string) - Required - The natural language question.
- **generated_sql** (string) - Required - The SQL query corresponding to the question.
- **dataset_id** (string) - Required - The ID of the dataset.
- **quality** (string) - Optional - The quality of the example. Can be `APPROVED` or `PROPOSED`. Defaults to `PROPOSED`.

### Request Example
```json
{
  "question": "What is the total revenue by region for Q1 2026?",
  "generated_sql": "SELECT region, SUM(amount) FROM orders WHERE order_date >= '2026-01-01' AND order_date < '2026-04-01' GROUP BY region",
  "dataset_id": "01906f2a-...",
  "quality": "APPROVED"
}
```
```

--------------------------------

### Add User-Curated Example

Source: https://github.com/firefly-operationos/flyquery/blob/main/docs/api-reference.md

Use this endpoint to add a user-curated question and SQL pair to the example store. Setting quality to APPROVED immediately enters the example into the retrieval pool.

```json
{
  "question": "What is the total revenue by region for Q1 2026?",
  "generated_sql": "SELECT region, SUM(amount) FROM orders WHERE order_date >= '2026-01-01' AND order_date < '2026-04-01' GROUP BY region",
  "dataset_id": "01906f2a-...",
  "quality": "APPROVED"
}
```

--------------------------------

### List Examples with Java SDK

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/ExamplesApi.md

Demonstrates how to instantiate the ExamplesApi and call the listExamples method with various parameters. Includes API key configuration for authentication.

```java
// Import classes:
import com.firefly.flyquery.ApiClient;
import com.firefly.flyquery.ApiException;
import com.firefly.flyquery.Configuration;
import com.firefly.flyquery.auth.*;
import com.firefly.flyquery.models.*;
import com.firefly.flyquery.api.ExamplesApi;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("http://localhost");
        
        // Configure API key authorization: WorkspaceContext
        ApiKeyAuth WorkspaceContext = (ApiKeyAuth) defaultClient.getAuthentication("WorkspaceContext");
        WorkspaceContext.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //WorkspaceContext.setApiKeyPrefix("Token");

        // Configure API key authorization: TenantContext
        ApiKeyAuth TenantContext = (ApiKeyAuth) defaultClient.getAuthentication("TenantContext");
        TenantContext.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //TenantContext.setApiKeyPrefix("Token");

        ExamplesApi apiInstance = new ExamplesApi(defaultClient);
        String xTenantId = "acme-corp"; // String | Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.
        String xWorkspaceId = "00000000-0000-0000-0000-000000000001"; // String | Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.
        String quality = "quality_example"; // String | 
        String datasetId = "datasetId_example"; // String | 
        Integer limit = 100; // Integer | 
        Integer offset = 0; // Integer | 
        UUID xCorrelationId = UUID.fromString("550e8400-e29b-41d4-a716-446655440000"); // UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header.
        try {
            PaginatedExampleRead result = apiInstance.listExamples(xTenantId, xWorkspaceId, quality, datasetId, limit, offset, xCorrelationId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling ExamplesApi#listExamples");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Setup Development Environment

Source: https://github.com/firefly-operationos/flyquery/blob/main/CONTRIBUTING.md

Use uv to create and synchronize development dependencies.

```bash
uv venv
uv sync --extra dev
```

--------------------------------

### GET /api/v1/billing Response Example

Source: https://github.com/firefly-operationos/flyquery/blob/main/docs/api-reference.md

Example response for the GET /api/v1/billing endpoint, showing aggregated cost data broken down by day.

```json
{
  "period": "day",
  "date_from": "2026-05-01T00:00:00Z",
  "date_to": "2026-05-24T00:00:00Z",
  "total_cost_cents": 14230,
  "breakdown": [
    {
      "date": "2026-05-23T00:00:00Z",
      "ingest_cost_cents": 200,
      "query_cost_cents": 14030,
      "other_cost_cents": 0,
      "total_cost_cents": 14230
    }
  ]
}
```

--------------------------------

### Create Example using Java SDK

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/ExamplesApi.md

This snippet demonstrates how to create an example using the ExamplesApi in the Java SDK. It includes setting up the API client, configuring authentication for WorkspaceContext and TenantContext, and making the create call with required parameters. It also shows how to handle potential API exceptions.

```java
import com.firefly.flyquery.ApiClient;
import com.firefly.flyquery.ApiException;
import com.firefly.flyquery.Configuration;
import com.firefly.flyquery.auth.*;
import com.firefly.flyquery.models.*;
import com.firefly.flyquery.api.ExamplesApi;

import java.util.UUID;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("http://localhost");
        
        // Configure API key authorization: WorkspaceContext
        ApiKeyAuth WorkspaceContext = (ApiKeyAuth) defaultClient.getAuthentication("WorkspaceContext");
        WorkspaceContext.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //WorkspaceContext.setApiKeyPrefix("Token");

        // Configure API key authorization: TenantContext
        ApiKeyAuth TenantContext = (ApiKeyAuth) defaultClient.getAuthentication("TenantContext");
        TenantContext.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //TenantContext.setApiKeyPrefix("Token");

        ExamplesApi apiInstance = new ExamplesApi(defaultClient);
        String xTenantId = "acme-corp"; // String | Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.
        String xWorkspaceId = "00000000-0000-0000-0000-000000000001"; // String | Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.
        ExampleCreate exampleCreate = new ExampleCreate(); // ExampleCreate | 
        UUID xCorrelationId = UUID.fromString("550e8400-e29b-41d4-a716-446655440000"); // UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header.
        String idempotencyKey = "ingest-2026-05-23-abc123"; // String | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h.
        try {
            ExampleRead result = apiInstance.create(xTenantId, xWorkspaceId, exampleCreate, xCorrelationId, idempotencyKey);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling ExamplesApi#create");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Start Ingestion Job with AgentToken Authentication

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/python/docs/AgentIngestJobsApi.md

This snippet demonstrates how to start a background ingestion job using API key authentication (AgentToken). Ensure you have the flyquery_sdk installed and your API key configured.

```python
import flyquery_sdk
from flyquery_sdk.rest import ApiException
from pprint import pprint
import os
from uuid import UUID

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = flyquery_sdk.Configuration(
    host = "http://localhost"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: AgentToken
configuration.api_key['AgentToken'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['AgentToken'] = 'Bearer'

# Enter a context with an instance of the API client
async with flyquery_sdk.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = flyquery_sdk.AgentIngestJobsApi(api_client)
    x_agent_token = 'fqt_live_aBcDeF1234567890aBcDeF1234567890' # str | Machine-to-machine bearer token. Replaces X-Tenant-Id and X-Workspace-Id on agent-tier endpoints -- the token's claims encode the tenant + workspace + scopes. Issue via ``POST /api/v1/agent-tokens``.
    x_correlation_id = UUID('550e8400-e29b-41d4-a716-446655440000') # UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header. (optional)
    idempotency_key = 'ingest-2026-05-23-abc123' # str | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h. (optional)

    try:
        # Start a background ingestion job (REPARSE/SAMPLE_REFRESH/...). 
        await api_instance.create_job(x_agent_token, x_correlation_id=x_correlation_id, idempotency_key=idempotency_key)
    except Exception as e:
        print("Exception when calling AgentIngestJobsApi->create_job: %s\n" % e)

```

--------------------------------

### Java Example for AgentQueryApi explain

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/AgentQueryApi.md

Demonstrates how to initialize the ApiClient, configure API key authentication, and call the explain method with necessary parameters. Includes error handling for API exceptions.

```java
// Import classes:
import com.firefly.flyquery.ApiClient;
import com.firefly.flyquery.ApiException;
import com.firefly.flyquery.Configuration;
import com.firefly.flyquery.auth.*;
import com.firefly.flyquery.models.*;
import com.firefly.flyquery.api.AgentQueryApi;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("http://localhost");
        
        // Configure API key authorization: AgentToken
        ApiKeyAuth AgentToken = (ApiKeyAuth) defaultClient.getAuthentication("AgentToken");
        AgentToken.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //AgentToken.setApiKeyPrefix("Token");

        AgentQueryApi apiInstance = new AgentQueryApi(defaultClient);
        String xAgentToken = "fqt_live_aBcDeF1234567890aBcDeF1234567890"; // String | Machine-to-machine bearer token. Replaces X-Tenant-Id and X-Workspace-Id on agent-tier endpoints -- the token's claims encode the tenant + workspace + scopes. Issue via ``POST /api/v1/agent-tokens``.
        QueryRequest queryRequest = new QueryRequest(); // QueryRequest | 
        UUID xCorrelationId = UUID.fromString("550e8400-e29b-41d4-a716-446655440000"); // UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header.
        String idempotencyKey = "ingest-2026-05-23-abc123"; // String | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h.
        try {
            ExplainResponse result = apiInstance.explain(xAgentToken, queryRequest, xCorrelationId, idempotencyKey);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AgentQueryApi#explain");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Fetch Workspace Stats

Source: https://github.com/firefly-operationos/flyquery/blob/main/docs/stats.md

Example of how to call the GET /api/v1/stats endpoint using curl. Ensure to set the correct tenant and workspace headers.

```bash
curl -sS http://localhost:8520/api/v1/stats \
  -H 'X-Tenant-Id: acme' \
  -H 'X-Workspace-Id: analytics'
```

--------------------------------

### create

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/java/docs/ExamplesApi.md

Create a new example. Defaults to source=USER_CURATED and quality=PROPOSED.

```APIDOC
## POST /api/v1/examples

### Description
Create an example; defaults to source=USER_CURATED, quality=PROPOSED.

### Method
POST

### Endpoint
/api/v1/examples
```

--------------------------------

### Create Agent Example

Source: https://github.com/firefly-operationos/flyquery/blob/main/sdks/python/docs/AgentExamplesApi.md

Demonstrates how to create a new example using the AgentExamplesApi. Requires an agent token and an ExampleCreate object. Includes optional correlation ID and idempotency key for request management.

```python
import flyquery_sdk
from flyquery_sdk.models.example_create import ExampleCreate
from flyquery_sdk.models.example_read import ExampleRead
from flyquery_sdk.rest import ApiException
from pprint import pprint
import os
from uuid import UUID

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = flyquery_sdk.Configuration(
    host = "http://localhost"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: AgentToken
configuration.api_key['AgentToken'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['AgentToken'] = 'Bearer'

# Enter a context with an instance of the API client
async with flyquery_sdk.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = flyquery_sdk.AgentExamplesApi(api_client)
    x_agent_token = 'fqt_live_aBcDeF1234567890aBcDeF1234567890' # str | Machine-to-machine bearer token. Replaces X-Tenant-Id and X-Workspace-Id on agent-tier endpoints -- the token's claims encode the tenant + workspace + scopes. Issue via ``POST /api/v1/agent-tokens``.
    example_create = flyquery_sdk.ExampleCreate() # ExampleCreate | 
    x_correlation_id = UUID('550e8400-e29b-41d4-a716-446655440000') # UUID | Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header. (optional)
    idempotency_key = 'ingest-2026-05-23-abc123' # str | Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h. (optional)

    try:
        # Create an example (agent-tier — source=AGENT_LEARNED, quality=PROPOSED).
        api_response = await api_instance.create(x_agent_token, example_create, x_correlation_id=x_correlation_id, idempotency_key=idempotency_key)
        print("The response of AgentExamplesApi->create:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling AgentExamplesApi->create: %s\n" % e)

```