API reference
Base URL: https://theunibot.com. All bodies are JSON. Authenticated calls send Authorization: Bearer <token>; see Authentication.
Errors
{"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:
{
"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": {}}.