Guides

Build with Avaloka, step by step

Each guide is a short sequence of real API calls — from your first upload to serving a model and wiring GitHub. Copy the commands, swap in your token and IDs, and you're running.

Full API reference Try it live

Quickstart

Upload a CSV and preview it

Get data into your workspace in two calls, then confirm the schema and rows landed as expected.

Upload the file

Send one or more CSVs as multipart form data. The response contains the new dataset IDs.

curl -X POST https://app.avaloka.ai/api/upload \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -F "files=@sales.csv"

2
List what you have
Datasets are workspace-scoped, so listing shows uploads plus anything registered from your own storage.
```
curl https://app.avaloka.ai/datasets \
  -H "Authorization: Bearer $AVALOKA_TOKEN"
```

Preview rows

Check column types and a sample of rows before you build anything on top of the dataset.

curl https://app.avaloka.ai/datasets/$DATASET_ID/preview \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

4
Watch background processing
Large files finish profiling asynchronously — poll until the background task reports completion.
```
curl https://app.avaloka.ai/api/datasets/$DATASET_ID/background-task-status \
  -H "Authorization: Bearer $AVALOKA_TOKEN"
```

Ingestion

Register storage you already own

Keep data where it lives. Register a bucket or folder and Avaloka reads it in place instead of copying it.

Register the location

Point Avaloka at a bucket path or a whole folder of files.

curl -X POST https://app.avaloka.ai/api/register-existing-folder \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "s3://my-bucket/exports/2026/"}'

2
Browse the objects
Confirm Avaloka can see the files before you register them as datasets.
```
curl "https://app.avaloka.ai/buckets/list" \
  -H "Authorization: Bearer $AVALOKA_TOKEN"
```

Conversational AI

Ask questions in a thread

Threads are the conversational surface. Create one, send a question, then poll until the turn completes and read the answer.

Create a thread

A thread holds the conversation, the plan and every asset produced along the way.

curl -X POST https://app.avaloka.ai/threads \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

Send a message

Ask in plain language. Avaloka plans the work, writes the code and runs it.

curl -X POST https://app.avaloka.ai/threads/$THREAD_ID/messages \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Which regions grew fastest last quarter?"}'

Wait for the turn

Poll the pending turn endpoint, then fetch history once it clears.

curl https://app.avaloka.ai/threads/$THREAD_ID/pending-turn \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

curl https://app.avaloka.ai/threads/$THREAD_ID/messages \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

Inspect the reasoning

Pull the generated code or render the planner graph to see exactly how the answer was produced.

curl https://app.avaloka.ai/threads/$THREAD_ID/code \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

curl https://app.avaloka.ai/threads/$THREAD_ID/planner-graph \
  -H "Authorization: Bearer $AVALOKA_TOKEN" --output planner.png

Automation

Plan a mission and track its tasks

For programmatic workloads, submit a structured intent, then follow the tasks it spawns to completion.

Plan from an intent

The planner returns the same shared representation the CLI and MCP server produce.

curl -X POST https://app.avaloka.ai/api/missions/plan \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal": "forecast monthly churn", "dataset_id": "'$DATASET_ID'"}'

Follow the run

Poll status, list runs and fetch each result by index as it becomes available.

curl https://app.avaloka.ai/tasks/$TASK_ID/status \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

curl https://app.avaloka.ai/tasks/$TASK_ID/result/0 \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

Cancel if needed

Long-running work can be stopped cleanly without leaving orphaned resources.

curl -X DELETE https://app.avaloka.ai/tasks/$TASK_ID \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

SQL Warehouse

Connect a database and query it

Attach a live database, promote the tables you care about into an analysis, then query conversationally.

Connect

Credentials are stored encrypted and scoped to your workspace.

curl -X POST https://app.avaloka.ai/api/database/connect \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"engine": "postgres", "host": "...", "database": "analytics"}'

Promote tables

Turn a selection of tables into a ready-to-question analysis.

curl -X POST https://app.avaloka.ai/api/database/tables-to-analysis \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tables": ["public.orders", "public.customers"]}'

Query in natural language

Sampled queries return fast so you can iterate on the question before running it at full scale.

curl -X POST https://app.avaloka.ai/api/v1/database/query \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "Top 10 customers by revenue this year"}'

Inference models

Serve a model and run inference

Every training run produces a model you can configure as a hosted inference service and call from your app.

Find the run

List models, then read the details for the run you want to serve.

curl https://app.avaloka.ai/api/models \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

Start the service

Configure the inference service once; it stays warm until you stop it.

curl -X POST https://app.avaloka.ai/api/models/$RUN_ID/configure-inference-service \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

Predict

Send feature payloads and get predictions back synchronously.

curl -X POST https://app.avaloka.ai/api/models/$RUN_ID/inference \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": [{"tenure": 14, "plan": "plus"}]}'

Stop when idle

Shut the service down to release compute — the model stays available to restart later.

curl -X POST https://app.avaloka.ai/api/models/$RUN_ID/stop-inference-service \
  -H "Authorization: Bearer $AVALOKA_TOKEN" -d '{}'

Auto insights

Version, refresh and improve an analysis

Analyses are living artefacts: refresh them on new data, review versions and roll back when an edit goes wrong.

Read the code

Every analysis exposes the code that produced it, so nothing is a black box.

curl https://app.avaloka.ai/analysis/$ANALYSIS_ID/code \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

Edit and execute

Save your changes and run them in one call — a new version is recorded automatically.

curl -X POST https://app.avaloka.ai/analysis/$ANALYSIS_ID/save-and-execute \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "# updated analysis"}'

Roll back

List versions and restore any earlier one if the latest run isn't right.

curl https://app.avaloka.ai/analysis/$ANALYSIS_ID/versions \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

curl -X POST https://app.avaloka.ai/analysis/$ANALYSIS_ID/restore \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" -d '{"version": 3}'

Send feedback

Feedback tunes future results for the same question shape.

curl -X POST https://app.avaloka.ai/analysis/$ANALYSIS_ID/feedback \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rating": "up", "comment": "Right segmentation"}'

Integrations

Connect GitHub and manage connections

Push generated code to your own repositories and manage credentials for connected tools.

See what's connected

One call returns every integration and its status.

curl https://app.avaloka.ai/api/integrations \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

Connect GitHub

Link a repository so analyses and models can be versioned alongside your application code.

curl -X POST https://app.avaloka.ai/api/integrations/github/connect \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repository": "acme/analytics"}'

Rotate or disconnect

Update the connection in place, or remove it entirely when access should end.

curl -X PATCH https://app.avaloka.ai/api/integrations/github \
  -H "Authorization: Bearer $AVALOKA_TOKEN" \
  -H "Content-Type: application/json" -d '{"branch": "main"}'

curl -X DELETE https://app.avaloka.ai/api/integrations/github \
  -H "Authorization: Bearer $AVALOKA_TOKEN"

Need a guide we haven't written?

Tell us the workflow you're building and we'll help you map it to the right endpoints.

Talk to us Visit the help centre