API Libraries > REST API

REST API

Rockset’s REST API allows for creating and managing all resources in Rockset. Each supported endpoint is documented below.

All endpoints are only accessible via https. The base URL of the Rockset API server is:

https://api.rs2.usw2.rockset.com

All requests must be authorized with a Rockset API key, which can be created in the Rockset console. The API key must be provided as ApiKey {api_key} in the Authorization request header. For example:

Authorization: ApiKey aB35kDjg931J5nsf4GjwMeErAVd832F7ahsW1S02kfZiab42s11TsfW5Sxt25asT

Debugging Error Codes

The REST API may return an error code if there is an error either on the user end or the Rockset end. Below are some debugging tips for common error codes.

Error 401: Unauthorized

You are not authenticated correctly. Check to make sure that your API key is correct.

Error 403: Forbidden

You do not have access to this content. Check to make sure you have the required permissions.

Error 404: Not Found

We did not find the resource you are requesting. Check to make sure the resource name is spelled correctly.

Error 5xx: Server Error

Internal Error. Unexpected condition encountered by the server. Please include the error text and description when contacting support.

Queries

QueryResponse Type

Attributes
Example object
  • resultsoptionalarray

    list of objects returned by the query

  • fieldsoptionalarray

    list of fields returned by the query

  • statsoptional

    meta information about the query

  • collectionsoptionalarray

    list of collections queried by the query

  • column_fieldsoptionalarray

    meta information about each column in the result set

  • Query

    Make a SQL query to Rockset.

    POST /v1/orgs/self/queries
    Arguments
    Example Request
    Example Response
    • sqloptionalobject

      details about the query

      Show child attributes

    Documents

    Delete Documents

    Delete documents from a collection in Rockset.

    DELETE /v1/orgs/self/ws/{workspace}/collections/{collection}/docs
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace

    • collectionrequiredstring(in path)

      name of the collection

    • datarequiredarray

      array of document IDs

      Show child attributes

    Add Documents

    Add documents to a collection in Rockset.

    POST /v1/orgs/self/ws/{workspace}/collections/{collection}/docs
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace

    • collectionrequiredstring(in path)

      name of the collection

    • datarequiredarray

      Array of JSON documents

    ApiKeys

    ApiKey Type

    API keys are used to authenticate requests to Rockset's API. An API key is tied to the user who creates it. A new API key can be created for each use case, with a maximum of 10 API keys per user.

    Attributes
    Example object
  • created_atoptionalstring

    ISO-8601 date

  • nameoptionalstring

    descriptive label

  • keyoptionalstring

    string of 64 alphanumeric characters

  • List API Keys

    List all API keys for the authenticated user.

    GET /v1/orgs/self/users/self/apikeys
    Example Request
    Example Response
    curl --request GET \
      --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/self/apikeys \
      -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

    Create API Key

    Create a new API key for the authenticated user.

    POST /v1/orgs/self/users/self/apikeys
    Arguments
    Example Request
    Example Response
    • namerequiredstring

      descriptive label

    Delete API Key

    Delete an API key for the authenticated user.

    DELETE /v1/orgs/self/users/self/apikeys/{name}
    Arguments
    Example Request
    Example Response
    • namerequiredstring(in path)

      name of the API key

    List API Keys for any user (admin only)

    List all API keys for any user (admin only).

    GET /v1/orgs/self/users/{user}/apikeys
    Arguments
    Example Request
    Example Response
    • userrequiredstring(in path)

    Create API Key for any user (admin only)

    Create a new API key for any user (admin only).

    POST /v1/orgs/self/users/{user}/apikeys
    Arguments
    Example Request
    Example Response
    • namerequiredstring

      descriptive label

    • userrequiredstring(in path)

    Delete API Key for any user (admin only)

    Delete an API key for any user (admin only).

    DELETE /v1/orgs/self/users/{user}/apikeys/{name}
    Arguments
    Example Request
    Example Response
    • namerequiredstring(in path)

      name of the API key

    • userrequiredstring(in path)

    Collections

    Collection Type

    Attributes
    Example object
  • created_atoptionalstring

    ISO-8601 date

  • created_byoptionalstring

    email of user who created the collection

  • nameoptionalstring

    unique identifer for collection, can contain alphanumeric or dash characters

  • descriptionoptionalstring

    text describing the collection

  • workspaceoptionalstring

    name of the workspace that the collection is in

  • statusoptionalstring

    current status of collection, one of: CREATED, READY, DELETED

  • sourcesoptionalarray

    list of sources from which collection ingests

  • statsoptional

    metrics about the collection

  • retention_secsoptionalinteger

    number of seconds after which data is purged based on event time

  • field_mappingsoptionalarray

    list of mappings applied on all documents in a collection

  • List Collections

    Retrieve all collections in an organization.

    GET /v1/orgs/self/collections
    Example Request
    Example Response
    curl --request GET \
      --url https://api.rs2.usw2.rockset.com/v1/orgs/self/collections \
      -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

    List Collections for Workspace

    Retrieve all collections in a workspace.

    GET /v1/orgs/self/ws/{workspace}/collections
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace

    Create Collection

    Create new collection in a workspace.

    POST /v1/orgs/self/ws/{workspace}/collections
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace

    • namerequiredstring

      unique identifer for collection, can contain alphanumeric or dash characters

    • descriptionoptionalstring

      text describing the collection

    • sourcesoptionalarray

      list of sources from which to ingest data

      Show child attributes

    • retention_secsoptionalinteger

      number of seconds after which data is purged, based on event time

    • event_time_infooptionalobject

      configuration for event data

      Show child attributes

    • field_mappingsoptionalarray

      list of mappings

      Show child attributes

    Delete Collection

    Delete a collection and all its documents from Rockset.

    DELETE /v1/orgs/self/ws/{workspace}/collections/{collection}
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace

    • collectionrequiredstring(in path)

      name of the collection

    Get Collection

    Get details about a collection.

    GET /v1/orgs/self/ws/{workspace}/collections/{collection}
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace

    • collectionrequiredstring(in path)

      name of the collection

    Integrations

    Integration Type

    Integrations that can be associated with data sources to create collections. Only one type of integration may be specified.

    Attributes
    Example object
  • created_atoptionalstring

    ISO-8601 date

  • created_byoptionalstring

    email of user who created the integration

  • nameoptionalstring

    descriptive label and unique identifier

  • descriptionoptionalstring

    longer explanation for the integration

  • s3optional

    Amazon S3 details, must have one of aws_access_key or aws_role

  • kinesisoptional

    Amazon Kinesis details, must have one of aws_access_key or aws_role

  • dynamodboptional

    Amazon DynamoDB details, must have one of aws_access_key or aws_role

  • redshiftoptional

    Amazon Redshift details

  • gcsoptional

    GCS details

  • segmentoptional

    Segment details

  • kafkaoptional

    Kafka details

  • List Integrations

    List all integrations for organization.

    GET /v1/orgs/self/integrations
    Example Request
    Example Response
    curl --request GET \
      --url https://api.rs2.usw2.rockset.com/v1/orgs/self/integrations \
      -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

    Create Integration

    Create a new integration with Rockset.

    POST /v1/orgs/self/integrations
    Arguments
    Example Request
    Example Response
    • namerequiredstring

      descriptive label

    • descriptionoptionalstring

      longer explanation for the integration

    • s3optionalobject

      Amazon S3 details, must have one of aws_access_key or aws_role

      Show child attributes

    • kinesisoptionalobject

      Amazon Kinesis details, must have one of aws_access_key or aws_role

      Show child attributes

    • dynamodboptionalobject

      Amazon DynamoDB details, must have one of aws_access_key or aws_role

      Show child attributes

    • redshiftoptionalobject

      Amazon Redshift details

      Show child attributes

    • gcsoptionalobject

      GCS details

      Show child attributes

    • segmentoptionalobject

      Show child attributes

    • kafkaoptionalobject

      Show child attributes

    Delete Integration

    Remove an integration.

    DELETE /v1/orgs/self/integrations/{integration}
    Arguments
    Example Request
    Example Response
    • integrationrequiredstring(in path)

      name of the integration

    Get Integration

    Get information about a single integration.

    GET /v1/orgs/self/integrations/{integration}
    Arguments
    Example Request
    Example Response
    • integrationrequiredstring(in path)

      name of the integration

    Organizations

    Organization Type

    An organization in Rockset is a container for users and collections.

    Attributes
    Example object
  • idoptionalstring

    unique identifier for the organization

  • created_atoptionalstring

    ISO-8601 date

  • display_nameoptionalstring

    name of the organization

  • company_nameoptionalstring

    name of the company

  • tieroptionalstring

    pricing tier

  • qcuoptionalinteger

    number of QCUs

  • stateoptionalstring

    org state

  • Get Organization

    Retrieve information about current organization.

    GET /v1/orgs/self
    Example Request
    Example Response
    curl --request GET \
      --url https://api.rs2.usw2.rockset.com/v1/orgs/self \
      -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

    Users

    User Type

    Attributes
    Example object
  • created_atoptionalstring

    ISO-8601 date

  • emailoptionalstring

    user email

  • first_nameoptionalstring

    user first name

  • last_nameoptionalstring

    user last name

  • rolesoptionalarray

    List of roles for a given user

  • stateoptionalstring

    state of user - NEW / ACTIVE

  • List Users

    Retrieve all users for an organization.

    GET /v1/orgs/self/users
    Example Request
    Example Response
    curl --request GET \
      --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users \
      -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

    Create User

    Create a new user for an organization.

    POST /v1/orgs/self/users
    Arguments
    Example Request
    Example Response
    • emailrequiredstring

      user email, must be unique

    • rolesoptionalarray

      List of roles for a given user

    Get Current User

    Retrieve currently active user.

    GET /v1/orgs/self/users/self
    Example Request
    Example Response
    curl --request GET \
      --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/self \
      -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

    Delete User

    Delete a user from an organization.

    DELETE /v1/orgs/self/users/{user}
    Arguments
    Example Request
    Example Response
    • userrequiredstring(in path)

      user email

    Workspaces

    Workspace Type

    Workspaces are organizational containers for collections.

    Attributes
    Example object
  • created_atoptionalstring

    ISO-8601 date of when workspace was created

  • created_byoptionalstring

    email of user who created the workspace

  • nameoptionalstring

    descriptive label and unique identifier

  • descriptionoptionalstring

    longer explanation for the workspace

  • collection_countoptionalinteger

    number of collections that are immediate children of workspace

  • List Workspaces

    List all workspaces.

    GET /v1/orgs/self/ws
    Example Request
    Example Response
    curl --request GET \
      --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws \
      -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

    Create Workspace

    Create a new workspace in your org.

    POST /v1/orgs/self/ws
    Arguments
    Example Request
    Example Response
    • namerequiredstring

      descriptive label and unique identifier

    • descriptionoptionalstring

      longer explanation for the workspace

    Delete Workspace

    Remove a workspace.

    DELETE /v1/orgs/self/ws/{workspace}
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace

    Get Workspace

    Get information about a single workspace.

    GET /v1/orgs/self/ws/{workspace}
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace

    List Workspaces

    List workspaces under given workspace.

    GET /v1/orgs/self/ws/{workspace}/ws
    Arguments
    Example Request
    Example Response
    • workspacerequiredstring(in path)

      name of the workspace