# API reference

Base URL: `https://theunibot.com`. All bodies are JSON. Authenticated calls send `Authorization: Bearer <token>`; see [Authentication](/docs/auth).

## Errors

```json
{"status": 404, "message": "The requested resource wasn't found.", "data": {}}
```

Validation failures list the offending fields under `data`.

## Public ask route

### `GET /v1/bots/{slug}/ask?q=<question>`

No authentication. Answers from a public bot's stored questions and answers.

| Parameter | Description |
| --- | --- |
| `slug` | The bot's slug |
| `q` | The question, 1 to 300 characters |

Response `200`:

```json
{
  "bot": {"slug": "quillfeather-books", "name": "Quillfeather Books", "greeting": "..."},
  "query": "opening hours",
  "matched": true,
  "answer": {"question": "What are your opening hours?", "answer": "...", "score": 1},
  "alternatives": [{"question": "Do you host events or book clubs?", "score": 0.5}]
}
```

`matched` is `false` and `answer` is `null` when nothing is close enough. `score` runs from 0 to 1.

| Status | When |
| --- | --- |
| 400 | `q` is missing, empty or longer than 300 characters |
| 404 | The slug does not exist or the bot is private |

## Accounts

| Method and path | Purpose |
| --- | --- |
| `POST /api/collections/users/records` | Sign up with `email`, `password`, `passwordConfirm`, optional `name` |
| `POST /api/collections/users/request-otp` | Email a one-time code for `email`; returns `otpId` |
| `POST /api/collections/users/auth-with-otp` | Body `otpId` and `password` (the code); returns `token` and `record` |
| `POST /api/collections/users/auth-with-password` | Body `identity` (email) and `password`; returns `token` and `record` |
| `POST /v1/account/password` | Signed in. Body `password`, `passwordConfirm` (8 to 72 characters); sets the password and returns a fresh `token` and `record` |
| `POST /api/collections/users/auth-refresh` | Returns a fresh token |
| `POST /api/collections/users/request-password-reset` | Email a reset link |
| `GET /api/collections/users/records/{id}` | Read your own record |
| `PATCH /api/collections/users/records/{id}` | Update your own record |

## Bots

Collection: `bots`. Fields:

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | Generated |
| `owner` | user id | Required on create; must be you |
| `name` | string | 2 to 80 characters |
| `slug` | string | Unique; `^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$` |
| `greeting` | string | Up to 300 characters |
| `public` | boolean | Whether the public ask route answers |
| `created`, `updated` | datetime | Generated |

| Method and path | Purpose |
| --- | --- |
| `GET /api/collections/bots/records` | List your bots. Supports `page`, `perPage`, `sort`, `filter` |
| `GET /api/collections/bots/records/{id}` | Read one of your bots |
| `POST /api/collections/bots/records` | Create a bot |
| `PATCH /api/collections/bots/records/{id}` | Update a bot |
| `DELETE /api/collections/bots/records/{id}` | Delete a bot and its answers |

## Answers

Collection: `answers`. Fields: `bot` (bot id, required), `question` (2 to 300 characters), `answer` (up to 4000 characters).

| Method and path | Purpose |
| --- | --- |
| `GET /api/collections/answers/records?filter=(bot='<bot id>')` | List answers of a bot you own |
| `POST /api/collections/answers/records` | Add an answer to a bot you own |
| `PATCH /api/collections/answers/records/{id}` | Edit an answer |
| `DELETE /api/collections/answers/records/{id}` | Delete an answer |

## Health

`GET /api/health` returns `{"message": "API is healthy.", "code": 200, "data": {}}`.
