Make an API Call with AI Services APIs

how-to

How to make an API call with the Couchbase AI Services APIs.

This page is for Capella AI Services. It covers the AI Services features in the Management API, and the Model Service API. For more information about the Management API for Capella Operational features, see Make an API Call with the Management API.

Capella AI Services has different APIs that you can use. You can:

Make an API call with the Management API to manage Provider integrations, Workflows, AI Models, and Model Service API Keys.
Make an API call with Model Service API to send inference requests to your embedding models or Large Language Models (LLMs) and receive outputs.

Make an API Call with the Management API

Use the Management API to manage your AI Services.

Prerequisites

You have created an API key.
- The API key must have all the organization roles, project access, and project roles required to carry out the API call. In the Management API reference, each endpoint description lists the roles that are needed.
- The API key is not expired.
- You have added the IP address you want to connect from to your API key’s allowed IP addresses.
- You saved the API key token when you created it.

Make an API Call

You can use a client such as cURL or a native SDK call to make an API call with the Management API.

To make an API call:

Use the following base URL:
```
https://cloudapi.cloud.couchbase.com
```
Pass your API key as a Bearer token using the HTTP Authorization header.
If a request body is required, pass it in JSON format.

Alternatively, you can use a client such as Insomnia or Postman to explore the details of the REST API, generate code samples, and so on. The Management API uses an OpenAPI v3 specification. To download the Management API specification, go to the Management API Reference and click Download.

Examples

The following examples show different operations you can complete with the Management API:

List an API Key’s Organizations
List Deployed Models in an Organization
Get a Model’s Connection String
Create Model Service API Key for a Region

List an API Key’s Organizations

The following GET request lists all of the organizations available to the provided API key.

$TOKEN is the API key token.

HTTP Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations" \
   -H "Authorization: Bearer $TOKEN"

The response is a JSON object similar to the following. In this case, the provided API key is able to access a single organization.

HTTP Response

{
  "data": [
    {
      "audit": {
        "createdAt": "2025-10-02T16:34:44.604521691Z",
        "createdBy": "<USER_ID",
        "modifiedAt": "2025-10-02T16:34:44.604521691Z",
        "modifiedBy": "<USER_ID>",
        "version": 1
      },
      "description": "",
      "id": "<ORGID>",
      "name": "My Organization",
      "preferences": {
        "sessionDuration": 7200
      }
    }
  ]
}

The response includes the organization ID. You can use the organization ID for any further API calls in which {organization} is a path parameter.

List Deployed Models in an Organization

The following GET request lists all of the deployed models available to the provided API key within the specified organization.

$ORGID is the organization ID.
$TOKEN is the API key token.

HTTP Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/aiServices/models
   -H "Authorization: Bearer $TOKEN"

The response is a JSON object similar to the following.

HTTP Response

{
    "cursor": {
        "hrefs": {
            "first": "https://cloudapi.cloud.couchbase.com/v4/organizations/<ORGID>/aiServices/models?page=1&perPage=10",
            "last": "https://cloudapi.cloud.couchbase.com/v4/organizations/<ORGID>/aiServices/models?page=1&perPage=10",
            "next": "https://cloudapi.cloud.couchbase.com/v4/organizations/<ORGID>/aiServices/models?page=0&perPage=10",
            "previous": ""
        },
        "pages": {
            "last": 1,
            "next": 0,
            "page": 1,
            "perPage": 10,
            "previous": 0,
            "totalItems": 2
        }
    },
    "data": [
        {
            "model": {
                "actions": [
                    "pause",
                    "destroy",
                    "edit"
                ],
                "cloudConfig": {
                    "compute": {
                        "cpu": 4,
                        "gpuMemory": 48
                    },
                    "provider": "aws",
                    "region": "us-east-1"
                },
                "config": {
                    "catalogModelName": "mistralai/mistral-7b-instruct-v0.3",
                    "provider": "mistral",
                    "type": "text-generation"
                },
                "connectionString": "https://<MODEL_STRING_ID>.ai.couchbase.com",
                "id": "<MODELID",
                "name": "model-1",
                "status": "healthy"
            }
        },
        {
            "model": {
                "actions": [
                    "pause",
                    "destroy",
                    "edit"
                ],
                "cloudConfig": {
                    "compute": {
                        "cpu": 4,
                        "gpuMemory": 24
                    },
                    "provider": "aws",
                    "region": "us-east-1"
                },
                "config": {
                    "catalogModelName": "nvidia/llama-3.2-nv-embedqa-1b-v2",
                    "dimensions": 2048,
                    "provider": "nvidia",
                    "type": "embedding-generation"
                },
                "connectionString": "https://<MODEL_STRING_ID>.ai.couchbase.com",
                "id": "<MODELID>",
                "name": "model-2",
                "status": "healthy"
            }
        }
    ]
}

This response contains details about all the models, including their model type and respective {connectionString} URL.

Get a Model’s Connection String

The following GET request retrieves details about a specific model’s connection string. This connection string is the base URL required to use the Model Service API for this specific model.

$ORGID is the organization ID.
$MODELID is the model ID.
$TOKEN is the API key token.

HTTP Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/aiServices/models/$MODELID/connectionString" \
   -H "Authorization: Bearer $TOKEN"

The response is a JSON object similar to the following.

HTTP Response

{
    "connectionString": "https://<MODEL_STRING_ID>.ai.couchbase.com"
}

Create Model Service API Key for a Region

The following POST request creates a Model Service API Key for an AWS region within the specified organization. You need this Model Service API Key to access the Model Service API and use your AI model.

$ORGID is the organization ID.
$TOKEN is the API key token.

HTTP Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/aiServices/models/apiKeys" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
    "name": "model-api-key",
  "description": "API key for LLM",
  "expiry": 180,
  "allowedCIDRs": ["<ALLOWED_IP>"],
  "region": "us-east-1"
  }'

The response is an JSON similar to the following.

HTTP Response

{
    "id": "<API-KEY-ID>",
    "token": "<API-KEY-TOKEN>"
}

Make an API Call with the Model Service API

Use the Model Service API to provide inference requests to your hosted models.

Prerequisites

To make an API call with the Model Service API, you need:

A Model Service API key.
The model connection string.

Model Service API Key

A Model Service API key is only used for the Model Service API. Organizational API keys created for the Management API have different access and will not work for the Model Service API.

To use a Model Service API key to make a call to the Model Service API:

Configure it with the same region as your AI model.
Use a key that has not expired.
Add the IP address you want to connect from to your API key’s allowed IP addresses.
Save the API key token when you create it, as it cannot be retrieved later.

To create an API key for the Model Service API, see Generate Model Service API Keys.

Model Connection String

The Model Service API uses a model’s Model Endpoint as its base URL. This is also known as the model connection string in the Management API. The model connection string is unique to every AI model you deploy.

To get your model connection string:

Go to AI Services Models.
Find your model and copy the Model Endpoint.

To get your model connection string using the Management API, see Get a Model’s Connection String.

Make an API Call

You can use a client such as cURL or a native SDK call to make an API call with the Model Service API.

To make an API call with the Model Service API and a specific model:

Use your model’s connection string as the base URL:
```
https://<MODEL_STRING_ID>.ai.couchbase.com
```
Pass the Model Service API key as a Bearer token using the HTTP Authorization header.
If a request body is required, pass it in JSON format.

Alternatively, you can use a client such as Insomnia or Postman to explore the details of the REST API, generate code samples, and so on. The Model Service API uses an OpenAPI v3 specification. To download the Model Service API specification, go to the Model Service API Reference and click Download.

Examples

The following examples show different operations you can complete with the Model Service API:

Create Chat Conversation

Create Chat Conversation

The following POST request creates a model response for a given chat conversation with your specified LLM. To use your model, you need a Model Service API key in the same region as the model, along with its unique model connection string.

$MODEL_STRING is the base URL. This is the model connection string, also known as Model Endpoint in the Capella UI.
$TOKEN is the Model Service API key token.

HTTP Request

curl "$MODEL_STRING/v1/chat/completions \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
  "messages": [
    {
      "role": "user",
      "content": "What is Couchbase all about? Write a N1QL query to get top 250 documents in a sorted list of scope, inventory and collection, airlines"
    }
  ],
  "model": "meta-llama/Llama-3.1-8B-Instruct",
  "stream": false,
  "max_tokens": 100
}

The response is an JSON similar to the following.

HTTP Response

{
    "id": "<CHATID>",
    "object": "chat.completion",
    "created": 1759451545,
    "model": "mistralai/mistral-7b-instruct-v0.3",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Couchbase is a NoSQL document-oriented database that can be used for building fast and resilient applications, offering features like data durability, real-time insights, and flexible data modeling. It supports various programming languages and APIs, including N1QL (SQL-likequery language).\n\nIn your case, you want to retrieve the top 250 documents from a scope, inventory, and collection named \"airlines\" in a sorted order. Assuming you have"
            },
            "finish_reason": "length"
        }
    ],
    "usage": {
        "prompt_tokens": 38,
        "completion_tokens": 100,
        "total_tokens": 138
    }
}

Next Steps

For a full reference guide of the Management API, see Management API Reference.
For a full reference guide of the Model Service API, see Inference API Reference.
For a reference of the Management API errors, see Management API Error Messages .
For a reference of the AI Services Model Service API errors, see Model Service API Error Messages .