Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Agent Memory APIs for Managed Deployments

  • concept
The Couchbase Capella Management API and the Agent Memory API are secure REST APIs that enable you to deploy Agent Memory servers and store and retrieve memory for your AI agents.

This page is for Agent Memory in Capella. It covers the Agent Memory features in the Management API, and the Agent Memory API. For more information about the Management API for Capella Operational features, see Manage Deployments with the Capella Operational Management API.

For Agent Memory in Capella, you can use REST APIs to deploy Agent Memory servers and store and retrieve memory. This includes:

You do not need any special tools, SDKs, or libraries to access the Management API or the Agent Memory API. Both of these APIs support off-the-shelf HTTP clients, such as Insomnia or Postman.

To get started with the APIs, create an API key and make an API call.

The Management API is not available for free tier operational clusters. Upgrade your account to manage deployments with the Management API.

The Management API

The Capella Management API is a secure, versioned REST API provided by Couchbase Capella that allows users to manage tasks for Couchbase operational clusters, App Services, and the AI Data Plane. For Agent Memory in Capella, this includes management tasks such as deploying Agent Memory servers and creating Agent Memory API keys.

For a full Management API reference guide, see Couchbase Capella Management API Reference.

Versioning

The Management API uses semantic versioning. The full version number consists of 3 parts: major.minor.patch.

An update to the Management API may be a non-versioned bug fix, a patch update, a minor update, or a major update. All major, minor, and patch updates increment the version number. Only non-versioned bug fixes do not change the version number as they resolve defects without altering functionality or adding new features.

New versions of the Management API, with some exceptions, are backward compatible, minimizing the effect on existing deployments. In most cases, you do not need to update your existing infrastructure when Couchbase releases a new version of the Management API. Features added in a new version of the Management API do not break existing deployments.

Exceptions to backward compatibility are as follows:

  • Critical security fixes. Couchbase marks a vulnerable version of the Management API as unsupported when it releases a version that fixes the vulnerability. In this case, you must plan to upgrade as soon as possible.

  • Fundamental architectural changes, when unavoidable.

Authentication and Authorization

The Management API uses API keys for authentication and authorization. They’re required for accessing endpoints exposed by the Management API.

Couchbase Capella associates API keys with roles and permissions. To access an endpoint, an API key must have the appropriate Capella roles. The Management API reference guide lists the roles required for each endpoint.

When you create an API key, you can configure an allowed IP address list. Every API key has an expiration date.

To authenticate a Management API call, pass the API key as a Bearer token in the HTTP Authorization header.

Concurrent Access and PUT Requests

To support concurrent requests, PUT requests support optimistic concurrency control, using If-Match headers in combination with HTTP ETags (entity tags). Exceptions are noted in the endpoint descriptions of the Management API reference page. A typical pattern is to do a GET request on a specified resource, which returns an ETag value. You can then include the ETag value in a PUT request to update the resource.

PUT requests ignore all fields in the body of the request that are not required. You can find the required fields for each PUT request in the Management API reference guide.

Auditing

All requests to the Management API are audited. All endpoints support Audit fields for audit purposes, except where noted in the Management API reference guide.

Lists are paginated.

Service Limits

Service limits set boundaries for managing clusters, App Services, and the Couchbase AI Data Plane with the Management API.

Long-Running Requests

The following long-running requests are rejected with error 504, Gateway Timeout:

  • Read requests taking longer than 90 seconds to process.

  • Write requests taking longer than 120 seconds to process.

Rate Limiting

Requests are limited to 100 requests per minute per API key.

Payload Size

Requests and response payloads are restricted to 18 MB.

The Agent Memory API

The Agent Memory API is a REST API for the Couchbase Agent Memory server. It allows your AI agents to store and retrieve persistent memory across user sessions.

With Agent Memory in Capella, Capella deploys and runs your Agent Memory server and connects it to your Capella operational cluster. For more information, see Deploy Managed Agent Memory.

For a full Agent Memory API reference guide, see Agent Memory API Reference.

Versioning

The Agent Memory API uses semantic versioning. The full version number consists of 3 parts: major.minor.patch.

An update to the API may be a non-versioned bug fix, a patch update, a minor update, or a major update. When a non-versioned bug fix releases, the version number is not updated. When a patch update, a minor update, or a major update releases, the version number also updates.

Endpoint paths do not include the version. To check the version of your Agent Memory server, call the GET /health endpoint.

For more information about changes between versions, see The Agent Memory API Change Log.

Authentication and Authorization

To access your server, you must have:

Agent Memory API Keys

Agent Memory API keys are different from the API keys required by the Management API. A Management API key gives access to your Capella organization, while an Agent Memory API key gives access to an Agent Memory server.

Each API key for the Agent Memory API has the following characteristics:

For more information about how to create Agent Memory API keys, see Agent Memory API Keys.

Access Levels

When you create an API key, you choose its access level:

Access Role Description

Read

ams_ro

Read-only access to the Agent Memory server. This includes the ability to search, list, and get memory.

Write

ams_rw

Read and write access to the Agent Memory server. Everything in Read, plus the ability to add, update, and delete memory, sessions, and users. This is the default access level.

Admin

ams_admin

Full access to the Agent Memory server, including administrative operations. Everything in Write, plus the ability to list users, manage custom prompts, and collect logs.

For more information about access levels, see Authentication.

Agent Memory Server Endpoint

The Agent Memory API uses a different base URL than the Management API. The base URL for the Agent Memory API is your Agent Memory server’s endpoint. Each Agent Memory server has a unique endpoint that uses HTTPS.

Capella labels the unique endpoint as:

  • network.endpoint in the Management REST API.

  • A server’s Endpoint in the Capella UI.

For more information about how to copy your Agent Memory server endpoint, see Agent Memory Server Endpoint.

IP Access

Each Agent Memory server has an allowed IP address list. Your Agent Memory server only accepts requests from IP addresses in its allowed IP address list. A new Agent Memory server has no allowed IP addresses, so it blocks all requests until you add at least 1.

For more information about how to add allowed IP addresses, see Allowed IP Addresses.

Request Logging

Every Agent Memory API response includes an X-Request-ID header. To identify your application in the server logs, pass an optional X-Client-ID header with each request.

Limits and Configuration

You set your Agent Memory server’s limits when you deploy the server. These limits include extraction rate limits, queue size, and timeouts. You cannot change the configuration of a deployed Agent Memory server. For more information, see Changing Your Configuration.

For more information about endpoint-specific limits, such as page sizes, see the Agent Memory API Reference.

See Also