Name	Name	Last commit message	Last commit date
parent directory ..
Header.md	Header.md
README.md	README.md
Specification.md	Specification.md
tableland-openapi-spec.yaml	tableland-openapi-spec.yaml

Tableland Validator API Specification

Author(s): @jsign, @carsonfarmer, @brunocalza

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.

Query the network
Query the network (POST)
Get transaction status
Get table information
Get health status
Get version information
Schemas

Tableland Validator - OpenAPI 3.0 v1.1.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

In Tableland, Validators are the execution unit/actors of the protocol. They have the following responsibilities: - Listen to onchain 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.

In the 1.0.0 release of the Tableland Validator API, we’ve switched to a design first approach! You can now help us improve the API whether it’s by making changes to the definition itself or to the code. That way, with time, we can improve the API in general, and expose some of the new features in OAS3.

The API includes the following endpoints: - /health: Returns OK if the validator considers itself healthy. - /version: Returns version information about the validator daemon. - /query: Returns the results of a SQL read query against the Tableland network. - /receipt/{chainId}/{transactionHash}: Returns the status of a given transaction receipt by hash. - /tables/{chainId}/{tableId}: Returns information about a single table, including schema information.

Base URLs:

query

Query the Tableland network

Find out more about queries

Query the network

Code samples

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/query?statement=select%20%2A%20from%20healthbot_80002_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

Query the network (POST)

Code samples

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

POST /query

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

Body parameter

{
  "statement": "select * from healthbot_80002_1",
  "params": [
    1,
    "hello",
    null,
    true
  ],
  "format": "objects",
  "extract": false,
  "unwrap": false
}

Parameters

Name	In	Type	Required	Description
body	body	Query	true	A JSON containing the statement and additional options

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

Find out more about receipts

Get transaction status

Code samples

# 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",
  "table_ids": [
    "1",
    "2"
  ],
  "transaction_hash": "0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b",
  "block_number": 27055540,
  "chain_id": 80002,
  "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

Find out more about tables

Get table information

Code samples

# 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_80002_1",
  "external_url": "https://testnets.tableland.network/api/v1/tables/80002/1",
  "animation_url": "https://tables.testnets.tableland.xyz/80002/1.html",
  "image": "https://tables.testnets.tableland.xyz/80002/1.svg",
  "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

Code samples

# 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

Code samples

# 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

{
  "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_80002_1",
  "external_url": "https://testnets.tableland.network/api/v1/tables/80002/1",
  "animation_url": "https://tables.testnets.tableland.xyz/80002/1.html",
  "image": "https://tables.testnets.tableland.xyz/80002/1.svg",
  "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",
  "table_ids": [
    "1",
    "2"
  ],
  "transaction_hash": "0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b",
  "block_number": 27055540,
  "chain_id": 80002,
  "error": "The query statement is invalid",
  "error_event_idx": 1
}

Properties

Name	Type	Required	Restrictions	Description
table_id	string	false	none	This field is deprecated
table_ids	[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

{
  "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
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

{
  "statement": "select * from healthbot_80002_1",
  "params": [
    1,
    "hello",
    null,
    true
  ],
  "format": "objects",
  "extract": false,
  "unwrap": false
}

Properties

Name	Type	Required	Restrictions	Description
statement	string	false	none	The SQL read query statement
params	[oneOf]	false	none	The values of query parameters

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

continued

Name	Type	Required	Restrictions	Description
format	string	false	none	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.
extract	boolean	false	none	Whether to extract the JSON object from the single property of the surrounding JSON object.
unwrap	boolean	false	none	Whether to unwrap the returned JSON objects from their surrounding array.

Files

validator

Directory actions

More options

Directory actions

More options

Latest commit

History

validator

Folders and files

parent directory

README.md

Tableland Validator API Specification

Synopsis

Table of Contents

Tableland Validator - OpenAPI 3.0 v1.1.0

query

Query the network

Parameters

Detailed descriptions

Enumerated Values

Responses

Response Schema

Query the network (POST)

Parameters

Responses

Response Schema

receipt

Get transaction status

Parameters

Responses

tables

Get table information

Parameters

Responses

health

Get health status

Responses

version

Get version information

Responses

Schemas

Table

Properties

TransactionReceipt

Properties

Schema

Properties

Column

Properties

VersionInfo

Properties

Query

Properties