DocumentationAPI Reference
DashboardContact

CapybaraDB API v0 Reference

Welcome to the CapybaraDB API v0 Reference. This documentation provides detailed information about the CapybaraDB REST API endpoints, request/response formats, and authentication methods.

Getting Started

The CapybaraDB API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://api.capybaradb.co/v0

Authentication

The CapybaraDB API uses API keys to authenticate requests. You can view and manage your API keys in the CapybaraDB Dashboard. API keys must be included in the Authorization header of all requests.

Authorization: Bearer YOUR_API_KEY

For more details on authentication, see the Authentication Guide.

Database and Collection Structure

CapybaraDB organizes data in a hierarchical structure:

  • Project: The top-level container for your data
  • Database: A logical grouping of collections within a project
  • Collection: A container for documents
  • Document: Individual JSON records that can contain standard JSON types and CapybaraDB's EmbJSON types

When making API requests, you'll need to specify the database ID (db_id) which is a combination of your project ID and database name in the format project_id_database_name.

Important: The db_id uses an underscore (_) as a separator between the project ID and database name. For example: my_project_my_database

URL Structure

API endpoints follow this general structure:

/v0/db/<db_id>/collection/<collection_name>/document/...

EmbJSON Types

CapybaraDB extends standard JSON with special types for embedding and vector operations:

  • EmbText: For text that should be embedded and indexed for semantic search
  • EmbImage: For images that should be embedded and indexed for visual search

For detailed information about EmbJSON types, please visit the EmbJSON Types documentation page. To learn about the supported embedding models for text and images, see the Supported LLM Modes page.

In JSON requests, these are represented as:

1{
2  "title": "Regular text field",
3  "description": {
4    "@embText": "This text will be embedded for semantic search"
5  },
6  "image": {
7    "@embImage": "https://example.com/image.jpg"
8  }
9}

API Endpoints

Documents

Insert, find, query, update, and delete documents in your collections.

EmbJSON Types

Detailed information about EmbText and EmbImage types for embedding and vector operations.

Error Handling

CapybaraDB uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with CapybaraDB's servers.

Error responses follow this format:

1{
2  "status": "error",
3  "code": 400,
4  "message": "Detailed error message"
5}

Need Help?

If you have any questions or need assistance with the CapybaraDB API, please don't hesitate to reach out to our support team at hello@capybaradb.co.