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

  • 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

List databases:

curl http://localhost:8080/api/databases \

-H "Authorization: Bearer <token>"

Create and rename:

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:

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:

curl "http://localhost:8080/api/atoms?limit=20" \

-H "Authorization: Bearer <token>" \

-H "X-Atomic-Database: <db-id>"

Exports

Start a markdown export for one database:

curl -X POST http://localhost:8080/api/databases/<db-id>/exports/markdown \

-H "Authorization: Bearer <token>"

Check job status:

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

  • 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.