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 Astra DB Serverless databases, including a variety of generative AI ecosystem integrations like LangChain, LlamaIndex, and embedding providers. It leverages the scalability, performance, and real-time indexing capabilities of Apache Cassandra® to support generative AI application development.
|
The Data API is supported for Serverless (vector) and Serverless (non-vector) databases generally. However, vector and reranking functionalities aren’t compatible with all databases, tables, or collections. |
If you are new to the Data API, try 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 with sufficient permissions to perform the requested operations.
-
In the Astra Portal, click the name of the database that you want to use with the Data API.
-
In the header, or the Database Details section (Serverless (vector) databases only), copy the database’s API endpoint.
The default endpoint format is
https://DATABASE_ID-REGION.apps.astra.datastax.com. If you use custom domains, replaceastra.datastax.comwith your custom domain. -
Generate a token to authenticate to the Data API:
-
Serverless (vector) databases: Under Database Details, click Generate token, and then copy the token.
-
Serverless (non-vector) and Serverless (vector) databases: Click Connection details, click Generate Token, and then copy the token. The selected driver or client doesn’t change the generated token. Tokens aren’t bound to specific drivers or clients.
The generated token has a custom Database Administrator role that is scoped to the current database only. Alternatively, you can create application tokens with other roles.
-
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.
By default, the initial keyspace for Serverless (vector) databases is named |
|
The name of the collection or table where you want to run the command. |
|
An application token with sufficient permissions to perform the requested command on the specified database. |
For example, use vector search and filters to find a document:
curl -sS -L -X POST "API_ENDPOINT/api/json/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": { "$vectorize": "A thrilling story set in a futuristic world" }
}
}'Use the Data API console
When viewing a database in the Astra Portal, you can use the built-in API Console to run Data API commands without installing a client or writing a script.
The Data API console is a useful tool for exploring basic Data API commands. You can edit commands with the built-in text editor, run them on your database directly in the Astra Portal, or copy pre-generated snippets for use with the Data API clients and HTTP requests.
The Data API console has the following limitations:
-
Strictly scoped to the current database and one collection or table per command. To loop commands over multiple objects, you must run Data API commands outside of the Astra Portal.
-
Supports Data Manipulation Language (DML) operations only. The Data API console doesn’t provide access to DevOps API endpoints, including those supported by the Data API clients.
-
Pre-generated commands and code snippets don’t cover all possible Data API commands or parameters. For complete details about a particular command or parameter, see the Data API reference documentation.
The Data API console requires a user role with permission to view, read, and write to a given database.
