Bot Quickstart

This page is for automated agents that discover an AeorDB HTTP endpoint and need to understand how to use it safely.

Discovery

Most API routes require an API key exchanged for a bearer token:

curl -X POST "$AEORDB/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"<api-key>"}'

Use the returned token as:

Authorization: Bearer <token>

If auth is disabled for a development instance, authenticated routes may work without this header.

Purpose	Route
Health	`GET /system/health`
Stats	`GET /system/stats`
Read file	`GET /files/{path}`
Write file	`PUT /files/{path}`
List directory	`GET /files/{dir}/`
Query one subtree	`POST /files/query`
Search globally or by subtree	`POST /files/search`
Fetch many files or ranges	`POST /files/fetch`
Chunk upload check	`POST /blobs/check`
Upload chunk	`PUT /blobs/chunks/{hash}`
Commit uploaded chunks	`POST /blobs/commit`
Invoke plugin	`POST /plugins/{name}/invoke`
Events	`GET /system/events`

Search one folder:

{
  "path": "/docs/",
  "query": "how to",
  "limit": 20
}

Structured search:

{
  "path": "/",
  "where": {"field": "@extension", "op": "eq", "value": "md"},
  "limit": 100
}

Search with locators for follow-up range fetch:

{
  "path": "/docs/",
  "query": "database write pattern",
  "include_matches": true,
  "max_matches_per_result": 5,
  "snippet_chars": 240
}

Use returned fetch_hint, ranges, content_hash, and updated_at with POST /files/fetch to retrieve only the relevant parts of large files.

Use POST /files/fetch for batch reads and partial reads. Prefer range fetch after search hit locators instead of downloading large documents.

Treat AeorDB as a database, not a disposable file server.
Do not run repair, GC, import, export-over, or repeated restarts against a suspected corrupt original until evidence has been preserved.
If corruption is suspected, preserve the database file, hot files, lock file, and logs before mutation.
Prefer graceful shutdown with SIGTERM/Ctrl+C and wait for completion.
Avoid broad unbounded searches or full-file fetches when a scoped search or range fetch will do.

Start with: