Stargate REST API reference

Abstract
The Stargate REST API provides CRUD operations on table data managed by Stargate.

1. Endpoints

1.1. Auth

1.1.1. createToken

POST /v1/auth

Create an auth token

Description
Parameters
Body Parameter
Name Description Required Default Pattern

Credentials

Credentials

X
Return Type

AuthTokenResponse

Content Type

  • application/json

  • /

Responses
Table 1. http response codes
Code Message Datatype

201

Created

AuthTokenResponse

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.2. Data

1.2.1. addRows

POST /v2/keyspaces/{keyspace-id}/{table-id}

Add rows

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null
Body Parameter
Name Description Required Default Pattern

request_body

[string]

X
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

[Map]

Content Type

  • application/json

  • /

Responses
Table 2. http response codes
Code Message Datatype

201

resource created

Map[[string]]

400

Bad Request

Error

401

Unauthorized

Error

409

Conflict

Error

500

Internal server error

Error
Samples

1.2.2. deleteRows

DELETE /v2/keyspaces/{keyspace-id}/{table-id}/{primary-key}

delete a row(s)

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

primary-key

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. </br> 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`

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

-

Content Type

  • /

Responses
Table 3. http response codes
Code Message Datatype

204

No Content

<<>>

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.2.3. getRows

GET /v2/keyspaces/{keyspace-id}/{table-id}/{primary-key}

get a row(s)

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

primary-key

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. </br> 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`

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

fields

URL escaped, comma delimited list of keys to include

-

null

page-size

restrict the number of returned items

-

null

page-state

move the cursor to a particular result

-

null

sort

keys to sort by [String]

-

null

raw

unwrap results

-

false
Return Type

[inline_response_200_3]

Content Type

  • application/json

  • /

Responses
Table 4. http response codes
Code Message Datatype

200

[inline_response_200_3]

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.2.4. replaceRows

PUT /v2/keyspaces/{keyspace-id}/{table-id}/{primary-key}

replace a row(s)

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

primary-key

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. </br> 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`

X

null
Body Parameter
Name Description Required Default Pattern

request_body

document [string]

X
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false
Return Type

[inline_response_200_4]

Content Type

  • application/json

  • /

Responses
Table 5. http response codes
Code Message Datatype

200

resource updated

[inline_response_200_4]

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.2.5. searchTable

GET /v2/keyspaces/{keyspace-id}/{table-id}

search a table

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

where

URL escaped 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

$ne

Not Equal To

$in

Contained In

$exists

A value is set for the key

$select

This matches a value for a key in the result of a different query

$dontSelect

Requires that a key’s value not match a value for a key in the result of a different query

$all

Contains all of the given values

$regex

Requires that a key’s value match a regular expression

$text

Performs a full text search on indexed fields

fields

URL escaped, comma delimited list of keys to include

-

null

page-size

restrict the number of returned items

-

null

page-state

move the cursor to a particular result

-

null

sort

keys to sort by [String]

-

null

raw

unwrap results

-

false
Return Type

[inline_response_200_3]

Content Type

  • application/json

  • /

Responses
Table 6. http response codes
Code Message Datatype

200

[inline_response_200_3]

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.2.6. updateRows

PATCH /v2/keyspaces/{keyspace-id}/{table-id}/{primary-key}

update part of a row(s)

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

primary-key

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. </br> 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`

X

null
Body Parameter
Name Description Required Default Pattern

request_body

document [string]

X
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false
Return Type

[inline_response_200_4]

Content Type

  • application/json

  • /

Responses
Table 7. http response codes
Code Message Datatype

200

resource updated

[inline_response_200_4]

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.3. Schemas

1.3.1. createColumn

POST /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns

create a column

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null
Body Parameter
Name Description Required Default Pattern

ColumnDefinition

ColumnDefinition

X
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

[inline_response_201]

Content Type

  • application/json

  • /

Responses
Table 8. http response codes
Code Message Datatype

201

resource created

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

409

Conflict

Error

500

Internal server error

Error
Samples

1.3.2. createKeyspace

POST /v2/schemas/keyspaces

create a keyspace

Description
Parameters
Body Parameter
Name Description Required Default Pattern

Keyspace

Keyspace

X
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

[inline_response_201]

Content Type

  • application/json

  • /

Responses
Table 9. http response codes
Code Message Datatype

201

resource created

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

409

Conflict

Error

500

Internal server error

Error
Samples

1.3.3. createTable

POST /v2/schemas/keyspaces/{keyspace-id}/tables

create a table

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null
Body Parameter
Name Description Required Default Pattern

TableAdd

TableAdd

X
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

[inline_response_201]

Content Type

  • application/json

  • /

Responses
Table 10. http response codes
Code Message Datatype

201

resource created

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

409

Conflict

Error

500

Internal server error

Error
Samples

1.3.4. deleteColumn

DELETE /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns/{column-id}

delete a column

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

column-id

column name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

-

Content Type

  • /

Responses
Table 11. http response codes
Code Message Datatype

204

No Content

<<>>

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.3.5. deleteKeyspace

DELETE /v2/schemas/keyspaces/{keyspace-id}

delete a keyspace

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

-

Content Type

  • /

Responses
Table 12. http response codes
Code Message Datatype

204

No Content

<<>>

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.3.6. deleteTable

DELETE /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}

delete a table

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

-

Content Type

  • /

Responses
Table 13. http response codes
Code Message Datatype

204

No Content

<<>>

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.3.7. getColumn

GET /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns/{column-id}

get a column

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

column-id

column name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false
Return Type

ColumnDefinition

Content Type

  • application/json

  • /

Responses
Table 14. http response codes
Code Message Datatype

200

ColumnDefinition

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error
Samples

1.3.8. getColumns

GET /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns

list columns

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false
Return Type

[inline_response_200_2]

Content Type

  • application/json

  • /

Responses
Table 15. http response codes
Code Message Datatype

200

[inline_response_200_2]

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error
Samples

1.3.9. getKeyspace

GET /v2/schemas/keyspaces/{keyspace-id}

get a keyspace

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false
Return Type

Keyspace

Content Type

  • application/json

  • /

Responses
Table 16. http response codes
Code Message Datatype

200

Keyspace

400

Bad Request

Error

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error
Samples

1.3.10. getKeyspaces

GET /v2/schemas/keyspaces

Return all keyspaces

Description

Retrieve all available keyspaces in the specific database.

Parameters
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false
Return Type

[inline_response_200]

Content Type

  • application/json

  • /

Responses
Table 17. http response codes
Code Message Datatype

200

[inline_response_200]

401

Unauthorized

Error

500

Internal server error

Error
Samples

1.3.11. getTable

GET /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}

get a table

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false
Return Type

Table

Content Type

  • application/json

  • /

Responses
Table 18. http response codes
Code Message Datatype

200

Table

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error
Samples

1.3.12. getTables

GET /v2/schemas/keyspaces/{keyspace-id}/tables

list tables

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false
Return Type

[inline_response_200_1]

Content Type

  • application/json

  • /

Responses
Table 19. http response codes
Code Message Datatype

200

[inline_response_200_1]

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error
Samples

1.3.13. replaceColumn

PUT /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns/{column-id}

replace a column definition

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

column-id

column name

X

null
Body Parameter
Name Description Required Default Pattern

ColumnDefinition

ColumnDefinition

X
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

[inline_response_201]

Content Type

  • application/json

  • /

Responses
Table 20. http response codes
Code Message Datatype

200

resource updated

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

404

Not Found

Error

409

Conflict

Error

500

Internal server error

Error
Samples

1.3.14. replaceTable

PUT /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}

replace a table definition, except for columns

Description
Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null
Body Parameter
Name Description Required Default Pattern

TableAdd

TableAdd

X
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null
Return Type

[inline_response_201]

Content Type

  • application/json

  • /

Responses
Table 21. http response codes
Code Message Datatype

200

resource updated

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

404

Not Found

Error

409

Conflict

Error

500

Internal server error

Error
Samples

2. Models

2.1. AuthTokenResponse

Field Name Required Type Description Format

authToken

String

2.2. ClusteringExpression

Order rows storage to make use of the on-disk sorting of columns. Specifying order can make query results more efficient.

Field Name Required Type Description Format

column

X

String

order

X

String

Enum: ASC, DESC,

2.3. ColumnDefinition

Field Name Required Type Description Format

name

X

String

Name for the column, which must be unique.

typeDefinition

X

String

The type of data allowed in the column.

Enum: ascii, text, varchar, tinyint, smallint, int, bigint, varint, decimal, float, double, date, DateRangeType, duration, time, timestamp, uuid, timeuuid, blob, boolean, counter, inet, PointType, LineStringType, PolygonType, frozen, list, map, set, tuple,

static

Boolean

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

2.4. Credentials

User credentials for authenticating

Field Name Required Type Description Format

username

X

String

Username

password

X

String

Password

2.5. Datacenter

Field Name Required Type Description Format

name

X

String

replicas

X

Integer

2.6. Error

A description of an error state

Field Name Required Type Description Format

description

String

A human readable description of the error state

code

Integer

The code referencing the error state

2.7. InlineResponse200

Field Name Required Type Description Format

data

List of Keyspace

2.8. InlineResponse2001

Field Name Required Type Description Format

data

List of Table

2.9. InlineResponse2002

Field Name Required Type Description Format

data

List of ColumnDefinition

2.10. InlineResponse2003

Field Name Required Type Description Format

data

List of [map]

count

Integer

2.11. InlineResponse2004

Field Name Required Type Description Format

data

Map of [string]

2.12. InlineResponse201

Field Name Required Type Description Format

name

String

2.13. Keyspace

Field Name Required Type Description Format

name

X

String

datacenters

List of Datacenter

2.14. PrimaryKey

Defines a column list for the primary key. Can be either a single column, compound primary key, or composite partition key. Provide multiple columns for the partition key to define a composite partition key.

Field Name Required Type Description Format

partitionKey

X

List of [string]

Name of the column or columns that constitute the partition key.

clusteringKey

List of [string]

Name of the column or columns that constitute the clustering key.

2.15. Table

Field Name Required Type Description Format

name

String

keyspace

String

columnDefinitions

List of ColumnDefinition

primaryKey

PrimaryKey

tableOptions

TableOptions

2.16. TableAdd

Field Name Required Type Description Format

name

X

String

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.

columnDefinitions

X

List of ColumnDefinition

primaryKey

X

PrimaryKey

tableOptions

TableOptions

2.17. TableOptions

Field Name Required Type Description Format

defaultTimeToLive

Integer

Defines the Time To Live (TTL), which determines the time period (in seconds) to expire data. If the value is >0, TTL is enabled for the entire table and an expiration timestamp is added to each column. The maximum value is 630720000 (20 years). A new TTL timestamp is calculated each time the data is updated and the row is removed after the data expires.

clusteringExpression

List of ClusteringExpression