/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/request_recovery_code GET

Request a recovery code or link via email, in order to recover the token associated with an identity.

Accessible through the CLI as spacetime identity recover <email> <identity>.

Query Parameters

/database/confirm_recovery_code GET

Confirm a recovery code received via email following a /database/request_recovery_code GET request, and retrieve the identity's token.

Accessible through the CLI as spacetime identity recover <email> <identity>.

Query Parameters

On success, returns JSON in the form:

{
    "identity": string,
    "token": 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.