# Abbotik API

Abbotik API is a multi-tenant PaaS backend for model-first applications.
It gives tenants the raw HTTP surfaces to define their own models,
store records, query data, track changes, manage access, and move files.

This document is the agent-facing public entrypoint.
It is served at `/llms.txt`.
The human-facing root lives at `/` as HTML with a companion stylesheet at `/index.css`.

## Install surfaces

### Install server

Choose one:

- curl installer

```bash
curl -fsSL https://raw.githubusercontent.com/abbotik/api/main/apps/api/scripts/install.sh | bash
```

- Homebrew

```bash
brew install abbotik/tap/abbotik-api
```

### Install CLI

Choose one:

- curl installer

```bash
curl -fsSL https://raw.githubusercontent.com/abbotik/cli/main/scripts/install.sh | bash
```

- Homebrew

```bash
brew install abbotik/tap/abbot
```

## Start here

If you are a human or an LLM landing on the API, read these in order:

1. [API overview](/docs)
2. [MCP server](/docs/mcp)
3. [Authentication](/docs/auth)
4. [API Keys](/docs/api/keys)
5. [Data API](/docs/api/data)
6. [Describe API](/docs/api/describe)
7. [Find API](/docs/api/find)
8. [Aggregate API](/docs/api/aggregate)
9. [Bulk API](/docs/api/bulk)
10. [ACLs API](/docs/api/acls)
11. [Stat API](/docs/api/stat)
12. [Tracked API](/docs/api/tracked)
13. [Trashed API](/docs/api/trashed)
14. [Cron API](/docs/api/cron)
15. [LLM room protocol](/docs/llm/room)
16. [LLM factory protocol](/docs/llm/factory)
17. [LLM providers](/docs/llm/providers)
18. [LLM skills](/docs/llm/skills)
19. [Responses API](/docs/v1/responses)
20. [User API](/docs/api/user)
21. [Filesystem API](/docs/fs)

## What Abbotik API does

Abbotik API provides:

- model-first data access
- tenant-isolated storage
- an HTTP JSON-RPC MCP server at `/mcp`
- record-level ACLs
- change tracking and audit trails
- soft delete and restore workflows
- scheduled job management
- LLM execution protocols under `/llm/*`
- a root-mounted room-backed Responses ingress at `/v1/responses`
- provider and skill discovery for LLM execution
- filesystem-style tenant access under `/fs/*`
- response formatting for JSON, YAML, TOON, CSV, Markdown, and more

## Common workflow

## Critical onboarding path

If you are an agent or long-running client, get this working first.
Nothing else is reliable until authentication and token minting are working.

### Preferred machine-first path

1. Use machine auth for provisioning:
   - `POST /auth/provision`
   - sign the returned challenge nonce
   - `POST /auth/verify`
2. Use the user invite flow for adding more users:
   - tenant admin calls `POST /api/user/invite`
   - invited human uses `POST /auth/register/user` then `POST /auth/login`
   - invited machine uses `POST /auth/provision/user` then `POST /auth/verify`
3. Use the bearer API-key flow for durable service tokens:
   - `POST /api/keys`
   - reuse the returned global user API key directly in `Authorization: Bearer <token>`
4. Use tenant machine keys only when you need multiple stored public keys or fingerprint rotation for the same tenant identity:
   - `GET /api/user/machine-keys`
   - `POST /api/user/machine-keys`
   - `POST /api/user/machine-keys/rotate`
   - `DELETE /api/user/machine-keys/:key_id`

### Route choice summary

- Prefer `POST /auth/provision` + `POST /auth/verify` for initial machine bootstrap
- Prefer `POST /api/user/invite` for adding humans or machines to an existing tenant
- Prefer `POST /api/keys` for long-running clients and service tokens
- Use `/api/user/machine-keys` only if you need to manage multiple tenant-bound fingerprints or uploaded public keys

### Deprioritized human-first path

The username/password routes still exist, but they are not the recommended primary onboarding path for agents:

- `POST /auth/register`
- `POST /auth/login`

### Human tenant bootstrap

1. `POST /auth/register`
2. `POST /auth/login`
3. Use the returned bearer token on protected routes

### Existing-tenant human join

1. Existing tenant admin: `POST /api/user/invite`
2. Invited user: `POST /auth/register/user`
3. Invited user: `POST /auth/login`

### Machine tenant bootstrap

1. `POST /auth/provision`
2. Sign the returned challenge nonce
3. `POST /auth/verify`
4. Use `GET /api/user/machine-keys`, `POST /api/user/machine-keys`, `POST /api/user/machine-keys/rotate`, and `DELETE /api/user/machine-keys/:key_id` to manage machine credentials

### Existing-tenant machine join

1. Existing tenant admin: `POST /api/user/invite`
2. Invited machine: `POST /auth/provision/user`
3. Sign the returned challenge nonce
4. `POST /auth/verify`

### Tenant work

1. Use `/api/describe/*` to define or inspect models.
2. Use `/api/data/*` to create and update records.
3. Use `/api/find/*` and `/api/aggregate/*` for query and analysis.
4. Use `/api/tracked/*`, `/api/stat/*`, `/api/trashed/*`, and `/api/cron/*` for audit, lifecycle, and scheduled jobs.
5. Use `/llm/room/*` for bounded live LLM work.
6. Use `/llm/factory/*` for durable delivery orchestration state.
7. Use `/llm/providers` and `/llm/skills` to inspect execution options.
8. Use `/v1/responses` for room-backed response-style sessions.
9. Use `/fs/*` for tenant-scoped files.

### MCP workflow

1. Read `/docs/mcp`.
2. `POST /mcp` with JSON-RPC `initialize` and `Accept: application/json, text/event-stream`.
3. Persist the returned `Mcp-Session-Id` header and negotiated `MCP-Protocol-Version`.
4. Send both headers on later `POST /mcp` calls.
5. Call `tools/list`, then `tools/call` for `abbot_auth`, `abbot_describe`, `abbot_find`, `abbot_data`, `abbot_related`, and `abbot_bulk`.
6. `DELETE /mcp` with the same `Mcp-Session-Id` header when the session is no longer needed.

## Authentication

Most API routes require an Abbotik bearer token in the `Authorization` header.
That bearer slot may contain either a signed JWT or a global user API key:

```bash
Authorization: Bearer <token>
```

Public routes do not require authentication:

- `/`
- `/index.html`
- `/index.css`
- `/llms.txt`
- `/health`
- `/mcp`
- `/auth/register`
- `/auth/register/user`
- `/auth/login`
- `/auth/provision`
- `/auth/provision/user`
- `/auth/challenge`
- `/auth/verify`
- `/auth/refresh`
- `/auth/tenants`
- `/auth/dissolve`
- `/auth/dissolve/confirm`
- `/docs`
- `/docs/*`

Protected route families require a Abbotik bearer token:

- `/api/user/*`
- `/api/keys*`
- `/api/user/machine-keys*`
- `/api/data/*`
- `/api/describe/*`
- `/api/find/*`
- `/api/aggregate/*`
- `/api/bulk*`
- `/api/acls/*`
- `/api/stat/*`
- `/api/tracked/*`
- `/api/trashed/*`
- `/api/cron/*`
- `/llm/*`
- `/v1/*`
- `/fs/*`

## Example

```bash
curl http://localhost:9001/docs/api/data
curl http://localhost:9001/docs/api/keys
curl http://localhost:9001/docs/api/cron
curl http://localhost:9001/docs/llm/room
curl http://localhost:9001/docs/llm/factory
curl http://localhost:9001/docs/v1/responses
curl http://localhost:9001/docs/mcp
curl -X GET http://localhost:9001/api/describe/users \
  -H "Authorization: Bearer <token>"
```

## Notes for agents

- Read the route docs before calling the API.
- Prefer the documented route paths over guessing.
- Use `/docs/*` as the canonical navigation surface.
- Use `/docs/mcp` before assuming tool names or session behavior for the MCP server.
- Treat the root document as the shortest path to the route docs.