Difficulty: Intermediate
Estimated Time: 15 minutes

Astra offers a GraphQL API, which allows you to create and modify tables as well as insert, query and change data within the database. Let's take a look at this helpful Astra feature!

As a prerequisite, be sure to setup an Astra account and create a database as detailed in the Creating an Astra Database scenario. We'll be using that account, the database, and the table to work through this GraphQL scenario.

In this scenario we'll explore the GraphQL API. We'll create a table, insert some data and query the data. We'll use the Better Botz database we created when we set up our account. Onward...

Better Botz

ver 0.003

Code Complete

You're all set! To try out further GraphQL Queries check out a tool like GraphiQL. It will provide a means to add header information, the token, and issue GraphQL queries, mutations, and provide standard GraphQL autocompletion through introspection.


GraphiQL is available in multiple formats, such as an installable Electron App, and example embedding is available at Code Sandbox. GraphiQL is all open source at graphiql.

For more information and details on using the Astra GraphQL API read the documentation at astra.readme.io.

For further reading of the work with Better Botz, check out our articles we post regularly on the Better Botz Blog.

Please give this scenario a rating (click on the stars near the top).

Astra GraphQL

Step 1 of 6

Getting a Token to use the GraphQL API

In this first step, let's set up some environment variables. We'll use these variables in later steps.

Let's start with a variable that contains the Astra GraphQL endpoint URL. Copy and paste the following command into the terminal.

export GRAPHQL_URL=''

Now, get the GraphQL endpoint URL from the Astra website and paste it between the quotes.

Astra Dashboard

With the pasted URL in place, execute the export command.

We'll create variables for the database credentials. Copy and paste the following command into the terminal

export DB_USER=''

Now, enter your Astra database username between the single quotes and execute the command.

Copy and paste the following command into the terminal

export DB_PASSWORD=''

Enter your Astra database password between the single quotes and execute the command.

Next, we want to extract the base part of the URL and store it in an environment variable named $BASEURI. Execute this sed script to do that.

export BASEURI=$(echo $GRAPHQL_URL | sed 's/\.com.*/\.com/')

You can inspect the result of the command here.


The last environment variable we need is one that contains the database authorization token. We'll use the following command to retrieve the token and set the variable.

Want to know how this command works? This command looks complicated, so let's break it down for you.

There are actually three commands here that work together. The outer command has the following form and creates an environment variable. export TOKEN=<variable's value goes here>

There are two inner commands surrounded by $(), which causes the commands to execute and the result to be the value of the variable.

The first of the two inner commands is a cURL command to retrieve info from the Astra website. The second jq command parses the result of the cURL command and isolates the token value. The two inner commands have this form: curl \ --request POST \ --url ${BASEURI}/api/rest/v1/auth \ --header 'Content-Type: application/json' \ --data-raw '{"username":"DB_USER","password":"DB_PASS"}' \ | jq -r '.authToken'

Here's an explanation of the cURL command options:
  • --request POST causes cURL to issue and HTTP POST command
  • --url ${BASEURI}/api/rest/v1/auth specifies the target of the POST command
  • --header 'Content-Type: application/json' tells cURL to use JSON syntax
  • --data-raw '{"username":"${DB_USER}","password":"${DB_PASSWORD}"}' is the JSON containing the database credentials that cURL uses to access the token
export TOKEN=$(curl --request POST --url ${BASEURI}/api/rest/v1/auth --header 'Content-Type: application/json' --data-raw "{\"username\":\"${DB_USER}\",\"password\":\"${DB_PASSWORD}\"}" | jq -r '.authToken')

Now to check that the environment variables are set and available, run this command.

printf "${GREEN}Astra GraphQL URL is $GRAPHQL_URL${NC}\n"
printf "${GREEN}Base URI is $BASEURI${NC}\n"
printf "${GREEN}Token is $TOKEN${NC}\n"

Now, we're ready to get started!