# TypeDB HTTP API

## [](#_authorization)Authorization

### [](#_sign_in)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

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

Request headers

None

**Responses:**

200: OK

```json
{
    "token": string
}
```

400: Bad Request

Possible causes:

*   Incorrectly formatted request
    

Response format:

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

401: Unauthorized

Possible causes:

*   Invalid credentials
    

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request POST \
  --url http://localhost:8000/v1/signin \
  --json '{"username": "USERNAME", "password": "PASSWORD"}'
```

```python
import requests

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

response = requests.post(url, json=body)
```

```rust
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://localhost:8000/v1/signin")
        .json(&signin)
        .send().await;
    Ok(())
}
```

**Example response:**

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

## [](#_server_information)Server information

### [](#_version)Version

Get the server’s distribution and version information.

 

Token required

No

Method

`GET`

URL

`/v1/version`

Request body

None

Request headers

None

**Responses:**

200: OK

```json
{
    "distribution": string,
    "version": string
}
```

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request GET \
  --url http://localhost:8000/v1/version
```

```python
import requests

url = "http://localhost:8000/v1/version"

response = requests.get(url)
```

```rust
use reqwest;

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

**Example response:**

```
{
    "distribution": "TypeDB",
    "version": "3.2.0"
}
```

## [](#_databases)Databases

### [](#_get_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

```json
{
    "databases": [
        {
            "name": string
        }
    ]
}
```

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request GET \
  --url http://localhost:8000/v1/databases \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.get(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_get_database)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

```json
{
    "name": string
}
```

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request GET \
  --url http://localhost:8000/v1/databases/DATABASE_NAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.get(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_create_database)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:

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

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request POST \
  --url http://localhost:8000/v1/databases/DATABASE_NAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.post(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_delete_database)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:

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

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request DELETE \
  --url http://localhost:8000/v1/databases/DATABASE_NAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.delete(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_get_databases_schema)Get database’s schema

Retrieve a full schema text as a valid TypeQL define query string. This includes function definitions.

 

Token required

Yes

Method

`GET`

URL

`/v1/databases/DATABASE_NAME/schema`

Request body

None

Request headers

`Authorization: Bearer ACCESS_TOKEN`

**Responses:**

200: OK

If schema is defined

```bash
"define <statements>;"
```

If schema is not defined

```bash
""
```

400: Bad Request

Possible causes:

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

Response format:

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

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request GET \
  --url http://localhost:8000/v1/databases/DATABASE_NAME/schema \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

url = "http://localhost:8000/v1/databases/DATABASE_NAME/schema"

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

response = requests.get(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_get_databases_type_schema)Get database’s type schema

Retrieve the types in the schema as a valid TypeQL define query string.

 

Token required

Yes

Method

`GET`

URL

`/v1/databases/DATABASE_NAME/type-schema`

Request body

None

Request headers

`Authorization: Bearer ACCESS_TOKEN`

**Responses:**

200: OK

If schema is defined

```bash
"define <statements>;"
```

If schema is not defined

```bash
""
```

400: Bad Request

Possible causes:

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

Response format:

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

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request GET \
  --url http://localhost:8000/v1/databases/DATABASE_NAME/type-schema \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

url = "http://localhost:8000/v1/databases/DATABASE_NAME/type-schema"

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

response = requests.get(url, headers=headers)
```

```rust
use reqwest;

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

## [](#_users)Users

### [](#_get_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

```json
{
    "users": [
        {
            "username": string
        }
    ]
}
```

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

403: Forbidden

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request GET \
  --url http://localhost:8000/v1/users \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.get(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_get_user)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

```json
{
    "username": string
}
```

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

403: Forbidden

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request GET \
  --url http://localhost:8000/v1/users/USERNAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.get(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_create_user)Create user

Create a new user on the server.

 

Token required

Yes

Method

`POST`

URL

`/v1/users/USERNAME`

Request body

```json
{
    "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:

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

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

403: Forbidden

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

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

```python
import requests

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

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

response = requests.post(url, headers=headers, json=body)
```

```rust
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://localhost:8000/v1/users/USERNAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&user_credentials)
        .send().await;
    Ok(())
}
```

### [](#_update_user)Update user

Update credentials for a user present on the server.

 

Token required

Yes

Method

`PUT`

URL

`/v1/users/USERNAME`

Request body

```json
{
    "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:

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

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

403: Forbidden

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

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

```python
import requests

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

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

response = requests.put(url, headers=headers, json=body)
```

```rust
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://localhost:8000/v1/users/USERNAME")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&user_credentials)
        .send().await;
    Ok(())
}
```

### [](#_delete_user)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:

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

401: Unauthorized

Possible causes:

*   Invalid token
    
*   Expired token
    

Response format:

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

403: Forbidden

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request DELETE \
  --url http://localhost:8000/v1/users/USERNAME \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.delete(url, headers=headers)
```

```rust
use reqwest;

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

## [](#_transactions)Transactions

### [](#_open_transaction)Open transaction

Open a new transaction and receive a unique transaction id.

 

Token required

Yes

Method

`POST`

URL

`/v1/transactions/open`

Request body

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

Request headers

`Authorization: Bearer ACCESS_TOKEN`

**Transaction options:**

 

Field

Description

`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

`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

**Responses:**

200: OK

```json
{
  "transactionId": string
}
```

400: Bad Request

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

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

```python
import requests

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

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

response = requests.post(url, headers=headers, json=body)
```

```rust
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://localhost:8000/v1/transactions/open")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&transaction)
        .send().await;
    Ok(())
}
```

### [](#_close_transaction)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:

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

403: Forbidden

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request POST \
  --url http://localhost:8000/v1/transactions/TRANSACTION_ID/close \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.post(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_commit_transaction)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:

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

403: Forbidden

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request POST \
  --url http://localhost:8000/v1/transactions/TRANSACTION_ID/commit \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.post(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_rollback_transaction)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:

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

403: Forbidden

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

```console
curl --request POST \
  --url http://localhost:8000/v1/transactions/TRANSACTION_ID/rollback \
  --header 'Authorization: Bearer {ACCESS-TOKEN}'
```

```python
import requests

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

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

response = requests.post(url, headers=headers)
```

```rust
use reqwest;

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

### [](#_query_in_transaction)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

```json
{
    "query": string,
    "queryOptions": {                    // optional
        "includeInstanceTypes": boolean, // optional
        "answerCountLimit": integer      // optional
    },
    "given": GivenRow[],
}
```

Request headers

`Authorization: Bearer ACCESS_TOKEN`

**Query options:**

 

Field

Description

`includeInstanceTypes`

Whether to include the types of the returned instance concepts in concept row responses or not. This option allows reducing the amount of unnecessary data transmitted.

**Default:** true

`answerCountLimit`

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

At most **count limit** answers is returned. If it is a write query, all changes, including both returned and not returned, will be applied. If there are more answers cut, a relevant `warning` will be provided in the response.

**Default:** 10 000

**Given rows:**

Each given row maps a 'given' variable to an instance or value. .Examples:

Details

```json
{
  "query": "given $p: person, $n: string, $dob: datetime-tz;\ninsert $p has name == $n, has date-of-birth == $dob;",
  "given": [
    {
        "p": {
          "kind": "entity",
          "iid": "0x1e00000000000000000001"
        },
        "n": {
          "kind": "value",
          "valueType": "string",
          "value": "John"
        },
        "dob": "1987-12-22T17:29 Asia/Kolkata"
    }
  ]
}
```

**Responses:**

200: OK

```json
{
  "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:

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

403: Forbidden

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

408: Request Timeout

Possible causes:

*   Request finished with an error due to an execution timeout
    

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

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

```python
import requests

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

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

response = requests.post(url, headers=headers, json=body)
```

```rust
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://localhost: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

```json
{
    "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
    }
}
```

```json
{
    "queryType": "read",
    "answerType": "conceptRows",
    "answers": [
        {
            "data": {
                "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

```json
{
    "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 }; ] };"
}
```

```json
{
    "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)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

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

`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

`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

**Query options:**

 

Field

Description

`includeInstanceTypes`

Whether to include the types of the returned instance concepts in concept row responses or not. This option allows reducing the amount of unnecessary data transmitted.

**Default:** true

`answerCountLimit`

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

At most **count limit** answers is returned. If it is a write query, all changes, including both returned and not returned, will be applied. If there are more answers cut, a relevant `warning` will be provided in the response.

**Default:** 10 000

**Responses:**

200: OK

```json
{
  "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:

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

403: Forbidden

Possible causes:

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

Response format:

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

404: Not Found

Possible causes:

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

Response format:

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

408: Request Timeout

Possible causes:

*   Request finished with an error due to an execution timeout
    

Response format:

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

**Example request:**

*   curl
    
*   Python
    
*   Rust
    

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

```python
import requests

url = "http://localhost: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)
```

```rust
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://localhost:8000/v1/query")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .json(&query)
        .send().await;
    Ok(())
}
```

**Example responses for each concept:**

Concept rows

Request body

```json
{
    "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
    }
}
```

```json
{
    "queryType": "read",
    "answerType": "conceptRows",
    "answers": [
        {
            "data": {
                "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

```json
{
    "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 }; ] };"
}
```

```json
{
    "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)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
    

```console
curl --request GET \
  --url http://localhost:8000/health
```

```python
import requests

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

response = requests.get(url)
```

```rust
use reqwest;

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

[C# gRPC driver](../typedb-grpc-drivers/csharp/index.md) [TypeDB HTTP Drivers](../typedb-http-drivers/index.md)

[Edit on GitHub](https://github.com/typedb/typedb-docs/edit/3.x-development/reference/modules/ROOT/pages/typedb-http-api.adoc) Edit this page on GitHub.