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": {}}.