TypeDB 3.0 is live! Get started for free.

TypeDB HTTP API Reference

Authorization

Sign in

Request an API token to authenticate against the rest of the API using user credentials. This token must be used as ACCESS_TOKEN for other protected methods.

Token required

No

Method

POST

URL

/v1/signin

Request body

 
{
    "username": string,
    "password": string
}

Request headers

None

Responses:

200: OK 
{
    "token": string
}
400: Bad Request

Possible causes:

  • Incorrectly formatted request

Response format:

{
    "code": string,
    "message": string
}
401: Unauthorized

Possible causes:

  • Invalid credentials

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/signin \
  --json '{"username": "USERNAME", "password": "PASSWORD"}'
import requests

url = "http://0.0.0.0:8000/v1/signin"
body = {
    "username": "USERNAME",
    "password": "PASSWORD"
}

response = requests.post(url, json=body)
use reqwest;
use serde::Serialize;

#[derive(Serialize)]
struct Signin {
    username: String,
    password: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let signin = Signin {
        username: "username".to_string(),
        password: "password".to_string(),
    };
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/signin")
        .json(&signin)
        .send().await;
    Ok(())
}

Example response:

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTc0NDYzNTI5NSwiaWF0IjoxNzQ0NjIwODk1fQ.WEhmBTAXI_qZUlAB7zw52LDGJhnqfNTXS63QDSZlqds"
}

Databases

Get databases

Get all databases present on the server.

Token required

Yes

Method

GET

URL

/v1/databases

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK 
{
    "databases": [
        {
            "name": string
        }
    ]
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request GET \
  --url http://0.0.0.0:8000/v1/databases \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/databases"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.get(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .get("http://0.0.0.0:8000/v1/databases")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Get database

Get a single database present on the server by name.

Token required

Yes

Method

GET

URL

/v1/databases/DATABASE_NAME

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK 
{
    "name": string
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request GET \
  --url http://0.0.0.0:8000/v1/databases/DATABASE_NAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/databases/DATABASE_NAME"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.get(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .get("http://0.0.0.0:8000/v1/databases/DATABASE_NAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Create database

Create a database on the server.

Token required

Yes

Method

POST

URL

/v1/databases/DATABASE_NAME

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK

No body.

400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/databases/DATABASE_NAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/databases/DATABASE_NAME"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.post(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/databases/DATABASE_NAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Delete database

Delete a database from the server by name.

Token required

Yes

Method

DELETE

URL

/v1/databases/DATABASE_NAME

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK

No body.

400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request DELETE \
  --url http://0.0.0.0:8000/v1/databases/DATABASE_NAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/databases/DATABASE_NAME"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.delete(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .delete("http://0.0.0.0:8000/v1/databases/DATABASE_NAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Users

Get users

Get all users present on the server.

Token required

Yes

Method

GET

URL

/v1/users

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK 
{
    "users": [
        {
            "username": string
        }
    ]
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request GET \
  --url http://0.0.0.0:8000/v1/users \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/users"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.get(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .get("http://0.0.0.0:8000/v1/users")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Get user

Get a single user present on the server by name.

Token required

Yes

Method

GET

URL

/v1/users/USERNAME

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK 
{
    "username": string
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request GET \
  --url http://0.0.0.0:8000/v1/users/USERNAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/users/USERNAME"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.get(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .get("http://0.0.0.0:8000/v1/users/USERNAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Create user

Create a new user on the server.

Token required

Yes

Method

POST

URL

/v1/users/USERNAME

Request body

 
{
    "password": string
}

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK

No body.

400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/users/USERNAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}' \
  --json '{"password": "PASSWORD"}'
import requests

url = "http://0.0.0.0:8000/v1/users/USERNAME"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}
body = {
    "password": "PASSWORD"
}

response = requests.post(url, headers=headers, json=body)
use reqwest;
use serde::Serialize;

#[derive(Serialize)]
struct UserCredentials {
    password: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let user_credentials = UserCredentials {
        password: "password".to_string(),
    };
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/users/USERNAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&user_credentials)
        .send().await;
    Ok(())
}

Update user

Update credentials for a user present on the server.

Token required

Yes

Method

PUT

URL

/v1/users/USERNAME

Request body

 
{
    "password": string
}

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK

No body.

400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request PUT \
  --url http://0.0.0.0:8000/v1/users/USERNAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}' \
  --json '{"password": "PASSWORD"}'
import requests

url = "http://0.0.0.0:8000/v1/users/USERNAME"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}
body = {
    "password": "PASSWORD"
}

response = requests.put(url, headers=headers, json=body)
use reqwest;
use serde::Serialize;

#[derive(Serialize)]
struct UserCredentials {
    password: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let user_credentials = UserCredentials {
        password: "password".to_string(),
    };
    let client = reqwest::Client::new();
    let resp = client
        .put("http://0.0.0.0:8000/v1/users/USERNAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&user_credentials)
        .send().await;
    Ok(())
}

Delete user

Delete a user from the server by name.

Token required

Yes

Method

DELETE

URL

/v1/users/USERNAME

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK

No body.

400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
401: Unauthorized

Possible causes:

  • Invalid token

  • Expired token

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request DELETE \
  --url http://0.0.0.0:8000/v1/users/USERNAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/users/USERNAME"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.delete(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .delete("http://0.0.0.0:8000/v1/users/USERNAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Transactions

Open transaction

Open a new transaction and receive a unique transaction id.

Token required

Yes

Method

POST

URL

/v1/transactions/open

Request body

 
{
    "databaseName": string,
    "transactionType": "read" | "write" | "schema",
    "transactionOptions": {                        // optional
        "schemaLockAcquireTimeoutMillis": integer, // optional
        "transactionTimeoutMillis": integer        // optional
    }
}

Request headers

Authorization: Bearer ACCESS_TOKEN

Transaction options:

Field Description

schemaLockAcquireTimeoutMillis

Timeout for a schema transaction to acquire the exclusive schema lock of the database. Can be used to wait until a previous schema transaction finishes and releases the exclusivity lock. Specified in milliseconds. Default: 10 seconds.

transactionTimeoutMillis

The maximum amount of time a transaction can stay opened. It will be closed automatically without preserving its changes and finishing its active queries after this timeout. Specified in milliseconds. Default: 5 minutes.

Responses:

200: OK 
{
  "transactionId": string
}
400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/transactions/open \
  --header 'Authorization: Bearer {ACCESS-TOKEN}' \
  --json '{"databaseName": "DATABASE_NAME", "transactionType": "schema"}'
import requests

url = "http://0.0.0.0:8000/v1/transactions/open"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}
body = {
    "databaseName": "DATABASE_NAME",
    "transactionType": "schema",
}

response = requests.post(url, headers=headers, json=body)
use reqwest;
use serde::Serialize;

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
pub enum TransactionType {
    Read,
    Write,
    Schema,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct Transaction {
    database_name: String,
    transaction_type: TransactionType,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let transaction = Transaction {
        database_name: DATABASE_NAME,
        transaction_type: TransactionType::Schema,
    };
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/transactions/open")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&transaction)
        .send().await;
    Ok(())
}

Close transaction

Close a transaction without preserving its changes by transaction id.

Token required

Yes

Method

POST

URL

/v1/transactions/TRANSACTION_ID/close

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK

No body.

400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/close \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/close"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.post(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/close")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Commit transaction

Commit and close a transaction, preserving it changes on the server.

Token required

Yes

Method

POST

URL

/v1/transactions/TRANSACTION_ID/commit

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK

No body.

400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/commit \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/commit"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.post(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/commit")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Rollback transaction

Rolls back the uncommitted changes made via a transaction.

Token required

Yes

Method

POST

URL

/v1/transactions/TRANSACTION_ID/rollback

Request body

None

Request headers

Authorization: Bearer ACCESS_TOKEN

Responses:

200: OK

No body.

400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/rollback \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
import requests

url = "http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/rollback"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.post(url, headers=headers)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/rollback")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

Query in transaction

Run a query within an open transaction. This endpoint allows running multiple sequential queries before committing.

Token required

Yes

Method

POST

URL

/v1/transactions/TRANSACTION_ID/query

Request body

 
{
    "query": string,
    "queryOptions": {                    // optional
        "includeInstanceTypes": boolean, // optional
        "answerCountLimit": integer      // optional
    }
}

Request headers

Authorization: Bearer ACCESS_TOKEN

Query options:

Field Description

includeInstanceTypes

An optimization flag: whether to include the types of the returned instance concepts in concept row responses or not. Default: true.

answerCountLimit

The maximum allowed size of concept rows or concept documents answers returned. Used to limit the network load. Default: 10 000.

If used in a read query, at most answerCountLimit answers will be returned. If there are more answers cut, a relevant warning will be provided in the response.

If used in a write query and is hit, the operation will fail completely.

This behaviour will be changed in the next stable version of TypeDB:

If used in a write query, at most answerCountLimit answers will be returned. All changes, including both returned and not returned, will be applied.

Responses:

200: OK 
{
  "queryType": "read" | "write" | "schema",
  "answerType": "ok" | "conceptRows" | "conceptDocuments",
  "answers": [ ... ], // optional
  "warning": string   // optional
}
400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}
408: Request Timeout

Possible causes:

  • Request finished with an error due to an execution timeout

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/query \
  --header 'Authorization: Bearer {ACCESS-TOKEN}' \
  --json '{"query": "define entity person;"}'
import requests

url = "http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/query"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}
body = {
    "query": "define entity person;"
}

response = requests.post(url, headers=headers, json=body)
use reqwest;
use serde::Serialize;

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct Query {
    query: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let query = Query {
        query: "define entity person;".to_string(),
    };
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/transactions/TRANSACTION_ID/query")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&query)
        .send().await;
    Ok(())
}

Example responses for each concept:

Concept rows
Request body 
{
    "query": "match $entity isa $entity-type, has $attribute-type $attribute; $relation isa $relation-type, links ($entity); $relation-type relates $role-type; let $value = $attribute;",
    "queryOptions": {
        "includeInstanceTypes": true
    }
}
{
    "queryType": "read",
    "answerType": "conceptRows",
    "answers": [
        {
            "entity": {
                "kind": "entity",
                "iid": "0x1e00000000000000000001",
                "type": {
                    "kind": "entityType",
                    "label": "person"
                }
            },
            "role-type": {
                "kind": "roleType",
                "label": "parentship:parent"
            },
            "relation": {
                "kind": "relation",
                "iid": "0x1f00000000000000000000",
                "type": {
                    "kind": "relationType",
                    "label": "parentship"
                }
            },
            "relation-type": {
                "kind": "relationType",
                "label": "parentship"
            },
            "attribute-type": {
                "kind": "attributeType",
                "label": "name",
                "valueType": "string"
            },
            "entity-type": {
                "kind": "entityType",
                "label": "person"
            },
            "value": {
                "kind": "value",
                "value": "John",
                "valueType": "string"
            },
            "attribute": {
                "kind": "attribute",
                "value": "John",
                "valueType": "string",
                "type": {
                    "kind": "attributeType",
                    "label": "name",
                    "valueType": "string"
                }
            }
        }
    ],
    "warning": null
}
Concept documents
Request body 
{
    "query": "match $entity isa $entity-type, has $attribute-type $attribute; $relation isa $relation-type, links ($entity); $relation-type relates $role-type; fetch { 'entity type': $entity-type, 'relation type': $relation-type, 'entity attributes': { $entity.* }, 'sub query': [ match let $value = $attribute; fetch { 'value': $value }; ] };"
}
{
    "queryType": "read",
    "answerType": "conceptDocuments",
    "answers": [
        {
            "entity attributes": {
                "name": "John"
            },
            "sub query": [
                {
                    "value": "John"
                }
            ],
            "entity type": {
                "kind": "entity",
                "label": "person"
            },
            "relation type": {
                "kind": "relation",
                "label": "parentship"
            }
        }
    ],
    "warning": null
}

One-shot query

Run a one-shot query. This endpoint executes a query within a temporary transaction that is opened and then either committed or closed exclusively for this query.

Token required

Yes

Method

POST

URL

/v1/query

Request body

 
{
    "query": string,
    "commit": boolean,                             // optional
    "databaseName": string,
    "transactionType": "read" | "write" | "schema",
    "transactionOptions": {                        // optional
        "schemaLockAcquireTimeoutMillis": integer, // optional
        "transactionTimeoutMillis": integer        // optional
    },
    "queryOptions": {                              // optional
        "includeInstanceTypes": boolean,           // optional
        "answerCountLimit": integer                // optional
    }
}

Request headers

Authorization: Bearer ACCESS_TOKEN

Transaction options:

Field Description

schemaLockAcquireTimeoutMillis

Timeout for a schema transaction to acquire the exclusive schema lock of the database. Can be used to wait until a previous schema transaction finishes and releases the exclusivity lock. Specified in milliseconds. Default: 10 seconds.

transactionTimeoutMillis

The maximum amount of time a transaction can stay opened. It will be closed automatically without preserving its changes and finishing its active queries after this timeout. Specified in milliseconds. Default: 5 minutes.

Query options:

Field Description

includeInstanceTypes

An optimization flag: whether to include the types of the returned instance concepts in concept row responses or not. Default: true.

answerCountLimit

The maximum allowed size of concept rows or concept documents answers returned. Used to limit the network load. Default: 10 000.

If used in a read query, at most answerCountLimit answers will be returned. If there are more answers cut, a relevant warning will be provided in the response.

If used in a write query and is hit, the operation will fail completely.

This behaviour will be changed in the next stable version of TypeDB:

If used in a write query, at most answerCountLimit answers will be returned. All changes, including both returned and not returned, will be applied.

Responses:

200: OK 
{
  "queryType": "read" | "write" | "schema",
  "answerType": "ok" | "conceptRows" | "conceptDocuments",
  "answers": [ ... ], // optional
  "warning": string   // optional
}
400: Bad Request

Possible causes:

  • Incorrectly formatted request (e.g. Authorization header missing a token)

Response format:

{
    "code": string,
    "message": string
}
403: Forbidden

Possible causes:

  • The supplied access token lacks the required access level for the request

Response format:

{
    "code": string,
    "message": string
}
404: Not Found

Possible causes:

  • One or more resources referenced in the request could not be found

Response format:

{
    "code": string,
    "message": string
}
408: Request Timeout

Possible causes:

  • Request finished with an error due to an execution timeout

Response format:

{
    "code": string,
    "message": string
}

Example request:

  • curl

  • Python

  • Rust

curl --request POST \
  --url http://0.0.0.0:8000/v1/query \
  --header 'Authorization: Bearer {ACCESS-TOKEN}' \
  --json '{"databaseName": "DATABASE_NAME", "transactionType": "schema", "query": "define entity person;"}'
import requests

url = "http://0.0.0.0:8000/v1/query"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}
body = {
    "databaseName": "DATABASE_NAME",
    "transactionType": "schema",
    "query": "define entity person;"
}

response = requests.post(url, headers=headers, json=body)
use reqwest;
use serde::Serialize;

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
pub enum TransactionType {
    Read,
    Write,
    Schema,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct OneshotQuery {
    database_name: String,
    transaction_type: TransactionType,
    query: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let query = OneshotQuery {
        database_name: DATABASE_NAME,
        transaction_type: TransactionType::Schema,
        query: "define entity person;".to_string(),
    };
    let client = reqwest::Client::new();
    let resp = client
        .post("http://0.0.0.0:8000/v1/query")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&query)
        .send().await;
    Ok(())
}

Example responses for each concept:

Concept rows
Request body 
{
    "databaseName": "test",
    "transactionType": "read",
    "query": "match $entity isa $entity-type, has $attribute-type $attribute; $relation isa $relation-type, links ($entity); $relation-type relates $role-type; let $value = $attribute;",
    "queryOptions": {
        "includeInstanceTypes": true
    }
}
{
    "queryType": "read",
    "answerType": "conceptRows",
    "answers": [
        {
            "entity": {
                "kind": "entity",
                "iid": "0x1e00000000000000000001",
                "type": {
                    "kind": "entityType",
                    "label": "person"
                }
            },
            "role-type": {
                "kind": "roleType",
                "label": "parentship:parent"
            },
            "relation": {
                "kind": "relation",
                "iid": "0x1f00000000000000000000",
                "type": {
                    "kind": "relationType",
                    "label": "parentship"
                }
            },
            "relation-type": {
                "kind": "relationType",
                "label": "parentship"
            },
            "attribute-type": {
                "kind": "attributeType",
                "label": "name",
                "valueType": "string"
            },
            "entity-type": {
                "kind": "entityType",
                "label": "person"
            },
            "value": {
                "kind": "value",
                "value": "John",
                "valueType": "string"
            },
            "attribute": {
                "kind": "attribute",
                "value": "John",
                "valueType": "string",
                "type": {
                    "kind": "attributeType",
                    "label": "name",
                    "valueType": "string"
                }
            }
        }
    ],
    "warning": null
}
Concept documents
Request body 
{
    "databaseName": "test",
    "transactionType": "read",
    "query": "match $entity isa $entity-type, has $attribute-type $attribute; $relation isa $relation-type, links ($entity); $relation-type relates $role-type; fetch { 'entity type': $entity-type, 'relation type': $relation-type, 'entity attributes': { $entity.* }, 'sub query': [ match let $value = $attribute; fetch { 'value': $value }; ] };"
}
{
    "queryType": "read",
    "answerType": "conceptDocuments",
    "answers": [
        {
            "entity attributes": {
                "name": "John"
            },
            "sub query": [
                {
                    "value": "John"
                }
            ],
            "entity type": {
                "kind": "entity",
                "label": "person"
            },
            "relation type": {
                "kind": "relation",
                "label": "parentship"
            }
        }
    ],
    "warning": null
}

Health check

Check that the server is accessible and healthy.

Token required

No

Method

GET

URL

/health

Request body

None

Request headers

None

Responses:

204: No Content

No body.

Example request:

  • curl

  • Python

  • Rust

curl --request GET \
  --url http://0.0.0.0:8000/health
import requests

url = "http://0.0.0.0:8000/health"

response = requests.get(url)
use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .get("http://0.0.0.0:8000/health")
        .send().await;
    Ok(())
}