Get started with the Astra DevOps API

The DevOps API is a REST API that you can use for organization and database administration in Astra DB Classic.

Form DevOps API requests

DevOps API requests are typical RESTful API requests. You can use whichever tool you prefer to make these requests. The following example uses curl:

curl -sS -L -X METHOD "https://api.astra.datastax.com/v2/ENDPOINT_PATH" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{REQUEST_BODY}'

DevOps API requests include the following components:

METHOD: The request method, such as POST, GET, PUT, or DELETE.
ENDPOINT_PATH: The target endpoint, which can include path parameters or query parameters.

The endpoint path typically describes the action or object being targeted, for example:
- POST /v2/tokens generates an application token.
- POST /v2/databases/DATABASE_ID/secureBundleURL generates a URL to download a database’s Secure Connect Bundle (SCB).
APPLICATION_TOKEN: The authorization header requires an application token with sufficient permissions to authorize the desired operation.

For most DevOps API requests, the Organization Administrator role is more than sufficient. For automation and stricter access control, consider using other roles with narrower scopes. For more information, see the following:
REQUEST_BODY: A data body in the form of a JSON object, if required by the endpoint and method.

The body schema can vary significantly across endpoints, and different endpoints can use the same parameter name for different values. For example, name can refer to the name of a database, role, or organization, depending on the endpoint.

Export environment variables

As you use the DevOps API, you will frequently reuse common values, such as application tokens, database IDs, and organization IDs.

Store these values in environment variables to facilitate reuse in your scripts, simplify token rotation, and increase security by keeping sensitive information separate from your core application code. DataStax recommends that you follow industry best practices when storing sensitive values, such as application tokens.

You can use any method you prefer to set environment variables, for example:

export ASTRA_DB_APPLICATION_TOKEN=APPLICATION_TOKEN
export ASTRA_DB_ID=DATABASE_ID

For information about storing and using environment variables in scripts, see the documentation for your preferred language or operating system.

Optional curl arguments

The DevOps API curl examples throughout the Astra DB Classic documentation include some optional arguments, such as -s, -sS, and | jq. You can omit or modify these arguments as needed.

Filepaths assume *nix

Throughout the Astra DB Classic documentation, filepaths assume a *nix environment.

If you use Microsoft Windows, you might need to adjust the filepaths given in the examples.

DevOps API endpoints

The DevOps API provides endpoints for organization and database administration.

Access control endpoints

You can use the DevOps API to manage access to databases and other resources in your organization, including application tokens, users, roles, and IP access lists. For private endpoints and customer keys, see Private link and encryption endpoints.

Roles and users

You can use the DevOps API to manage roles and manage users in your Astra organizations, including:

Creating, editing, and deleting custom roles
Creating custom roles with more granular permissions than are available in the Astra Portal.
Adding and removing users
Changing users' assigned roles

Application tokens

You can use the DevOps API to manage application tokens, and you can get your organization ID from an application token.

Access lists

You can use the DevOps API to manage IP access lists for databases and the IP access list for the DevOps API.

Secure Connect Bundle (SCB)

You can use the DevOps API to download SCBs for your databases.

Database endpoints

Create and delete databases

Use the DevOps API to create databases and delete databases.

Get database information

Use the DevOps API to get information about one or more databases.

Get all database IDs

You can use the DevOps API List databases endpoint to get all database IDs at once:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"

Make sure the application token has View DB permission for all relevant databases. For example, the Organization Administrator role can view all databases within an Astra organization. If the supplied token doesn’t have permission to view a particular database, the response won’t include any information for that database.

Result

A successful response contains an array of database objects. In each object, the id field contains the database ID.

The following example is truncated for clarity.

[
  {
    "id": "FIRST_DB_ID",
    "orgId": "organizations/ORG_ID",
    "ownerId": "users/ADMIN_USER_ID",
    "info": { ... },
    "creationTime": "2012-11-01T22:08:41+00:00",
    "terminationTime": "2019-11-01T22:08:41+00:00",
    "status": "ACTIVE",
    "storage": { ... },
    "availableActions": [ ... ],
    ...
  },
  {
    "id": "SECOND_DB_ID",
    "orgId": "organizations/ORG_ID",
    "ownerId": "users/ADMIN_USER_ID",
    "info": { ... },
    "creationTime": "2012-11-01T22:08:41+00:00",
    "terminationTime": "2019-11-01T22:08:41+00:00",
    "status": "ACTIVE",
    "storage": { ... },
    "availableActions": [ ... ],
    ...
  }
]

Multi-region databases

Use the DevOps API to manage regions for multi-region databases.

Keyspaces

Use the DevOps API to create and delete keyspaces in your databases.

Resize

You can use the DevOps API to resize Astra DB Classic databases.

Private link and encryption endpoints

Private endpoints: Use the DevOps API to configure private endpoints for Astra DB databases.
Customer keys: Use the DevOps API to configure customer managed encryption keys.
VPC peering: You can use the DevOps API to configure VPC peering for Astra DB Classic databases with AWS, Azure, and Google Cloud.

Telemetry endpoints

You can use the DevOps API Telemetry endpoints to export database health metrics and stream Astra DB Classic audit logs.

Other DevOps API endpoints

Enterprise organization management: For information about DevOps API endpoints related to enterprise organization management, including creating organizations in an enterprise and getting enterprise usage reports, see Manage your Astra enterprise.
Astra DB Serverless databases: The DevOps API supports both Astra DB Classic and Serverless databases. Some endpoints are for Astra DB Serverless databases only, such as the Custom Domain endpoints. For information about these endpoints, see the DevOps API reference.

DevOps API status codes

The DevOps API can return the following status codes:

200 OK
201 Created
202 Accepted
400 Bad request
401 Unauthorized
403 Forbidden
404 Not found
409 Conflict
500 Server error

Error responses include additional information about the specific error conditions.

OpenAPI specification

DevOps API OpenAPI specification