---
title: "REST Endpoints"
description: "Overview of TigerGraph's REST API."
component: "tigergraph-server"
version: "4.3"
module: "API"
html_url: "/tigergraph-server/4.3/API/"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/API/"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/API/index.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/)

# REST Endpoints

This user guide provides information on how to engage with our REST APIs: the introduction section explains how to send requests, pass parameters, and format request bodies, while [GSQL Endpoints](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md) describes in detail each endpoint and its input and output.

> [!NOTE]
> Version 4.1 introduces changes to consolidate and unify the syntax for REST endpoints:
> 
> * Several REST API endpoints have been consolidated onto the GSQL server.
> * For self-installed systems, send requests to the NGINX proxy server (port 14240). For TigerGraph Cloud users, send requests to port 443.
> * The path prefix for endpoints has changed.
> * All endpoints can use token authentication instead of username and password.

A request must include the following specifications:

Our API accepts URL-encoded query string parameters, [JSON](https://www.json.org/json-en.html)\-encoded request bodies and returns JSON encoded responses.

To submit a request, send an HTTP request to the REST++ server or the GSQL server. By default, both REST++ server and GSQL server listens for requests on port 14240\. A request needs to specify the following:

* The request method (`GET`, `POST`, `PUT`, or `DELETE`)
* The endpoint address
* Any required or optional request parameters in URL encoding
* For `POST` requests, a data payload (i.e., request body) in JSON encoding unless otherwise specified
* In some cases, request header parameters

For requests that are sent to the GSQL server, the sender needs to provide TigerGraph user credentials for the request to be accepted. If authentication is enabled on the RESTPP server, a request token needs to be included in the request header as well. User credentials can be provided in 3 ways:

* `-u <user:password>`: pass the specified user name and password with curl option
* `-H 'Authorization: Bearer <JWT-token>'`: pass JWT token via header, note that JWT token was requested on graph level, so user will only has the access to the specific graph with JWT token
* `-H 'Authorization: Basic <encoded-username-password>'`: pass encoded username and password via header
* `-H 'Authorization: GSQL-Secret <gsql-secret>'`: pass gsql secret via header

> [!NOTE]
> When making a REST request, you need to know the IP address of the REST server. If the requester happens to be on the same server (e.g., in test set up), you can replace the IP address with `localhost`.

## Formatting query string parameters

TigerGraph's API endpoints accept parameters in URL encoding, which is straightforward in the case of string, number, and boolean values. However, some parameters, such as parameters for running a query, are more complex and require specific formatting.

The following table describes how to format the complex type parameter values when executing a query.

| Parameter type | Description | Example |
| --- | --- | --- |
| `SET` or `BAG` of primitives | Assign multiple values to the same parameter name. | A `SET<INT>` parameter named `p1` is assigned three integers: `p1=1&p1=5&p1=10` |
| `VERTEX` with a defined type | Use the primary key of the vertex. | A `VERTEX<person>` parameter named `vp` is assigned a vertex whose ID is `"person1"`: `vp=person1` |
| `VERTEX` without a defined type | Use `<parameter_name>.<parameter_type>` to specify the type of the parameter, and also provide the primary key of the vertex. | A `VERTEX` parameter named `va` is assigned a `person` type vertex whose ID is `"person2"` **`va=person2&va.type=person`** |
| `SET` or `BAG` of vertices with a defined type | Same as a `SET` or `BAG` of primitives, where the value for each element is the primary key of the vertex. | A `SET<VERTEX<person>>` parameter named `vp` is assigned two vertices with IDs `"person3"` and `"person4"`: **`vp=person3&vp=person4`** |
| `SET` or `BAG` of vertices without a defined type | The `SET` or `BAG` must be treated as an array, specifying the order of the elements with indices `[0]`, `[1]`, etc. | A `SET<VERTEX>` parameter named `vp` is assigned a `person` type vertex with an ID of `"person5"` and a `post` type vertex with an ID of `11` : **`vp[0]=person5&vp[0].type=person&vp[1]=11&vp[1].type=post`** |

### Example

## Input data for `POST` requests

Input data for `POST` requests should be in JSON format, unless the endpoint specifically accepts data in other formats. There are two ways to supply the data: inline or in a separate file.

### Inline data

The data should be formatted as a single string without linebreaks. If using curl, use the `-d` option, followed by the JSON string.

Syntax for a POST request with Inline Data Payload

```bash
curl -X POST -d 'json_string' "http://server_ip:14240/restpp/path_to_endpoint?request_parameters"
```

The following example uses the `POST /graph` endpoint to insert one User type vertex whose ID is `id6` into the graph called `"Social_Net"`.

Example using inline input data

```bash
curl -X POST -d '{"vertices":{"User":{"id6":{"id":{"value":"id6"}}}}}' "http://localhost:14240/restpp/graph/Social_Net"
```

### Data file

Often it will be more convenient for the input data to be in a separate file, especially if the data is large.

For curl, use `--data-binary @<path_to_file>` as in the following example:

Syntax for a POST request with Payload Data File

```bash
curl -X POST --data-binary @./person.csv  "http://localhost:14240/restpp/ddl/poc_graph?tag=load_data&filename=f1"
```

### Formatting data in JSON

Data of primitive types, including `INT, UINT, FLOAT, DOUBLE, STRING, BOOL`, and `DATETIME`, as well as arrays and objects, follow the standard [JSON Data Interchange Syntax](https://www.json.org/json-en.html).

The following table subsection describes how to format complex data types.

| Data type | Description | Example |
| --- | --- | --- |
| `SET`, `LIST` or `BAG` of primitives | Use a JSON array of primitive values. | A set of primitive values: `[1, 2, 3]` |
| `VERTEX` | Use a JSON object that has an `id` field whose value is the primary key of the vertex and a `type` field whose value is the type of the vertex. | A `person` vertex with an ID of `"Tom"`: `{"id": "Tom", "type": "person"}` |
| `MAP` | Use a JSON object that has two JSON arrays with keys `keylist`and `valuelist`, each containing the keys and the values of the map respectively. The order of items in the valuelist should correspond to the order of items in the keylist. | A map of nations and their capitals: `{"keylist": ["England", "Germany"],`   `"valuelist": ["London", "Berlin"]}` |
| User-Defined Type (UDT) | Use a JSON object that has two JSON arrays with keys `keylist` and `valuelist`. The `keylist` array contains the field names of the tuple, and the `valuelist` array contains the values of the fields. The order of items in the `keylist` should correspond to the order of the fields as specified in the definition of the tuple/UDT, and the order of values in the `valuelist` should correspond to the order of items in the keylist. | Tuple schema definition: `TYPEDEF TUPLE <name STRING, age INT> person` A `person` tuple written in JSON: `{"keylist: ["name", "age"], "valuelist": ["Sam", 24]}` |

Example: UDT Definition

```gsql
TYPEDEF TUPLE <field1 INT(1), field2 UINT, field3 STRING(10), field4 DOUBLE> myTuple
```

#### Vertices with composite keys

> [!NOTE]
> This format for vertices with composite keys does not apply to the [endpoint used to upsert data](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_upsert_data_to_graph). It is only applicable to the [endpoint to run a query](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_run_an_installed_query_post).

If a vertex has a composite key composed of multiple attributes, then all values for those attributes must be provided for the `"id"` field. The values can be presented either as a JSON object with key-value pairs for each attribute-value pair, or as a JSON array with a list values in the same order as defined in the schema.

The following example shows the two methods for a vertex `v` having a composite primary key composed of the three attributes `id` and `name`

* Option 1
* Option 2

Vertex v with composite key as JSON array

```javascript
{
  "v":{
    "id":["Tom",456], (1)
    "type":"compositePerson"
  }
}
```

| **1** | The values in the array must be in the same order as they are defined in the schema. |
| --- | --- |

Vertex v with composite key as JSON object

```javascript
{
  "v":{
    "id":{
      "name":"Tom",
      "id":456
    },
    "type":"compositePerson"
  }
}
```

#### `SET` or `BAG` of Vertices

To describe a `SET` or `BAG` of vertices in JSON, use a JSON array with _vertex objects_ nested in the `SET` or `BAG` array.

## Output responses

All TigerGraph REST responses are in JSON format. The output JSON object has four fields: `"version"`, `"error"`, `"message"`, and `"result"`.

* `"version"` \- this field describes the version of the running TigerGraph instance.
* "`error"` \- a boolean value to indicate if there is an error in processing the request. If there is an error, the `"error"` field will be `true`.
* `"message"` \- the error message when there is an error. If a request is successful, the field will be an empty string or a brief message conveying the result of the request.
* `"results"` \- this field contains the resulting data from the request. Details about the result of each built-in endpoint are described in the [Built-in Endpoints](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md) section.

```javascript
// Example response
{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "v_id": "id1",
      "v_type": "User",
      "attributes": {}
    }
  ]
}
```

> [!NOTE]
> To make the JSON output more human-readable in the terminal, use the [jq](https://stedolan.github.io/jq/) command or Python json library built into most Linux installations:
> 
> ```bash
> curl -X method "http://server_ip:14240/restpp/path_to_endpoint?request_parameters" | jq .
> 
> curl -X method "http://server_ip:14240/restpp/path_to_endpoint?request_parameters" | python -m json.tool
> ```

## Size and time limits

The maximum length for the request URL is 8K bytes, including the query string. Requests with a large parameter size should use a data payload file instead of inline data.

### Request body size

The maximum size for a request body, including the payload file, is set by the system parameter `Nginx.ClientMaxBodySize`. The default value is 200 (in MB). To increase this limit, use the following `gadmin` command:

```console
gadmin config set Nginx.ClientMaxBodySize NNN
```

The upper limit of this setting is 1024 MB. Raising the size limit for the data payload buffer reduces the memory available for other operations, so be cautious about increasing this limit.

### GSQL query timeout

By default, an HTTP request in the TigerGraph system times out after 16 seconds. to customize this timeout limit for a particular query instance, you can set the GSQL-TIMEOUT parameter in the request header. If you are using curl to submit your RESTPP request, the syntax would be the following:

```bash
curl -X <GET/POST> -H "GSQL-TIMEOUT: <timeout value in ms>" '<request_URL>'
```

### Response size

You can specify the response size limit of an HTTP request with the following header:

```bash
curl -X <GET/POST> -H "RESPONSE-LIMIT: <size limit in byte>" '<request_URL>'
```

* If the `RESPONSE-LIMIT` header is not set, TigerGraph uses the value configured in `GSQL.QueryResponseMaxSizeByte` as the default response size limit.
* If the response size is larger than the given limit, an error message will be returned instead of the actual query result:

```bash
{
  "error": true,
  "message": "The query response size is 256MB, which exceeds limit 32MB.",
  "results": [],
  "code": "REST-4000"
}
```

### Compressed responses

#### Gzip compression

You can request a gzip-compressed response for a query by including the `Accept-Encoding: gzip` header in your request. This is supported for query responses larger than 1000 bytes.

Use this option when network bandwidth is low. gzip compression itself takes some processing time.

```bash
curl -X GET -H "Accept-Encoding: gzip" -o /path/to/zip.gz "http://localhost:14240/restpp/query/{graph_name}/{query_name}"
```

You can also request a gzip-compressed response when running a query from the GSQL shell , see [\-gzip option](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/run-manage-queries.md#_gzip_compression) of the `RUN QUERY` command.

#### Zstd compression

You can request a zstd-compressed response for an installed query by including the `Accept-Encoding: zstd` header in your request.

```bash
curl -X GET -H "Accept-Encoding: zstd" -o /path/to/out.zst "http://localhost:14240/restpp/query/{graph_name}/{query_name}"
```

The default zstd compression level is `3`. To change the compression level, set the `ZSTD_COMPRESSION_LEVEL` environment variable in `RESTPP.BasicConfig.Env`. For example:

```text
ZSTD_COMPRESSION_LEVEL=4
```

You can also request a zstd-compressed response when running an installed query from the GSQL shell. See [\-zstd option](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/run-manage-queries.md#_zstd_compression) of the `RUN QUERY` command.

> [!NOTE]
> If you submit or run a query in async mode, do not use gzip or zstd compression with the request. Use gzip or zstd compression with the `query_result` API to fetch the actual query result.

## `curl` options

Request examples in this guide are made using [curl](https://curl.se/docs/manpage.html). Below is a list of `curl` options used in our code examples:

* `-d <data>`  
   * Sends the specified data in a `POST` request to the HTTP server in the same way that a browser does when a user has filled in an HTML form and presses the submit button. This will cause curl to pass the data to the server using the content-type `application/x-www-form-urlencoded`.  
   * To read the data from a file, start with a\`@\` character, followed by the filepath. For example, the command `curl -d @foobar` will read data from a file named `foobar`.
* `--data-binary <data>`  
   * Sends data with a `POST` request exactly as specified with no extra processing.
* `--fail`  
   * Makes curl fail silently (no output at all) on server errors.  
   * This is mostly done to enable scripts etc. to better deal with failed attempts. In normal cases when an HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22.
* `-H <header>`  
   * Extra header to include in the request when sending HTTP to a server. You may specify any number of extra headers.  
   * TigerGraph APIs use headers to specify [size and time limits](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/index.md#_size_and_time_limits), as well as to provide [authentication tokens](https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/jwt-token.md#_usage_of_gsql_jwt_token).
* `-s`  
   * Silent or quiet mode. Don't show a progress meter or error messages. It will still output the data you ask for, potentially even to the terminal/stdout unless you redirect it.
* `-u <user:password>`  
   * Submits the specified user name and password for server authentication.
* `-X <request_method>`  
   * Specifies a custom request method to use when communicating with the HTTP server. If this option is not used, curl will make a `GET` request by default.
