API docs by Redocly

Stargate REST API reference (2.0.18)

Download OpenAPI specification:Download

URL: https://www.datastax.com/contact-us License: Apache 2.0 Terms of Service

The Stargate REST API exposes CRUD access to data stored in Astra DB Cassandra tables. See the documentation site for additional information.

data

DML operations

CQL Query

Execute a cql query directly

Authorizations:
Token
query Parameters
keyspaceQP
string
Example: keyspaceQP=cycling

Name of the keyspace to use for the request

page-size
integer <int32>
Example: page-size=10

Restrict the number of returned items

page-state
string

Cassandra page state, used for pagination on consecutive requests

raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Request Body schema: text/plain

CQL Query String

string\S

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "pageState": "string",
  • "data": [
    ]
}

Search a table

Search a table using a json query as defined in the where query parameter

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
where
required
object

JSON query using the following keys:

Key Operation
$lt Less Than
$lte Less Than Or Equal To
$gt Greater Than
$gte Greater Than Or Equal To
$eq Equal To
$ne Not Equal To
$in Contained In
$contains Contains the given element (for lists or sets) or value (for maps)
$containsKey Contains the given key (for maps)
$containsEntry Contains the given key/value entry (for maps)
$exists Returns the rows whose column (boolean type) value is true
fields
string
Example: fields=name,title

Comma delimited list of keys to include

page-size
integer <int32>
Example: page-size=10

Restrict the number of returned items

page-state
string

Cassandra page state, used for pagination on consecutive requests

raw
boolean

Whether to 'unwrap' results object (omit wrapper)

sort
object
Examples:
  • count=DESC - Single sorting column

JSON Object with key(s) to sort results by as keys and 'ASC' or 'DESC' as value

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add row

Add a row to a table in your database. If the new row has the same primary key as that of an existing row, the database processes it as an update to the existing row.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Request Body schema: application/json

Fields of the Row to create as JSON

string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{ }

Retrieve all rows

Get all rows from a table.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
fields
string
Example: fields=name,title

Comma delimited list of keys to include

page-size
integer <int32>
Example: page-size=10

Restrict the number of returned items

page-state
string

Cassandra page state, used for pagination on consecutive requests

raw
boolean

Whether to 'unwrap' results object (omit wrapper)

sort
object
Examples:
  • count=DESC - Single sorting column

JSON Object with key(s) to sort results by as keys and 'ASC' or 'DESC' as value

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get row(s)

Get rows from a table based on the primary key.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

primaryKey
required
Array of strings

Value from the primary key column for the table. Define composite keys by separating values with slashes (val1/val2...) in the order they were defined.
For example, if the composite key was defined as PRIMARY KEY(race_year, race_name) then the primary key in the path would be race_year/race_name

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
fields
string
Example: fields=name,title

Comma delimited list of keys to include

page-size
integer <int32>
Example: page-size=10

Restrict the number of returned items

page-state
string

Cassandra page state, used for pagination on consecutive requests

raw
boolean

Whether to 'unwrap' results object (omit wrapper)

sort
object
Examples:
  • count=DESC - Single sorting column

JSON Object with key(s) to sort results by as keys and 'ASC' or 'DESC' as value

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Replace row(s)

Update existing rows in a table.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

primaryKey
required
Array of strings

Value from the primary key column for the table. Define composite keys by separating values with slashes (val1/val2...) in the order they were defined.
For example, if the composite key was defined as PRIMARY KEY(race_year, race_name) then the primary key in the path would be race_year/race_name

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Request Body schema: application/json

Fields of the Row to update as JSON

string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "data": null
}

Delete row(s)

Delete one or more rows in a table

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

primaryKey
required
Array of strings

Value from the primary key column for the table. Define composite keys by separating values with slashes (val1/val2...) in the order they were defined.
For example, if the composite key was defined as PRIMARY KEY(race_year, race_name) then the primary key in the path would be race_year/race_name

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "description": "Request invalid: payload not provided."
}

Update part of a row(s)

Perform a partial update of one or more rows in a table

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

primaryKey
required
Array of strings

Value from the primary key column for the table. Define composite keys by separating values with slashes (val1/val2...) in the order they were defined.
For example, if the composite key was defined as PRIMARY KEY(race_year, race_name) then the primary key in the path would be race_year/race_name

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Request Body schema: application/json

Fields of the Row to patch as JSON

string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "data": null
}

schemas

DDL operations

Get all keyspaces

Retrieve all available keyspaces.

Authorizations:
Token
query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a keyspace

Create a new keyspace.

Authorizations:
Token
Request Body schema: application/json

A map representing a keyspace with SimpleStrategy or NetworkTopologyStrategy with default replicas of 1 and 3 respectively Simple:

{ "name": "killrvideo", "replicas": 1}

Network Topology:

{
  "name": "killrvideo",
   "datacenters":
      [
         { "name": "dc1", "replicas": 3 },
         { "name": "dc2", "replicas": 3 },
      ],
}
string\S

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{ }

Get a keyspace

Return a single keyspace specification.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "datacenters": [
    ]
}

Delete a keyspace

Delete a single keyspace.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}

Get all tables

Retrieve all tables in a specific keyspace.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a table

Add a table in a specific keyspace.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

Request Body schema: application/json

Table definition as JSON

name
required
string\S

The name of the table to add.

object

The primary key definition of the table, consisting of partition and clustering keys.

Array of objects (ColumnDefinition)

Definition of columns that belong to the table to be added.

ifNotExists
boolean

Determines whether to create a new table if a table with the same name exists. Attempting to create an existing table returns an error unless this option is true.

object

The set of table options to apply to the table when creating.

Responses

Request samples

Content type
application/json
{
  • "name": "cycling_events",
  • "primaryKey": {
    },
  • "columnDefinitions": [
    ],
  • "ifNotExists": true,
  • "tableOptions": {
    }
}

Response samples

Content type
application/json
{ }

Get a table

Retrieve data for a single table in a specific keyspace.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Responses

Response samples

Content type
application/json
{
  • "name": "cycling_events",
  • "keyspace": "cycling",
  • "columnDefinitions": [
    ],
  • "primaryKey": {
    },
  • "tableOptions": {
    }
}

Replace a table definition

Update a single table definition, except for columns, in a keyspace.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Request Body schema: application/json

Table update definition as JSON

name
required
string\S

The name of the table to add.

object

The primary key definition of the table, consisting of partition and clustering keys.

Array of objects (ColumnDefinition)

Definition of columns that belong to the table to be added.

ifNotExists
boolean

Determines whether to create a new table if a table with the same name exists. Attempting to create an existing table returns an error unless this option is true.

object

The set of table options to apply to the table when creating.

Responses

Request samples

Content type
application/json
{
  • "name": "cycling_events",
  • "primaryKey": {
    },
  • "columnDefinitions": [
    ],
  • "ifNotExists": true,
  • "tableOptions": {
    }
}

Response samples

Content type
application/json
{ }

Delete a table

Delete a single table in the specified keyspace.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}

Get all columns

Return all columns for a specified table.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a column

Add a single column to a table.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Request Body schema: application/json

Column definition as JSON

name
required
string\S

Name for the column, which must be unique.

typeDefinition
required
string

The type of data allowed in the column.

static
boolean
Default: false

Denotes whether the column is shared by all rows of a partition.

Responses

Request samples

Content type
application/json
{
  • "name": "emailaddress",
  • "typeDefinition": "text",
  • "static": false
}

Response samples

Content type
application/json
{ }

Get a column

Return a single column specification in a specific table.

Authorizations:
Token
path Parameters
columnName
required
string\S
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Responses

Response samples

Content type
application/json
{
  • "name": "emailaddress",
  • "typeDefinition": "text",
  • "static": false
}

Update a column

Update a single column in a specific table

Authorizations:
Token
path Parameters
columnName
required
string\S
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Request Body schema: application/json
name
required
string\S

Name for the column, which must be unique.

typeDefinition
required
string

The type of data allowed in the column.

static
boolean
Default: false

Denotes whether the column is shared by all rows of a partition.

Responses

Request samples

Content type
application/json
{
  • "name": "emailaddress",
  • "typeDefinition": "text",
  • "static": false
}

Response samples

Content type
application/json
{ }

Delete a column

Delete a single column in a specific table.

Authorizations:
Token
path Parameters
columnName
required
string\S
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}

Get all indexes for a given table

Get all indexes for a given table

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Responses

Response samples

Content type
application/json
{ }

Add an index to a table's column

Add an index to a single column of a table.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

Request Body schema: application/json

Index definition as JSON

column
required
string\S

Column name

name
string

Optional index name. If no name is specified, Cassandra names the index: table_name_column_name_idx.

type
string

A custom index class name or classpath.

kind
string
Enum: "KEYS" "VALUES" "ENTRIES" "FULL"

The kind (ENTRIES, KEY, VALUES, FULL) of an index

object

Options passed to a custom index

ifNotExists
boolean

Determines whether to create a new index if an index with the same name exists. Attempting to create an existing index returns an error unless this option is true.

Responses

Request samples

Content type
application/json
{
  • "column": "string",
  • "name": "string",
  • "type": "string",
  • "kind": "KEYS",
  • "options": {
    },
  • "ifNotExists": true
}

Response samples

Content type
application/json
{ }

Drop an index from keyspace

Drop an index

Authorizations:
Token
path Parameters
indexName
required
string\S
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

tableName
required
string
Example: cycling_events

Name of the table to use for the request

query Parameters
If the index doesn't exist drop will throw an error unless this query param is set to true
boolean

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "description": "Request invalid: payload not provided."
}

Get all user defined types (UDT).

Retrieve all user defined types (UDT) in a specific keyspace.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update an User Defined type (UDT)

Update an user defined type (UDT) adding or renaming fields.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

Request Body schema: application/json

Type definition as JSON

name
required
string\S

User Defined Type name

Array of objects (UserDefinedTypeField)

User Defined Type fields to add

Array of objects (UserDefinedTypeFieldRename)

User Defined Type fields to rename

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "addFields": [
    ],
  • "renameFields": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}

Create an user defined type (UDT)

Add an user defined type (udt) in a specific keyspace.

Authorizations:
Token
path Parameters
keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

Request Body schema: application/json

Type definition as JSON

string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{ }

Get an user defined type (UDT) from its identifier

Retrieve data for a single table in a specific keyspace

Authorizations:
Token
path Parameters
typeName
required
string\S

Name of the type to find

keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

query Parameters
raw
boolean

Whether to 'unwrap' results object (omit wrapper)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "keyspace": "string",
  • "fields": [
    ]
}

Delete an User Defined type (UDT)

Delete a single user defined type (UDT) in the specified keyspace.

Authorizations:
Token
path Parameters
typeName
required
string\S

Name of the type to delete

keyspaceName
required
string
Example: cycling

Name of the keyspace to use for the request

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}

Health Resource

/health

Responses