# Aito.ai API v2 Documentation (Beta)

Aito is a database with built-in machine learning capabilities.
It provides prediction, recommendation, similarity search, and data matching through a REST API.

Base URL — one of:
- Dedicated instance:    https://<your-instance>.aito.ai
- Multi-tenant / shared: https://<host>/db/<database>   (public demo: https://shared.aito.ai/db/aito-demo)
- Environment (branch):  insert /env/<name> before /api (e.g. https://shared.aito.ai/db/aito-demo/env/v2/api/v2/_predict)
Authentication: x-api-key header (the same key reads and writes every environment).

Full documentation: https://aito.ai/docs/api/v2/
OpenAPI spec (covers both v1 and v2, served as text/yaml): https://aito.ai/docs/api/openapi.yaml

## API Endpoints

### Query Operations

**POST /api/v2/_query** - Query (v2)
Query rows using the v2 Query2 engine.
Example request:
```json
{
  "from": "products",
  "limit": 3
}
```

**POST /api/v2/_search** - Search (v2)
Full-text and structured search over a v2 collection.

**POST /api/v2/_predict** - Predict (v2)
Predict the value of a field from the evidence in `where`.
Example request:
```json
{
  "from": "products",
  "where": {
    "name": "rye bread"
  },
  "predict": "category"
}
```

**POST /api/v2/_recommend** - Recommend (v2)
Recommend the values of a field that best advance a goal.
Example request:
```json
{
  "from": "impressions",
  "where": {
    "context.user": "veronica"
  },
  "recommend": "product",
  "goal": {
    "purchase": true
  },
  "limit": 3
}
```

**POST /api/v2/_relate** - Relate (v2)
Find statistical relations between fields instead of returning rows.
Example request:
```json
{
  "from": "impressions",
  "where": {
    "product.tags": {
      "$has": "vegetable"
    }
  },
  "relate": [
    "purchase"
  ],
  "limit": 5
}
```

**POST /api/v2/_match** - Match (v2)
Match a context to the best-fitting values of a field.
Example request:
```json
{
  "from": "impressions",
  "where": {
    "context.user": "larry"
  },
  "match": "product",
  "limit": 5
}
```

**POST /api/v2/_evaluate** - Evaluate (v2)
Measure how well a v2 query performs on your own data.
Example request:
```json
{
  "test": {
    "$index": {
      "$mod": [
        4,
        0
      ]
    }
  },
  "evaluate": {
    "from": "products",
    "where": {
      "name": {
        "$get": "name"
      }
    },
    "predict": "category"
  },
  "select": [
    "n",
    "accuracy",
    "baseAccuracy",
    "accuracyGain",
    "meanRank"
  ]
}
```

**POST /api/v2/_estimate** - Estimate (v2)
Estimate the value of a numeric field from evidence.

**POST /api/v2/_aggregate** - Aggregate (v2)
Compute aggregate statistics over a collection.
Example request:
```json
{
  "from": "products",
  "aggregate": [
    "price.$mean",
    "price.$sum",
    "googleClicks.$mean"
  ]
}
```

**POST /api/v2/_batch** - Batch (v2)
Run several v2 queries in a single request.
Example request:
```json
[
  {
    "from": "products",
    "where": {
      "name": "rye bread"
    },
    "predict": "category"
  },
  {
    "from": "products",
    "where": {
      "name": "rye bread"
    },
    "predict": "tags"
  }
]
```

### Schema Operations

**GET /api/v2/schema** - List Tables (v2)

**GET /api/v2/schema/{table}** - Get Table Schema (v2)

**PUT /api/v2/schema/{table}** - Create Table (v2)

**PUT /api/v2/schema/{table}/{column}** - Add or alter column (v2)

**POST /api/v2/schema/{table}/_plan** - Plan schema change (v2)

**POST /api/v2/schema/{table}/_apply** - Apply schema change (v2)

**DELETE /api/v2/schema/{table}** - Delete Table (v2)

### Data Operations

**POST /api/v2/data/{table}** - Insert Document (v2)

**POST /api/v2/data/{table}/batch** - Batch Insert (v2)

**POST /api/v2/data/_modify** - Modify data (v2)

**POST /api/v2/data/{table}/_backfill** - Bulk backfill (v2)

## Query Language

Aito uses a JSON-based query language with the following key operators:

### Propositions (WHERE clauses)
- `{"field": "value"}` - exact match
- `{"field": {"$has": "value"}}` - contains value (for arrays/text)
- `{"field": {"$match": "text"}}` - full-text search
- `{"field": {"$gt": n}}` - greater than
- `{"field": {"$gte": n}}` - greater than or equal
- `{"field": {"$lt": n}}` - less than
- `{"field": {"$lte": n}}` - less than or equal
- `{"$and": [...]}` - logical AND
- `{"$or": [...]}` - logical OR
- `{"$not": {...}}` - logical NOT

### Common Query Parameters
- `from` - table name to query
- `where` - filter conditions (proposition)
- `limit` - max results (default 10)
- `offset` - skip results for pagination
- `orderBy` - sort field
- `select` - fields to return

### Prediction Query
```json
{
  "from": "tableName",
  "where": {
    "knownField": "value"
  },
  "predict": "targetField"
}
```

### Recommendation Query
```json
{
  "from": "tableName",
  "where": {
    "context": "value"
  },
  "recommend": "itemField",
  "goal": {
    "outcomeField": true
  }
}
```

## Data Types

Aito supports the following column types:
- `String` - text values
- `Int` - 32-bit integer
- `Long` - 64-bit integer
- `Decimal` - floating point
- `Boolean` - true/false
- `Text` - analyzed text (for full-text search)
- `String[]` - array of strings
- `Int[]` - array of integers
- `Long[]` - array of 64-bit integers
- `Decimal[]` - array of decimals

## API v2 (Beta)

Aito API v2 runs the new rep2 engine: explainable predictions ($why),
full-text search ($search), vector search ($nearest), itemset mining
($patterns), and schema-flexible collections. Base path: /api/v2/.

v2 documentation: https://aito.ai/docs/api/v2/
v2 query operator reference: https://aito.ai/docs/api/v2/query-reference/
The complete v2 endpoint and operator details are in llms-full.txt.

---
Generated from Aito API documentation
For the complete OpenAPI specification, see: https://aito.ai/docs/api/openapi.yaml