REST Integration

Expose Arivu as a clean HTTP API for web apps, mobile clients, CLIs, and custom services.

Theory & Example

What the backend needs

The REST adapter in integrations/rest_adapter.py exposes the pipeline as a FastAPI application.

Required values:

• ARIVU_API_KEY or api_key if you want auth
• A host and port for the API server
• Optional CORS configuration when embedding in browser apps

What the REST API returns

Query result

Returns the generated SQL, the natural-language response, success state, and session ID.

Approval flow

Returns pending_approval: true when the SQL must be approved before execution.

RLHF feedback

Accepts positive/negative feedback for a session.

Health check

Returns backend health, integration name, schema age, and active mode.

Setup steps

1. Create the REST server

   Instantiate RESTIntegration with your Arivu connection.

2. Add an API key

   Set ARIVU_API_KEY if you want requests to require authentication.

3. Start the server

   Call adapter.start(host="0.0.0.0", port=8000) or mount the FastAPI app in your own process.

4. Call /query

   POST a natural-language question and receive the generated SQL and answer in the JSON response.

Example

from arivu.integrations.rest_adapter import RESTIntegration

adapter = RESTIntegration(
    db=db,
    api_key="your-secret-key",
)

adapter.start(host="0.0.0.0", port=8000)

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"question":"How many users signed up today?","user_id":"rest_user"}'

Backend behavior

• Session IDs default to the provided user_id field, so API clients can keep their own session identity.
• pending_approval responses are returned in JSON so a caller can show a manual approval flow.
• /refresh refreshes the schema cache.
• /session/{session_id} returns stored session history.
• CORS is enabled by default to support browser clients, but you should restrict origins in production.

Use an API key in production. The REST adapter is intentionally simple so you can plug it into any client, but that also means auth is your responsibility.

API Docs

API overview

The REST adapter exposes the following backend endpoints:

POST /query

Run a natural language query and receive the response model.

POST /approve/{session_id}

Approve a pending SQL operation and execute it.

POST /reject/{session_id}

Reject a pending SQL operation.

POST /feedback/{session_id}

Save RLHF feedback for the session.

GET /session/{session_id}

Fetch stored session history.

GET /health

Check service health and schema age.

POST /query

Request model: QueryRequest

question · string · required

Natural-language prompt to answer.

user_id · string · default: "rest_user"

Session owner for the query. This becomes part of the backend session identity.

rlhf_signal · string

Optional feedback signal forwarded into the pipeline when you want to pre-tag the request.

Response model: QueryResponse

response · string · required

Final answer returned by the pipeline.

sql · string · required

Generated SQL that Arivu produced for the query.

success · boolean · required

Indicates whether the pipeline completed successfully.

pending_approval · boolean · required

Set to true when the SQL must be approved before execution.

session_id · string · required

Session identifier used by the backend for history, approval, and feedback.

error · string | null

Error text when the pipeline fails, otherwise null.

Example request

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"question":"How many users signed up today?","user_id":"rest_user"}'

POST /approve/{session_id}

Request model

session_id · string · required

Session whose pending SQL should be approved and executed.

X-API-Key · string

API key required when authentication is enabled.

Response model

status · string · required

Returns approved when the pending SQL has been executed.

session_id · string · required

The session that was approved.

What happens

• Looks up the pending SQL for the session
• Marks it as approved
• Executes the verified SQL directly through the SQLAlchemy engine

POST /reject/{session_id}

Request model

session_id · string · required

Session whose pending SQL should be rejected.

Response model

status · string · required

Returns rejected when the pending SQL is discarded.

session_id · string · required

The session that was rejected.

What happens

• Marks the pending approval as rejected
• Does not execute any SQL

POST /feedback/{session_id}

Request model

session_id · string · required

Session receiving the feedback signal.

signal · string · required

Feedback value. Use positive or negative.

Response model

status · string · required

Returns ok after the feedback is stored.

signal · string · required

The feedback value that was saved.

GET /session/{session_id}

Request model

session_id · string · required

Session whose stored history should be returned.

Response model

history · array · required

Stored messages, results, and actions for the session.

POST /refresh

Response model

status · string · required

Usually returns ok when the schema cache refreshes.

message · string · required

Human-readable confirmation text.

GET /health

Response model

status · string · required

Should always be ok when the service is healthy.

integration · string · required

Always returns rest.

schema_age_seconds · number · required

Age of the cached schema in seconds.

mode · string · required

Current backend mode such as user or admin.

Implementation notes

• This integration is FastAPI-based, so it can be mounted into a larger app or run standalone.
• Authentication is intentionally minimal: set an API key if you need protection.
• The backend returns structured JSON so a frontend can render its own approval or feedback workflow.