Skip to content
Atomic

Multi-Database

Atomic can host multiple knowledge bases under one server process. A registry database stores shared metadata and API tokens, while each data database stores its own atoms, tags, chunks, embeddings, wiki articles, conversations, positions, feeds, and briefings.

Active vs Default Database

Section titled “Active vs Default Database”
  • Active database - the database used when a request does not specify a database.
  • Default database - the database the server should prefer as the default choice.
  • Explicit database - a request can target a database with X-Atomic-Database: <id> or ?db=<id>.

The web UI and iOS app can switch databases. Integrations should pass an explicit database when they should not depend on server active state.

API

Section titled “API”

List databases:

Terminal window
curl http://localhost:8080/api/databases \
  -H "Authorization: Bearer <token>"

Create and rename:

Terminal window
curl -X POST http://localhost:8080/api/databases \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Research"}'


curl -X PUT http://localhost:8080/api/databases/<db-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Research Archive"}'

Activate or set default:

Terminal window
curl -X PUT http://localhost:8080/api/databases/<db-id>/activate \
  -H "Authorization: Bearer <token>"


curl -X PUT http://localhost:8080/api/databases/<db-id>/default \
  -H "Authorization: Bearer <token>"

Target a request explicitly:

Terminal window
curl "http://localhost:8080/api/atoms?limit=20" \
  -H "Authorization: Bearer <token>" \
  -H "X-Atomic-Database: <db-id>"

Exports

Section titled “Exports”

Start a markdown export for one database:

Terminal window
curl -X POST http://localhost:8080/api/databases/<db-id>/exports/markdown \
  -H "Authorization: Bearer <token>"

Check job status:

Terminal window
curl http://localhost:8080/api/exports/<job-id> \
  -H "Authorization: Bearer <token>"

Completed jobs return a temporary download_path. The download token is short-lived, so fetch the artifact promptly.

Operational Notes

Section titled “Operational Notes”
  • API tokens are managed in the registry and can access databases unless your deployment adds its own network or proxy controls.
  • Background jobs such as feed polling and briefings run per database.
  • Per-database pipeline status is available at GET /api/embeddings/status/all.
  • The desktop app stores local databases in its application data directory; self-hosted SQLite deployments store them under the configured data directory.
Section titled “Related”