`/v1/database` HTTP API

The HTTP endpoints in /v1/database allow clients to interact with Spacetime databases in a variety of ways, including retrieving information, creating and deleting databases, invoking reducers and evaluating SQL queries.

At a glance

`POST /v1/database`

Publish a new database with no name.

Accessible through the CLI as spacetime publish.

Required Headers

Data

A WebAssembly module in the binary format.

Returns

If the database was successfully published, returns JSON in the form:

{ "Success": {
    "database_identity": string,
    "op": "created" | "updated"
} } 
    

`POST /v1/database/:name_or_identity`

Publish to a database with the specified name or identity. If the name doesn't exist, creates a new database.

Accessible through the CLI as spacetime publish.

Query Parameters

Required Headers

Data

A WebAssembly module in the binary format.

Returns

If the database was successfully published, returns JSON in the form:

{ "Success": {
    "domain": null | string,
    "database_identity": string,
    "op": "created" | "updated"
} } 
    

If a database with the given name exists, but the identity provided in the Authorization header does not have permission to edit it, returns 401 UNAUTHORIZED along with JSON in the form:

{ "PermissionDenied": {
    "name": string
} } 
    

`GET /v1/database/:name_or_identity`

Get a database's identity, owner identity, host type, number of replicas and a hash of its WASM module.

Returns

Returns JSON in the form:

{
    "database_identity": string,
    "owner_identity": string,
    "host_type": "wasm",
    "initial_program": string
} 
    

`DELETE /v1/database/:name_or_identity`

Delete a database.

Accessible through the CLI as spacetime delete <identity>.

Required Headers

`GET /v1/database/:name_or_identity/names`

Get the names this datbase can be identified by.

Returns

Returns JSON in the form:

{ "names": array<string> } 
    

where <names> is a JSON array of strings, each of which is a name which refers to the database.

`POST /v1/database/:name_or_identity/names`

Add a new name for this database.

Required Headers

Data

Takes as the request body a string containing the new name of the database.

Returns

If the name was successfully set, returns JSON in the form:

{ "Success": {
    "domain": string,
    "database_result": string
} } 
    

If the new name already exists but the identity provided in the Authorization header does not have permission to edit it, returns JSON in the form:

{ "PermissionDenied": {
    "domain": string
} } 
    

`PUT /v1/database/:name_or_identity/names`

Set the list of names for this database.

Required Headers

Data

Takes as the request body a list of names, as a JSON array of strings.

Returns

If the name was successfully set, returns JSON in the form:

{ "Success": null } 
    

If any of the new names already exist but the identity provided in the Authorization header does not have permission to edit it, returns 401 UNAUTHORIZED along with JSON in the form:

{ "PermissionDenied": null } 
    

`GET /v1/database/:name_or_identity/identity`

Get the identity of a database.

Returns

Returns a hex string of the specified database's identity.

`GET /v1/database/:name_or_identity/subscribe`

Begin a WebSocket connection with a database.

Required Headers

For more information about WebSocket headers, see RFC 6455.

The SpacetimeDB binary WebSocket protocol, v1.bsatn.spacetimedb, encodes messages as well as reducer and row data using BSATN. Its messages are defined here.

The SpacetimeDB text WebSocket protocol, v1.json.spacetimedb, encodes messages according to the SATS-JSON format.

Optional Headers

`POST /v1/database/:name_or_identity/call/:reducer`

Invoke a reducer in a database.

Path parameters

Required Headers

Data

A JSON array of arguments to the reducer.

`GET /v1/database/:name_or_identity/schema`

Get a schema for a database.

Accessible through the CLI as spacetime describe <name_or_identity>.

Query Parameters

Returns

Returns a RawModuleDef in JSON form.

{
  "typespace": {
    "types": [
      {
        "Product": {
          "elements": [
            {
              "name": {
                "some": "name"
              },
              "algebraic_type": {
                "String": []
              }
            }
          ]
        }
      }
    ]
  },
  "tables": [
    {
      "name": "person",
      "product_type_ref": 0,
      "primary_key": [],
      "indexes": [],
      "constraints": [],
      "sequences": [],
      "schedule": {
        "none": []
      },
      "table_type": {
        "User": []
      },
      "table_access": {
        "Private": []
      }
    }
  ],
  "reducers": [
    {
      "name": "add",
      "params": {
        "elements": [
          {
            "name": {
              "some": "name"
            },
            "algebraic_type": {
              "String": []
            }
          }
        ]
      },
      "lifecycle": {
        "none": []
      }
    },
    {
      "name": "identity_connected",
      "params": {
        "elements": []
      },
      "lifecycle": {
        "some": {
          "OnConnect": []
        }
      }
    },
    {
      "name": "identity_disconnected",
      "params": {
        "elements": []
      },
      "lifecycle": {
        "some": {
          "OnDisconnect": []
        }
      }
    },
    {
      "name": "init",
      "params": {
        "elements": []
      },
      "lifecycle": {
        "some": {
          "Init": []
        }
      }
    },
    {
      "name": "say_hello",
      "params": {
        "elements": []
      },
      "lifecycle": {
        "none": []
      }
    }
  ],
  "types": [
    {
      "name": {
        "scope": [],
        "name": "Person"
      },
      "ty": 0,
      "custom_ordering": true
    }
  ],
  "misc_exports": [],
  "row_level_security": []
} 
    

`GET /v1/database/:name_or_identity/logs`

Retrieve logs from a database.

Accessible through the CLI as spacetime logs <name_or_identity>.

Query Parameters

Required Headers

Returns

Text, or streaming text if follow is supplied, containing log lines.

`POST /v1/database/:name_or_identity/sql`

Run a SQL query against a database.

Accessible through the CLI as spacetime sql <name_or_identity> <query>.

Required Headers

Data

SQL queries, separated by ;.

Returns

Returns a JSON array of statement results, each of which takes the form:

{
    "schema": ProductType,
    "rows": array
} 
    

The schema will be a JSON-encoded ProductType describing the type of the returned rows.

The rows will be an array of JSON-encoded ProductValues, each of which conforms to the schema.