`/database` HTTP API

The HTTP endpoints in /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

`/database/dns/:name GET`

Look up a database's address by its name.

Accessible through the CLI as spacetime dns lookup <name>.

Parameters

Returns

If a database with that name exists, returns JSON in the form:

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

If no database with that name exists, returns JSON in the form:

{ "Failure": {
    "domain": string
} } 
    

`/database/reverse_dns/:address GET`

Look up a database's name by its address.

Accessible through the CLI as spacetime dns reverse-lookup <address>.

Parameters

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.

`/database/set_name GET`

Set the name associated with a database.

Accessible through the CLI as spacetime dns set-name <domain> <address>.

Query Parameters

Required Headers

Returns

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

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

If the top-level domain is not registered, and register_tld was not specified, returns JSON in the form:

{ "TldNotRegistered": {
    "domain": string
} } 
    

If the top-level domain is registered, but the identity provided in the Authorization header does not have permission to insert into it, returns JSON in the form:

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

Note

Spacetime top-level domains are an upcoming feature, and are not fully implemented in SpacetimeDB 0.6. For now, database names should not contain slashes.

`/database/ping GET`

Does nothing and returns no data. Clients can send requests to this endpoint to determine whether they are able to connect to SpacetimeDB.

`/database/register_tld GET`

Register a new Spacetime top-level domain. A TLD is the part of a database name before the first /. For example, in the name tyler/bitcraft, the TLD is tyler. Each top-level domain is owned by at most one identity, and only the owner can publish databases with that TLD.

Note

Spacetime top-level domains are an upcoming feature, and are not fully implemented in SpacetimeDB 0.6. For now, database names should not contain slashes.

Accessible through the CLI as spacetime dns register-tld <tld>.

Query Parameters

Required Headers

Returns

If the domain is successfully registered, returns JSON in the form:

{ "Success": {
    "domain": string
} } 
    

If the domain is already registered to the caller, returns JSON in the form:

{ "AlreadyRegistered": {
    "domain": string
} } 
    

If the domain is already registered to another identity, returns JSON in the form:

{ "Unauthorized": {
    "domain": string
} } 
    

`/database/publish POST`

Publish a 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,
    "address": string,
    "op": "created" | "updated"
} } 
    

If the top-level domain for the requested name is not registered, returns JSON in the form:

{ "TldNotRegistered": {
    "domain": string
} } 
    

If the top-level domain for the requested name is registered, but the identity provided in the Authorization header does not have permission to insert into it, returns JSON in the form:

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

Note

Spacetime top-level domains are an upcoming feature, and are not fully implemented in SpacetimeDB 0.6. For now, database names should not contain slashes.

`/database/delete/:address POST`

Delete a database.

Accessible through the CLI as spacetime delete <address>.

Parameters

Required Headers

`/database/subscribe/:name_or_address GET`

Begin a WebSocket connection with a database.

Parameters

Required Headers

For more information about WebSocket headers, see RFC 6455.

Optional Headers

`/database/call/:name_or_address/:reducer POST`

Invoke a reducer in a database.

Parameters

Required Headers

Data

A JSON array of arguments to the reducer.

`/database/schema/:name_or_address GET`

Get a schema for a database.

Accessible through the CLI as spacetime describe <name_or_address>.

Parameters

Query Parameters

Returns

Returns a JSON object with two properties, "entities" and "typespace". For example, on the default module generated by spacetime init with expand=true, returns:

{
  "entities": {
    "Person": {
      "arity": 1,
      "schema": {
        "elements": [
          {
            "algebraic_type": {
              "Builtin": {
                "String": []
              }
            },
            "name": {
              "some": "name"
            }
          }
        ]
      },
      "type": "table"
    },
    "__init__": {
      "arity": 0,
      "schema": {
        "elements": [],
        "name": "__init__"
      },
      "type": "reducer"
    },
    "add": {
      "arity": 1,
      "schema": {
        "elements": [
          {
            "algebraic_type": {
              "Builtin": {
                "String": []
              }
            },
            "name": {
              "some": "name"
            }
          }
        ],
        "name": "add"
      },
      "type": "reducer"
    },
    "say_hello": {
      "arity": 0,
      "schema": {
        "elements": [],
        "name": "say_hello"
      },
      "type": "reducer"
    }
  },
  "typespace": [
    {
      "Product": {
        "elements": [
          {
            "algebraic_type": {
              "Builtin": {
                "String": []
              }
            },
            "name": {
              "some": "name"
            }
          }
        ]
      }
    }
  ]
} 
    

The "entities" will be an object whose keys are table and reducer names, and whose values are objects of the form:

{
    "arity": number,
    "type": "table" | "reducer",
    "schema"?: ProductType
} 
    

The "typespace" will be a JSON array of AlgebraicTypes referenced by the module. This can be used to resolve Ref types within the schema; the type { "Ref": n } refers to response["typespace"][n].

`/database/schema/:name_or_address/:entity_type/:entity GET`

Get a schema for a particular table or reducer in a database.

Accessible through the CLI as spacetime describe <name_or_address> <entity_type> <entity_name>.

Parameters

Query Parameters

Returns

Returns a single entity in the same format as in the "entities" returned by the /database/schema/:name_or_address GET endpoint:

{
    "arity": number,
    "type": "table" | "reducer",
    "schema"?: ProductType,
} 
    

`/database/info/:name_or_address GET`

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

Parameters

Returns

Returns JSON in the form:

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

`/database/logs/:name_or_address GET`

Retrieve logs from a database.

Accessible through the CLI as spacetime logs <name_or_address>.

Parameters

Query Parameters

Required Headers

Returns

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

`/database/sql/:name_or_address POST`

Run a SQL query against a database.

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

Parameters

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.