Get started with the Data API (TypeScript)

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, replace astra.datastax.com with 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, including the TypeScript client, to facilitate interaction with the Data API.

Install the client

Update to Node version 18 or later if needed.
Update to TypeScript version 5 or later if needed. This is unnecessary if you are using JavaScript instead of TypeScript.
Install the latest version of the @datastax/astra-db-ts package.

For example:
```
npm install @datastax/astra-db-ts
```

Use the client to interact with data

In general, all scripts that use a client will do the following:

Instantiate a DataAPIClient object.

All Data API interactions through a client start with a DataAPIClient object.
Connect to a database.

Most Data API interactions through a client require you to connect to a database through a DataAPIClient object.
Perform CRUD operations.

For example, you can create a collection or table, insert data, and find data. For a full list of operations, see the collection commands and table commands.

Here’s an example of a simple client script. For a more detailed demo, see the quickstart for collections and the quickstart for tables.

import { DataAPIClient } from "@datastax/astra-db-ts";

// Instantiate the client
const client = new DataAPIClient();

// Connect to a database
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});

// Get an existing collection
const collection = database.collection("COLLECTION_NAME");

// Use vector search and filters to find a document
(async function () {
  const result = await collection.findOne(
    {
      $and: [{ is_checked_out: false }, { number_of_pages: { $lt: 300 } }],
    },
    { sort: { $vectorize: "A thrilling story set in a futuristic world" } },
  );

  console.log(result);
})();

You can also use the clients for database administration, such as creating databases and keyspaces. For more information, see Databases and keyspaces (TypeScript).

Use HTTP

Instead of using a client, you can make direct HTTP requests.

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.