There are a number of REST APIs that allow developers to retrieve all of their owned tables, tables owned by a specific address, basic table information, and even raw SQL queries in the URL itself. Plus, leverage query formatting for tailoring the API response data, such as for ERC721 compliance.

⚠️

Tableland has updated its REST APIs with some breaking changes. Please review the new documentation for the latest usage requirements—this “legacy” API will eventually be deprecated for the Validator API, but a number of features do carry over. New Validator API docs

Setup

There are no required prerequisites, but it may be helpful to become familiar with HTTPie and cURL since the examples provided use these. Also, jq is an optional tool to help pipe the output from the API calls to a more human readable, “pretty” format (e.g., curl <url> | jq).

Settings

Since all of the REST APIs are purely GET requests, there is no Authorization nor Content-Type header required; that is, reads are not a on-chain operation and are unauthenticated for those using the Tableland gateway. All responses have a Content-Type of type application/json.

Endpoints

The base URL is the following:

Testnets ⇒ https://testnets.tableland.network
Mainnets ⇒ https://tableland.network

And following endpoints are available via gateway(s):

Mainnets vs. Testnets Gateway

Be sure to use https://tableland.network on mainnets, and https://testnets.tableland.network on testnets.

At the protocol level, the Tableland network is separated such that nodes process and respond to SQL queries relative to each environment. If you were to use the testnets gateway on a mainnet chain / contract, this would lead to issues. The testnets gateway only queries tables that exist on testnet chains, whereas the tableland.network gateway only queries tables that exist on mainnet chains.

Definitions

Structure hash ⇒ Hash generated upon table creation that describes uniquely describes a table schema (i.e., identical schemas have equivalent structure hashes)
Transaction ⇒ Instructions corresponding an on-chain activity, represented as a hash
Controller ⇒ The owner of a table, note that this is not the same as a controller contract.
ChainId ⇒ Blockchain or L2 solution on which transactions are being sent; available chainId options can be found here.

Examples Format

The provided examples leverage a table named rest_api_80001_2580, deployed on the Polygon Mumbai testnet. It has a schema of id int, name text.

REST API Reference

`/chain/{chainId}/tables/controller/{address}`

Get all tables owned by an address for a given chain.

Path Parameters

chainId: <int> ⇒ The chainId corresponding to the chain that tables are deployed on
address: <string> ⇒ Address to be queried against for a list of owned tables

Request

N/A — no request body should be passed

Responses

200 (success)

<array> ⇒ Array of objects, each describing a single table

<object> (optional) ⇒ If no tables are controlled by the passed address, no objects are returned

controller: <string> ⇒ Table owner’s address, matching the address passed as a parameter
name: <string> ⇒ Table name in the format {prefix}_{chainId}_{tableId}
structure: <string> ⇒ Structure hash of the table’s schema
created_at: <string> ⇒ Time at which each validator created the table within its local store

400 (bad request)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)

500 (internal sever error)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

Failed to fetch tables ⇒ There was an issue with finding the requested chainId (i.e., chainId that is not supported)

Note: if an invalid address is passed, the status code will still be a 200 but returns an empty array

Examples

Request (using curl):

curl https://testnets.tableland.network/chain/80001/tables/controller/0x4D5286d81317E284Cd377cB98b478552Bbe641ae

Request (using httpie):

http --print=b https://testnets.tableland.network/chain/80001/tables/controller/0x4D5286d81317E284Cd377cB98b478552Bbe641ae

Responses (200 success):

[
	{
    "controller": "0x4D5286d81317E284Cd377cB98b478552Bbe641ae",
    "name": "rest_api_80001_2580",
    "structure": "466dc130f3b02cf995fb66f6a0bdbadc49d2a527c26ac328daddc3f7b8ef779c"
  }
]

`/chain/{chainID}/tables/{tableId}`

Get the ERC-721 compliant metadata associated with a table for a given chain

Path Parameters

chainId: <int> ⇒ The chainId corresponding to the chain that tables are deployed on
tableId: <int> ⇒ Unique identifier for the table on the corresponding chain (i.e., the tableId from {prefix}_{chainId}_{tableId})

Request

N/A — no request body should be passed

Responses

200 (success)

<object> ⇒ ERC-721 compliant metadata about the table

name: <string> ⇒ Name of the table in the format {prefix}_{chainId}_{tableId}
external_url: <string> ⇒ External URL to the table, which matches with the endpoint itself
image: <string> ⇒ A URL leading to a default Tableland image (the same for all tables)
attributes: <array>⇒ Array of metadata attributes

display_type: <string> ⇒ Defined as “date”
trait_type: <string> ⇒ Defined as “created”
value: <int> ⇒ A unix timestamp (seconds) value

400 (bad request)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)
Invalid id format ⇒ The passed id was an invalid format (e.g., wrong type)

500 (internal sever error)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

Failed to fetch metadata ⇒ The metadata for the given id could not be found (i.e., nonexistent table id or a chainId that is not supported)

Examples

Request (using curl):

curl https://testnets.tableland.network/chain/80001/tables/2580

Request (using httpie)

http --print=b https://testnets.tableland.network/chain/80001/tables/2580

Response (200 success):

{
  "name": "rest_api_80001_2580",
  "external_url": "https://testnets.tableland.network/chain/80001/tables/2580",
  "image": "https://render.tableland.xyz/80001/2580",
  "attributes": [
    {
      "display_type": "date",
      "trait_type": "created",
      "value": 1663808196
    }
  ]
}

`/chain/{chainId}/tables/structure/{hash}`

Get all tables with a matching table structure on a specific chain.

Path Parameters

chainId: <int> ⇒ The chainId corresponding to the chain that tables are deployed on
hash: <string> ⇒ Structure hash of a table

Request

N/A — no request body should be passed

Responses

200 (success)

<array> ⇒ Array of objects, each describing a single table

<object> (optional) ⇒ If no tables are controlled by the passed address, no objects are returned

controller: <string> ⇒ Table owner’s address, matching the address passed as a parameter
name: <string> ⇒ Table name in the format {prefix}_{chainId}_{tableId}
structure: <string> ⇒ Structure hash of the table’s schema

400 (bad request)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)

500 (internal sever error)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

Failed to fetch tables ⇒ There was an issue with finding the requested chainId (i.e., chainId that is not supported)

Note: if an invalid address is passed, the status code will still be a 200 but return an empty array

Examples

Request (using curl):

curl https://testnets.tableland.network/chain/80001/tables/structure/7d5cd636b3cb913155fe97a54af38383c2a7a94c98369616bdfe6409558cc57a

Request (using httpie):

http --print=b https://testnets.tableland.network/chain/80001/tables/structure/7d5cd636b3cb913155fe97a54af38383c2a7a94c98369616bdfe6409558cc57a

Responses (200 success):

[
  {
    "controller": "0x4D5286d81317E284Cd377cB98b478552Bbe641ae",
    "name": "rest_api_80001_2580",
    "structure": "466dc130f3b02cf995fb66f6a0bdbadc49d2a527c26ac328daddc3f7b8ef779c"
  },
  {
    "controller": "0x4D5286d81317E284Cd377cB98b478552Bbe641ae",
    "name": "_80001_2151",
    "structure": "466dc130f3b02cf995fb66f6a0bdbadc49d2a527c26ac328daddc3f7b8ef779c"
  }
]

`/query?s={readStatement}`

Get the response from a read query, set to the value of the s query string parameter.

For transforming the /query response, see the query formatting section below.

Path Parameters

readStatement: <string> ⇒ A URL encoded read query (see the examples for context)

Request

N/A — no request body should be passed

Responses

200 (success)

<object> ⇒ Object containing all results matching the read query statement

columns: <array> ⇒ Array of objects, each describing a corresponding table column

<object> ⇒ Object containing information about a single column

name: <string> ⇒ The name of the column

rows: <array> ⇒ Array of arrays, each describing the table columns

<array> ⇒ Array of row values, each separated by a comma and corresponding to the order of the objects in columns

400 (bad request)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)
Invalid id format ⇒ The passed id was an invalid format (e.g., wrong type)

500 (internal sever error)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

Failed to fetch metadata ⇒ The metadata for the given id could not be found (i.e., nonexistent table id or a chainId that is not supported)

Examples

ℹ️

It may be helpful to use a URL encoding tool for these examples.

For this example, take the statement SELECT * FROM rest_api_5_85, which translates to a URL encoded string: SELECT%20*%20FROM%20rest_api_5_85. Note that it must be further sanitized for the sake of using curl or httpie by also escaping characters. However, for demonstration purposes, it is possible to simply paste this query into most modern browsers, like so:

https://testnets.tableland.network/query?s=SELECT * FROM rest_api_80001_2580

# most browsers will automtically encode this as:

https://testnets.tableland.network/query?s=SELECT%20*%20FROM%20rest_api_80001_2580

Request (using curl):

curl https://testnets.tableland.network/query\?s\=SELECT%20\*%20FROM%20rest_api_80001_2580

Request (using httpie)

http --print=b https://testnets.tableland.network/query\?s\=select%20\*%20FROM%20rest_api_80001_2580

Responses (200 success):

[
    {
        "id": 0,
        "name": "Bobby Tables"
    }
]

`/schema/{tableName}`

Get the schema and constraints for a table.

Path Parameters

tableName: <string> ⇒ The tableName in the format {prefix}_{chainId}_{tableId}

Request

N/A — no request body should be passed

Responses

200 (success)

<object> ⇒ Object containing all results matching the read query statement

columns: <array> ⇒ Array of objects, each describing a corresponding table column

<object> ⇒ Object containing information about a single column

name: <string> ⇒ The name of the column
type: <integer> ⇒ The SQL data type, defined in the SQL Specification
constraints: <array> ⇒ Array of column constraints

<string> ⇒ Column constraints, such as PRIMARY KEY

table_contraints: <array> ⇒ Array constraints on the table as a whole

<string> ⇒ The table constraint

400 (bad request)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)
Invalid id format ⇒ The passed id was an invalid format (e.g., wrong type)

500 (internal sever error)

<object> ⇒ Object containing the error message

message: <string> ⇒ The error message

Failed to fetch metadata ⇒ The metadata for the given id could not be found (i.e., nonexistent table id or a chainId that is not supported)

Examples

Request (using curl):

curl https://testnets.tableland.network/schema/rest_api_80001_2580

Request (using httpie)

http --print=b https://testnets.tableland.network/schema/rest_api_80001_2580

Responses (200 success):

{
  "columns": [
    {
      "name": "id",
      "type": "int",
      "constraints": []
    },
    {
      "name": "name",
      "type": "text",
      "constraints": []
    }
  ],
  "table_constraints": []
}

Query Formatting

Transform the /query endpoint response to a specific format.

Only applies to the /query endpoint.

Adding Path Parameters

To leverage the query response formatting, add the options specified below as a query parameter. Namely, after using /query?, specify a parameter and its value using the syntax {parameter}={value} and append or prepend an ampersand &.

ERC721 Compliance

For example, a query used composing ERC721 compliant metadata (e.g., leveraging usage of json_object) should include unwrap=true&extract=true somewhere in the query string, either at the beginning or the end:

/query?unwrap=true&extract=true&s={readStatement}
/query?s={readStatement}&unwrap=true&extract=true

Parameters

`output`

Specify the JSON response’s shape and style.

objects (default) A top-level array that contains objects, where each object is a key-value pair of column name to row value. Note the word is plural, not singular.

table A top-level object that contains the keys columns and rows. The columns is an array of column objects, and the rows field is an array of row arrays.

`unwrap`

Instead of putting objects in a JSON array, unwrap them and use new line delimited JSON Lines. Defaults to false

Only applies to output=objects.

`extract`

Whether or not to extract single column result values and use those as the results in the response. Defaults to false.

Only applies to output=objects.

`json_strings`

Whether or not to leave JSON strings as strings in query results or transform them to actual JSON data. Defaults to false.

Basic Examples

The following examples leverage the table rest_api_80001_2580. Each example, unless otherwise specified, is using the default values noted above.

`output`

objects

output=objects

[
    {
        "id": 0,
        "name": "Bobby Tables"
    }
]

table

output=table

{
  "columns": [
    {
      "name": "id"
    },
    {
      "name": "name"
    }
  ],
  "rows": [
    [
      0,
      "Bobby Tables"
    ]
  ]
}

`unwrap`

Only works with output=objects.

false

output=objects&unwrap=false

[
  {
    "id": 0,
    "name": "Bobby Tables"
  }
]

true

output=objects&unwrap=false

{
  "id": 0,
  "name": "Bobby Tables"
}

`extract`

Assuming the default, unwrap=false.

false

Only works with output=objects, and it’s only valid for a single column response (i.e., SELECT a single column). Below, we’re only selecting the id column from our table.

output=objects&extract=false

[
  {
    "id": 0
  }
]

true

output=objects&extract=true



[
  0
]

When using unwrap=true.

false

output=objects&unwrap=true&extract=false

{
  "id": 0
}

true

output=objects&unwrap=true&extract=true

← Previous

Validator API

SQL Specification