Databases: Overview

Every database endpoint, the order to call them in, and what each is for.

Databases are physically isolated spaces for storing context. In most integrations you create a database once, wait for provisioning, then ingest and query inside it.

Endpoint references

Endpoint	Method	SDK method	Purpose	Async?
/databases	POST	databases.create	Create a new isolated workspace	Yes
/databases	DELETE	databases.delete	Permanently remove a database	Yes
/databases	GET	databases.list	List all databases for the organization	No
/databases/status	GET	databases.status	Check provisioning readiness	No
/databases/stats	GET	databases.stats	Row counts for a database	No
/databases/collections	GET	TypeScript: databases.collections Python: databases.collections	List active collections	No
/databases/collections	DELETE	TypeScript: databases.deleteCollection Python: databases.delete_collection	Permanently remove one collection	Yes
/databases/{database}/metadata-schema	PATCH	TypeScript: databases.updateMetadataSchema Python: databases.update_metadata_schema	Add metadata schema fields	No
/databases/{database}/metadata-schema	GET	TypeScript: databases.getMetadataSchema Python: databases.get_metadata_schema	Read the metadata schema	No

Typical call sequence

For a new database from scratch:

1. Create the database: POST /databases
2. Wait for provisioning: GET /databases/status until infra.ready_for_ingestion is true
3. Ingest content: POST /context/ingest
4. Wait for indexing: GET /context/status until sources are searchable
5. Retrieve context: POST /query
6. Inspect usage: GET /databases/stats
7. Delete: DELETE /databases

For routine operations on an existing database:

• GET /databases: list databases in the org
• GET /databases/collections: list active collections
• GET /databases/stats: row counts for knowledge and memories

Key concepts

• Database: A top-level isolated space. For example, you can dedicate one database to one enterprise customer.
• Collection: A group of content inside a database, created on the first write. For a company brain, one collection holds everything, and metadata filters and access control keep results apart. Use separate collections only for data that must never meet in one search, such as each person’s memories.
• Database Metadata & Schema: Structured fields defined at database creation to enable query-time filtering. You can add fields later with Update Metadata Schema.