Get started with the Data API (HTTP)
You can use the Data API to programmatically interact with your databases.
The Data API provides an entry point for application development with Hyper-Converged Database (HCD) databases, including a variety of generative AI ecosystem integrations. It leverages the scalability, performance, and real-time indexing capabilities of Apache Cassandra® to support generative AI application development.
If you are new to the Data API, check out the quickstart for collections or the quickstart for tables for a demo of some common commands.
Get endpoint and token
The Data API requires your database’s API endpoint and an application token.
Get endpoint
The Data API endpoint for your database has the form: http://CLUSTER_HOST:GATEWAY_PORT
-
Replace CLUSTER_HOST with the external IP address of any node in your cluster. To find this, run
kubectl get nodes -o wideand use any of the values listed under "EXTERNAL-IP" in the output. -
Replace GATEWAY_PORT with the port number for your API gateway service. To find this, run
kubectl get svcand look for the "PORT(S)" value that corresponds toNodePort.
Generate token
The Data API requires an application token in the following format: Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD.
The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations.
You set a username and password when you create a cluster.
If you didn’t provide superuser credentials when you created your cluster, they were generated automatically and saved in a superuser secret named CLUSTER_NAME-superuser.
The CLUSTER_NAME-superuser secret contains both the username and the password.
Run the following commands to get the username and password in base64 format:
kubectl get secret CLUSTER_NAME-superuser -n PROJECT_SLUG -o jsonpath="{.data.username}" | xargskubectl get secret CLUSTER_NAME-superuser -n PROJECT_SLUG -o jsonpath="{.data.password}" | xargsUse the obtained values to create a token in the Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD format.
Use a client
DataStax provides several clients to facilitate interaction with the Data API. For details, see:
Use HTTP
You can interact directly with the Data API over HTTP using tools like curl or a library designed to make HTTP requests.
Data API HTTP requests always use the POST method, regardless of the actual CRUD operation performed by the command.
For a full list of commands, see the collection commands and table commands.
Most endpoints require you specify values:
| Name | Summary |
|---|---|
|
A database API endpoint URL. For information about how to find the endpoint, see Get endpoint and token. |
|
The target keyspace where you want to run the command. The target keyspace is also known as the working keyspace. |
|
The name of the collection or table where you want to run the command. |
|
An application token. The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations. For more information about how to generate a token, see Get endpoint and token. |
For example, use vector search and filters to find a document:
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"filter": {"$and": [
{"is_checked_out": false},
{"number_of_pages": {"$lt": 300}}
]},
"sort": { "$vector": [0.08, -0.62, 0.39] }
}
}'