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.

Make an API Call with the Management API v4.0

  • Capella Operational
  • how-to
    +
    How to make an API call with the Management API v4.0.

    This page is for Capella. For Capella columnar, see Make an API Call with the Columnar Management API.

    Prerequisites

    In order make an API call with the Management API v4.0, you must have an API key that was created for the Management API v4.0. API keys for the Management API v3.0, formerly known as the Public API, are not compatible with the Management API v4.0.

    • The API key must have all the organization roles, project access, and project roles required to carry out the API call. Note that in the Management API v4.0 reference, each endpoint description lists the roles that are needed.

    • The API key must not have expired.

    • The API key must grant access to the Management API from your client’s IP address.

    • You must have saved the API key token when you created it.

    To create an API key for the Management API v4.0, see Get Started with the Management API v4.0.

    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:

    1. Use the following base URL.

      https://cloudapi.cloud.couchbase.com

    2. Pass the API key as a Bearer token using the HTTP Authorization header.

    3. 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 v4.0 uses an OpenAPI v3 specification. To download the Management API v4.0 specification, go to the Management API Reference and click Download.

    Examples

    List Organizations

    The following 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": "2020-07-22T12:38:57.437248116Z",
        "createdBy": "",
        "modifiedAt": "2023-07-25T14:33:56.13967014Z",
        "modifiedBy": "<redacted>",
        "version": 0
      },
      "description": "",
      "id": "<redacted>",
      "name": "cbc-dev",
      "preferences": {
        "sessionDuration": 7200
      }
    }
  ]
}

    Note that 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 Projects in an Organization

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

    • $ORGID is the organization ID.

    • $TOKEN is the API key token.

    The query parameters specify that each page of results should contain 3 projects, and that the request should return the first page of results.

    HTTP Request
    curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects?perPage=3&page=1" \
   -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>/projects?page=1&perPage=3",
      "last": "https://cloudapi.cloud.couchbase.com/v4/organizations/<ORGID>/projects?page=182&perPage=3",
      "next": "https://cloudapi.cloud.couchbase.com/v4/organizations/<ORGID>/projects?page=2&perPage=3",
      "previous": ""
    },
    "pages": {
      "last": 182,
      "next": 2,
      "page": 1,
      "perPage": 3,
      "previous": 0,
      "totalItems": 544
    }
  },
  "data": [
    {
      "audit": {
        "createdAt": "2023-08-07T10:58:04.844838072Z",
        "createdBy": "<redacted>",
        "modifiedAt": "2023-08-07T10:58:04.844855439Z",
        "modifiedBy": "<redacted>",
        "version": 1
      },
      "description": "",
      "id": "<redacted>",
      "name": "Project 1"
    },
    {
      "audit": {
        "createdAt": "2023-08-30T10:52:25.834748195Z",
        "createdBy": "<redacted>",
        "modifiedAt": "2023-08-30T10:52:25.83476043Z",
        "modifiedBy": "<redacted>",
        "version": 1
      },
      "description": "terraform testing",
      "id": "<redacted>",
      "name": "Project 2"
    },
    {
      "audit": {
        "createdAt": "2023-07-18T09:28:13.334086299Z",
        "createdBy": "",
        "modifiedAt": "0001-01-01T00:00:00Z",
        "modifiedBy": "",
        "version": 0
      },
      "description": "",
      "id": "<redacted>",
      "name": "Project 3"
    }
  ]
}

    Note that this response contains cursor information, showing the pagination of the results. For each project, audit information is provided, showing metadata for the project.

    Get Details of a Project

    The following request gets details about the specified project within the specified organization.

    • $ORGID is the organization ID.

    • $PROJECTID is the project ID.

    • $TOKEN is the API key token.

    HTTP Request
    curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID" \
   -H "Authorization: Bearer $TOKEN"

    The response is a JSON object similar to the following.

    HTTP Response
    {
  "audit": {
    "createdAt": "2023-03-14T15:12:25.671401417Z",
    "createdBy": "<redacted>",
    "modifiedAt": "0001-01-01T00:00:00Z",
    "modifiedBy": "",
    "version": 0
  },
  "description": "",
  "id": "<redacted>",
  "name": "Project 1"
}

    Update a Project

    The following request updates the specified project within the specified organization with a new description.

    • $ORGID is the organization ID.

    • $PROJECTID is the project ID.

    • $TOKEN is the API key token.

    HTTP Request
    curl -X PUT "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{"name": "Project 1", "description": "New description"}'

    In this example, only the description field is new. However, both the name and description fields are required, so the name field is supplied unchanged.

    Get the ETag for a Project

    The following request gets the ETag of the specified project within the specified organization.

    • $ORGID is the organization ID.

    • $PROJECTID is the project ID.

    • $TOKEN is the API key token.

    HTTP Request
    curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID" -i \
   -H "Authorization: Bearer $TOKEN" | grep etag

    Note that cURL also has an --etag-save option, which provides a convenient way of saving the ETag value. This example requests the protocol response headers instead, for clarity.

    The response is an ETag similar to the following.

    HTTP Response
    etag: 1

    You can use the ETag in a PUT request for concurrency control.

    Update a Project with Concurrency Control

    The following request checks whether the specified project within the specified organization has the expected ETag. If so, it updates the project with a new description.

    This enables you to make sure that you’re applying your update to the correct revision of the project, in cases where the project may be updated by other processes concurrently.

    • $ORGID is the organization ID.

    • $PROJECTID is the project ID.

    • $TOKEN is the API key token.

    HTTP Request
    curl -X PUT "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -H "If-Match: 1" \
   -d '{"name": "Project 1", "description": "Updated description"}'

    Note that cURL also has an --etag-compare option, which provides a convenient way of checking the ETag value. This example specifies the If-Match request header instead, for clarity.

    If the ETag of the project matches, the project is updated. If the ETag does not match, the request returns an error message similar to the following.

    HTTP Response
    {
  "code": 9000,
  "hint": "Please include the correct ETag version with the request.",
  "httpStatusCode": 412,
  "message": "Unable to process update. The 'ETag' provided does not match the current version of the document being requested to update."
}

    Next Steps