The Tableland Validator API is organized around REST. You can leverage these APIs to read directly from tables and compose data across them, and make calls to learn information about the node itself. Keep in mind that a node listens to mainnet chains and testnet chains separately such that there are separate Base URLs for each respective environment.

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).

Base URLs

The following base URLs are supported:

Testnet chains ⇒ https://testnets.tableland.network/api/v1
Mainnet chains ⇒ https://tableland.network/api/v1

Endpoints

The following endpoints are available at the Base URL gateways above:

/query ⇒ Write a SQL read query and get table data.
/receipt/{chainId}/{transactionHash} ⇒ Retrieve on-chain transaction information regarding a table create or write query.
/tables/{chainId}/{tableId} ⇒ Get table metadata and information.
/health ⇒ Check if the validator is up and running.
/version ⇒ Check version information about the validator daemon.

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

transactionHash ⇒ Resultant on-chain transaction hash corresponding to a table’s creation or a write query.
chainId ⇒ Blockchain or L2 solution on which transactions are being sent; available chainId values can be found here.
tableId ⇒ The unique identifier assigned to the created table upon the contract minting the table as an ERC721 token.

Synopsis

This general API specification is used to automatically generate clients and backend services; it should be used as the primary source of truth for Validator APIs. This specification is a living document, and as such, may be updated over time. Proposals for the addition of API features and fixes may be submitted by the Tableland community over time. These proposals will be evaluated for technical feasibility, utility to the community, and longer-term sustainability.

In Tableland, Validators are the execution unit/actors of the protocol. They have the following responsibilities:

Listen to on-chain events to materialize Tableland-compliant SQL queries in a database engine (currently, SQLite by default).
Serve read-queries (e.g: SELECT * FROM foo_69_1) to the external world.
Serve state queries (e.g. list tables, get receipts, etc) to the external world.

Base URLs

query

See the Query Formatting section for how to transform the response, such as making it ERC721 compliant.

Query the network

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/query?statement=select%20%2A%20from%20healthbot_80001_1 \
  -H 'Accept: application/json'

`GET /query`

Returns the results of a SQL read query against the Tableland network

Parameters

Name	In	Type	Required	Description
statement	query	string	true	The SQL read query statement
format	query	string	false	The requested response format:
extract	query	boolean	false	Whether to extract the JSON object from the single property of the surrounding JSON object.
unwrap	query	boolean	false	Whether to unwrap the returned JSON objects from their surrounding array.

Detailed descriptions

format: The requested response format:

objects - Returns the query results as a JSON array of JSON objects.
table - Return the query results as a JSON object with columns and rows properties.

Enumerated Values

Parameter	Value
format	objects
format	table

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	Inline
400	Bad Request	Invalid query/statement value	None
404	Not Found	Row Not Found	None
429	Too Many Requests	Too Many Requests	None

Response Schema

This operation does not require authentication

receipt

Get information about transaction progress

Get transaction status

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/receipt/{chainId}/{transactionHash} \
  -H 'Accept: application/json'

`GET /receipt/{chainId}/{transactionHash}`

Returns the status of a given transaction receipt by hash

Parameters

Name	In	Type	Required	Description
chainId	path	integer(int32)	true	The parent chain to target
transactionHash	path	string	true	The transaction hash to request

Example responses

200 Response

{
  "table_id": "1",
  "transaction_hash": "0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b",
  "block_number": 27055540,
  "chain_id": 80001,
  "error": "The query statement is invalid",
  "error_event_idx": 1
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	TransactionReceipt
400	Bad Request	Invalid chain identifier or transaction hash format	None
404	Not Found	No transaction receipt found with the provided hash	None
429	Too Many Requests	Too Many Requests	None

This operation does not require authentication

tables

Access to table information

Get table information

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/tables/{chainId}/{tableId} \
  -H 'Accept: application/json'

`GET /tables/{chainId}/{tableId}`

Returns information about a single table, including schema information

Parameters

Name	In	Type	Required	Description
chainId	path	integer(int32)	true	The parent chain to target
tableId	path	string	true	Table identifier

Example responses

200 Response

{
  "name": "healthbot_5_1",
  "external_url": "https://testnet.tableland.network/tables/healthbot_5_1",
  "animation_url": "https://render.tableland.xyz/anim/?chain=1&id=1",
  "image": "https://render.tableland.xyz/healthbot_5_1",
  "attributes": {
    "display_type": "date",
    "trait_type": "created",
    "value": 1657113720
  },
  "schema": {
    "columns": [
      {
        "name": "id",
        "type": "integer",
        "constraints": [
          "NOT NULL",
          "PRIMARY KEY",
          "UNIQUE"
        ]
      }
    ],
    "table_constraints": [
      "PRIMARY KEY (id)"
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Table
400	Bad Request	Invalid chain or table identifier	None
404	Not Found	Table Not Found	None
429	Too Many Requests	Too Many Requests	None
500	Internal Server Error	Internal Server Error	None

This operation does not require authentication

health

Get health status

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/health

`GET /health`

Returns OK if the validator considers itself healthy.

Responses

Status	Meaning	Description	Schema
200	OK	The validator is healthy.	None

This operation does not require authentication

version

Get version information

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/version \
  -H 'Accept: application/json'

`GET /version`

Returns version information about the validator daemon.

Example responses

200 Response

{
  "version": 0,
  "git_commit": "79688910d4689dcc0991a0d8eb9d988200586d8f",
  "git_branch": "foo/experimentalfeature",
  "git_state": "dirty",
  "git_summary": "v1.2.3_dirty",
  "build_date": "2022-11-29T16:28:04Z",
  "binary_version": "v1.0.1"
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	VersionInfo

This operation does not require authentication

Schemas

Table

{
  "name": "healthbot_5_1",
  "external_url": "https://testnet.tableland.network/tables/healthbot_5_1",
  "animation_url": "https://render.tableland.xyz/anim/?chain=1&id=1",
  "image": "https://render.tableland.xyz/healthbot_5_1",
  "attributes": {
    "display_type": "date",
    "trait_type": "created",
    "value": 1657113720
  },
  "schema": {
    "columns": [
      {
        "name": "id",
        "type": "integer",
        "constraints": [
          "NOT NULL",
          "PRIMARY KEY",
          "UNIQUE"
        ]
      }
    ],
    "table_constraints": [
      "PRIMARY KEY (id)"
    ]
  }
}

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	none
external_url	string	false	none	none
animation_url	string	false	none	none
image	string	false	none	none
attributes	[object]	false	none	none
» display_type	string	false	none	The display type for marketplaces
» trait_type	string	false	none	The trait type for marketplaces
» value	object	false	none	The value of the property

oneOf

Name	Type	Required	Restrictions	Description
»» anonymous	string	false	none	none

xor

Name	Type	Required	Restrictions	Description
»» anonymous	number	false	none	none

xor

Name	Type	Required	Restrictions	Description
»» anonymous	integer	false	none	none

xor

Name	Type	Required	Restrictions	Description
»» anonymous	boolean	false	none	none

xor

Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none

continued

Name	Type	Required	Restrictions	Description
schema	Schema	false	none	none

TransactionReceipt

{
  "table_id": "1",
  "transaction_hash": "0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b",
  "block_number": 27055540,
  "chain_id": 80001,
  "error": "The query statement is invalid",
  "error_event_idx": 1
}

Properties

Name	Type	Required	Restrictions	Description
table_id	string	false	none	none
transaction_hash	string	false	none	none
block_number	integer(int64)	false	none	none
chain_id	integer(int32)	false	none	none
error	string	false	none	none
error_event_idx	integer(int32)	false	none	none

Schema

{
  "columns": [
    {
      "name": "id",
      "type": "integer",
      "constraints": [
        "NOT NULL",
        "PRIMARY KEY",
        "UNIQUE"
      ]
    }
  ],
  "table_constraints": [
    "PRIMARY KEY (id)"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
columns	[Column]	false	none	none
table_constraints	[string]	false	none	none

Column

{
  "name": "id",
  "type": "integer",
  "constraints": [
    "NOT NULL",
    "PRIMARY KEY",
    "UNIQUE"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	none
type	string	false	none	none
constraints	[string]	false	none	none

VersionInfo

{
  "version": 0,
  "git_commit": "79688910d4689dcc0991a0d8eb9d988200586d8f",
  "git_branch": "foo/experimentalfeature",
  "git_state": "dirty",
  "git_summary": "v1.2.3_dirty",
  "build_date": "2022-11-29T16:28:04Z",
  "binary_version": "v1.0.1"
}

Properties

Name	Type	Required	Restrictions	Description
version	integer(int32)	false	none	none
git_commit	string	false	none	none
git_branch	string	false	none	none
git_state	string	false	none	none
git_summary	string	false	none	none
build_date	string	false	none	none
binary_version	string	false	none	none

Query Formatting

Transform the /query endpoint response to a specific format (it only applies to this 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

Interactive Demo

Test out the Validator API yourself!

← Previous

CLI

SQL Specification