Introduction

Welcome to the NorthGravity API! You can use our API to upload, download, and search, or list files. All files may be uploaded together with metadata. Metadata are validated against the chosen file group.

Authorization

An Authorization header containing a token or an API key is expected by the Northgravity API. The only exception to this requirement is the login request, which requires the user credentials.

To authorize, use a Token, an API key or Basic Authentication:

curl "api_endpoint_here"
  -H "Authorization: Bearer yourAccessToken"

curl "api_endpoint_here"
  -H "Authorization: ApiKey yourApiKey"

curl "api_endpoint_here"
  -u username:password ...

Create a Company

This endpoint creates a new company.

curl -X POST https://api.northgravity.com/auth/company \
  -d '{
    "name": "companyName",
    "authType": "ALL",
    "companyTags": [],
    "companyMetadata": [
      {
        "metadataKey": "key1",
        "defaultValue": "value1",
        "isRequired": false
      }
    ]
  }'

If successful, the above command returns status code 201, otherwise please check Errors section.

HTTP Request

POST https://api.northgravity.com/auth/company

Request Body

Parameter	Description	required
name	The name of the company.	yes
authType	The authentication type. The default is ALL. Choose one of the following values: `ALL`, `BASIC`, or `SSO`.	no
companyTags	Tags associated with the company. If a defaultValue is provided, it will be automatically used for the user.	no
metadata	A list of JSON objects with key-value pairs defining the metadata for the company (metadataKey size is 2-64 characters and defaultValue size is up to 128 characters). - `metadataKey`: The metadata key, with a length of 2-64 characters. - `defaultValue`: The default value for the company metadata. This can be left empty. - `isRequired`: Specifies if the value is required when creating a user (true or false).	no

Parameter	Description
companyId	The unique ID of the company.
name	The name of the company.
status	The current status of the company.
creationDate	The date when the company was created.
entGroups	A list of entitlement groups associated with the company.
companyTags	Tags associated with the company.
authType	The authentication type for the company.
companyMetadata	A list of JSON objects with key-value pairs defining the metadata for the company (metadataKey size is 2-64 characters and defaultValue size is up to 128 characters). - `companyMetadataId`: The unique ID of the company metadata. - `metadataKey`: The key for the company metadata. - `defaultValue`: The default value for the company metadata, automatically used for users if no other value is provided. - `isRequired`: Indicates whether the metadata value is required.

Edit Company

This endpoint updates the specified company’s details.

curl -X PATCH https://api.northgravity.com/auth/company/{companyName} \
  -d '{
    "name": "companyName",
    "authType": "ALL",
    "companyTags": [],
    "companyMetadata": [
        {
            "companyMetadataId": 42,
            "metadataKey": "key1",
            "defaultValue": "value1",
            "isRequired": false,
            "isOverrideUserMetadata": false
        },
        {
            "metadataKey": "key2",
            "defaultValue": "value2",
            "isRequired": false,
            "isOverrideUserMetadata": true
        },
        {
            "metadataKey": "key3",
            "defaultValue": "value3",
            "isRequired": true,
            "isOverrideUserMetadata": false
        }
    ],
    "metadataRemovalOption": "DECOUPLE_FROM_COMPANY_ONLY"
  }'

If successful, the above command returns status code 204, otherwise please check Errors section.

HTTP Request

PATCH https://api.northgravity.com/auth/company/{companyName}

Response Body

Parameter	Description
name	The name of the company.
authType	The authentication type for the company.
companyTags	Tags associated with the company.
companyMetadata	A list of JSON objects with key-value pairs defining the metadata for the company(metadataKey size is 2-64 characters and metadataValue size is up to 128 characters). - `companyMetadataId`: The unique ID of the company metadata. - `metadataKey`: The key for the company metadata. - `defaultValue`: The default value for the company metadata, which is automatically used for users if no other value is provided. - `isRequired`: Specifies whether the metadata value is required. - `isOverrideUserMetadata`: If true, overrides the user’s private metadata(if user has the same private key) with the company's default value; if false, converts user metadata to company metadata but retains the user’s current value.
metadataRemovalOption	Specifies the action to take when deleting company metadata: - `DECOUPLE_FROM_COMPANY_ONLY`: Converts company metadata to private user metadata and retains the current metadata value (default option). - `DELETE_FROM_USER_AND_COMPANY`: Deletes the metadata from both the company and the user. - `DECOUPLE_IF_OVERRIDDEN_OR_DELETE_IF_DEFAULT`: Removes metadata from the company; if the user has an overridden metadata value, it’s retained as private metadata; if the user is using the default company value, it is also deleted for the user.

Important Notes

This is a PATCH request, which allows adding, updating, and deleting in a single request.
To make any updates to Company Metadata, you must provide the full list of metadata items.
- To delete metadata, simply omit it from the companyMetadata list in the request.
- To update existing metadata, specify the item using its companyMetadataId.
- To add new metadata, include it in the list without a companyMetadataId; it will be treated as a new entry.

Create a User

This endpoint validates an email address and returns a token that can be used to change a password for an activated user.

curl -X POST https://api.northgravity.com/auth/register
  -d '{
    "companyId": 1,
    "email": "name.name@company.com",
    "roleIds": [4, 5, 6],
    "metadata": [
      {
          "metadataKey": "key2",
          "metadataValue": "overwritePrivateValue"
      },
      {
          "metadataKey": "privateKey",
          "metadataValue": "privateValue"
      }
    ]
  }'

If successful, the above command returns status code 200, otherwise please check Errors section.

{
    "userId": 1,
    "isRoleAssignError": false
}

OR if user creation passed successfully but there were errors with assigning roles. User was created but roles needs to be assigned manually.

{
    "userId": 1,
    "isRoleAssignError": true,
    "roleAssignErrors": [
      {
        "roleId": 1,
        "errorMsg": "Error message"
      }
    ]
}

HTTP Request

POST https://api.northgravity.com/auth/register

Request Body

Parameter	Description	required
email	The user's email address.	yes
companyId	The company id associated with the user.	no
roleIds	A list of role ids to which user should be assigned	no
metadata	A list of JSON objects with key-value pairs defining the metadata (metadataKey size is 2-64 characters and metadataValue size is up to 128 characters). Only `metadataKey` and `metadataValue` need to be provided; all company metadata will be fetched automatically. Cases: 1. Set a private user value for company metadata: To override a company metadata value with a private value for the user, provide the `metadataKey` (matching the company metadata key) and the desired `metadataValue`. 2. Add new private metadata: For metadata that doesn’t correspond to any company metadata, simply provide a unique `metadataKey` and `metadataValue`.	no

Get User

This endpoint returns information about the specified user.

curl -X GET https://api.northgravity.com/auth/user/{username}

If successful, the above command returns status code 200, otherwise please check Errors section.

HTTP Request

GET https://api.northgravity.com/auth/user/{username}

Response Body

Parameter	Description
userId	The unique ID of the user.
email	The user's email address.
company	The company associated with the user.
status	The current status of the user: : `ACTIVE`, `BLOCKED`, `DELETED`
roles	A list of roles assigned to the user.
authType	The authentication type associated with the user.
metadata	A list of JSON objects with key-value pairs defining metadata for the user. - `metadataKey`: The key for the metadata item, with a size between 2-64 characters. - `metadataValue`: The value assigned to the user metadata, with a size of up to 128 characters. - `isCompanyMetadata`: A flag indicating whether this metadata is inherited from the company (`true`) or is user-specific (`false`). - `isRequired`: Indicates whether the metadata value is required for the user.

Update User

This endpoint updates the specified user’s.

curl -X PATCH https://api.northgravity.com/auth/user/{username} \
  -d '{
    "status": "BLOCKED",
    "metadata": [
        {
            "metadataKey": "privateKey",
            "metadataValue": "privateUserValue"
        },
        {
            "metadataKey": "key3",
            "metadataValue": "privateValueOverwrite"
        }
    ]
  }'

If successful, the above command returns status code 204, otherwise please check Errors section.

HTTP Request

PATCH https://api.northgravity.com/auth/user/{username}

Response Body

Parameter	Description	required
status	User status: `ACTIVE`, `BLOCKED`, `DELETED`	no
metadata	A list of JSON objects containing key-value pairs that define the metadata for the user. - `metadataKey`: The key for the metadata item (must be between 2-64 characters). - `metadataValue`: The value assigned to the user metadata (up to 128 characters). If this matches a company metadata key, it will overwrite the company value with a private value for this user. Otherwise, it is treated as user-specific metadata.	no

Important Notes

This is a PATCH request, which allows adding, updating, and deleting metadata in a single request.
- To delete metadata, simply omit it from the metadata list in the request.
- To update existing metadata or add new metadata, include it in the list. This will either update an existing key with a new value or add a new entry if the key doesn’t exist.
User-Level Metadata: From the user level, you cannot change or delete company metadata. You can only provide an overwrite value specific to the user. The original company metadata remains unaffected.
Default to Company Metadata: If all user-specific metadata is deleted, the user will still retain any applicable company metadata by default.

Hard Delete A User

This endpoint fully deletes a user's information from the platform, including all data related to user groups. It ensures complete removal of all associated information.

curl https://api.northgravity.com/mgmt/pipeline/execute/{pipeline-id} \
  -d '{
      "details": {
          "delete_user_email": "userEmail"
      }
  }'

If successful, the above command returns status code 200, otherwise please check Errors section.

HTTP Request

POST https://api.northgravity.com/mgmt/pipeline/execute/{pipeline-id}

Important Notes

The {pipeline-id} for the user-hard-delete pipeline can be retrieved from pipeline management interface.

Transfer User's Ownership

This endpoint transfers user ownership on the platform to a target user and then fully deletes the current user and user's information, including all data related to user groups.

curl https://api.northgravity.com/mgmt/pipeline/execute/{pipeline-id} \
  -d '{
      "details": {
          "current_user_email": "userEmail",
          "target_user_email": "userEmail"
      }
  }'

If successful, the above command returns status code 200, otherwise please check Errors section.

HTTP Request

POST https://api.northgravity.com/mgmt/pipeline/execute/{pipeline-id}

Important Notes

The {pipeline-id} for the user-ownership-transfer pipeline can be retrieved from pipeline management interface.

Activate A User

This endpoint validates an email address and returns a token that can be used to change a password for an activated user.

curl https://api.northgravity.com/auth/activate/token_from_received_email

If successful, the above command returns status code 200, otherwise please check Errors section.

{
    "email": "email of user",
    "token": "NG access token that can be used to change password"
}

HTTP Request

POST https://api.northgravity.com/auth/activate

Change password

This endpoint change a password of user. Change password has to be done after account creation to finish the registration proccess.

curl -X POST
  https://api.northgravity.com/auth/changePassword
  -d '{
      "password": "new user password"
    }'

If successful, the above command returns status code 200, otherwise please check Errors section.

HTTP Request

POST https://api.northgravity.com/auth/changePassword

Request Body

Parameter	Description
password	new user password

Log in

This endpoint returns a jwt access token and a refresh token. When access token is expired, refresh token can be used to generate a new one. Access tokens are used to validate requests to NorthGravity API.

curl -u 'login:password' 
  https://api.northgravity.com/auth/login

If successful, the above command returns a status code 200 and token, otherwise please check Errors section.

{
    "token": "your access token",
    "refreshToken": "your refresh token"
}

HTTP Request

GET https://api.northgravity.com/auth/login

Request Body

Parameter	Description
userName	userName of account
password	password of account

Refresh Access Token

This endpoint returns a new access token.

curl -X POST
  https://api.northgravity.com/auth/refresh
  -d '{
    "refreshToken": "your refresh token"
    }'

If successful, the above command returns a status code 200 and token, otherwise please check Errors section.

{
    "token": "your access token",
    "refreshToken": "your refresh token"
}

HTTP Request

POST https://api.northgravity.com/auth/refresh

Request Body

your refresh token

Log out

Log out the user by invalidating the refresh token.

curl -X POST
  https://api.northgravity.com/auth/logout
  -H "Authorization: Bearer yourAccessToken"
  -d '{
    "refreshToken": "your refresh token"
    }'

If successful, the above command returns status code 200, otherwise please check Errors section.

HTTP Request

POST https://api.northgravity.com/auth/logout

This endpoint shares a group / file or symbol.

curl -X POST
  https://api.northgravity.com/auth/share
  -H "Authorization: Bearer yourAccessToken"
  -d '{
        "shares":[
          {
            "email": "user email to share with",
            "groupName": "Group",
            "access": "RWS"
          },
          {
            "email": "user to share with",
            "groupName": "Group",
            "fileName": "file name",
            "access": "RWS"
          },
          {
            "email": "user to share with",
            "groupName": "Group",
            "uuid": "file uuid",
            "access": "RWS",
            "dataStart": "2021-10-01T12:00:00",
            "dataEnd": "2021-10-10T12:00:00",
            "timeZone": "Europe/Warsaw"
          },
          {
            "email": "user to share with",
            "groupName": "Group",
            "symbols": {
              "field1": "value",
              "field2": "value",
              "access": "RWS"
            },
            "access": "RWS"
          }
        ]
      }'

If successful, the above command returns a status code 200, otherwise please check Errors section.

HTTP Request

POST https://api.northgravity.com/auth/share

Request Body

Parameter	Description
email	user email to share with
groupName	A group to share
fileName	A file name to share
uuid	A file uuid to share
symbols	A symbol to share
access	first letters of Read Write Share
dataStart	date which restrict range of shared data. Can be use only with group. Apply effect on data in timeseries and file in datalake. Files need to have defined metadata "dataStart" and "dataEnd" (date of data start and end in milliseconds)
dataEnd	date which restrict range of shared data. Can be use only with group. Apply effect on data in timeseries and file in datalake. Files need to have defined metadata "dataStart" and "dataEnd" (date of data start and end in milliseconds)
timeZone	time zone with you want to apply to dataStart and dataEnd. If you leave this empty, then we will use UTC

This endpoint removes sharing of the group / file or symbol.

curl -X DELETE
  https://api.northgravity.com/auth/share
  -H "Authorization: Bearer yourAccessToken"
  -d '{
        "shares":[
          {
            "email": "user email to share with",
            "groupName": "Group",
            "access": "RWS"
          },
          {
            "email": "user to share with",
            "groupName": "Group",
            "fileName": "file name",
            "access": "RWS"
          },
          {
            "email": "user to share with",
            "groupName": "Group",
            "uuid": "file uuid",
            "access": "RWS"
          },
          {
            "email": "user to share with",
            "groupName": "Group",
            "symbols": {
              "field1": "value",
              "field2": "value",
              "access": "RWS"
            },
            "access": "RWS"
          }
        ]
      }'

If successful, the above command returns a status code 200, otherwise please check Errors section.

HTTP Request

DELETE https://api.northgravity.com/auth/share

Request Body

Parameter	Description
email	user email to share with
groupName	A group to share
fileName	A file name to share
uuid	A file uuid to share
symbols	A symbol to share

This endpoint returns a list of users who shares a group / file or symbol.

curl https://api.northgravity.com/auth/share/user?groupName=COT&fileName=ags_cot load - suppl.csv
  -H "Authorization: Bearer yourAccessToken"

If successful, the above command returns a status code 200, otherwise please check Errors section.

HTTP Request

GET https://api.northgravity.com/auth/share/user/?groupName=groupNameWichYouWantToCheck

Request Parameters

Parameter	Description
groupName	group name
fileName	file name
uuid	file uuid
symbols	symbol

List of users emails which are in the same company as user

This endpoint returns a list of email which are in the same company as user.

curl https://api.northgravity.com/auth/company/emails?from=0&size=20&query=text
  -H "Authorization: Bearer yourAccessToken"

If successful, the above command returns a status code 200 and JSON object with a list of emails, otherwise please check Errors section.

HTTP Request

GET https://api.northgravity.com/auth/company/emails?from=0&size=20&query=text

Request Parameters

Parameter	Description
from	Index where list starts, used to load data in chunks. Default value is 0.
size	Number of records to return. Max size is 1000. Default size is 100.
query	User query string. By default will return all results.

HTTP Response

The response is a JSON object with a list of emails.

{
    "from": 0,
    "totalSize": -1,
    "items": [
        "sample.email@gmail.com",
        ...
    ]
}

List of users

This endpoint returns a list users.

curl https://api.northgravity.com/auth/user?from=0&size=20
  -H "Authorization: Bearer yourAccessToken"

If successful, the above command returns a status code 200 and JSON object with a list of users, otherwise please check Errors section.

HTTP Request

GET https://api.northgravity.com/auth/user?from=0&size=20

Request Parameters

Parameter	Description
from	Index where list starts, used to load data in chunks. Default value is 0.
size	Number of records to return. Max size is 1000. Default size is 100.
query	User query string. By default will return all results.

HTTP Response

The response is a JSON object with a list of emails.

{
    "from": 0,
    "totalSize": 34,
    "items": [
        {
            "companyName": "NorthGravity",
            "email": "testUser",
            "status": "ACTIVE"
        },
        ...
    ]
}

List roles

curl -X GET
  https://api.northgravity.com/auth/role
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns list of roles.

HTTP Request

GET https://api.northgravity.com/auth/role

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 2, "items": [ { "egId": 1, "name": "User role", "description": "Default", "type": "REGULAR" }, { "egId": 2, "name": "Default role", "description": "Default", "type": "REGULAR" } ] }

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Create role

This endpoint creates an empty role. shell curl -X POST https://api.northgravity.com/auth/role -d '{ "name": "Unique, can not be blank", "description": "Can not be blank. 3 to 255 characters." }'

HTTP Request

POST https://api.northgravity.com/auth/role

Request Body

Parameter	Description	required
name	name of role	yes (unique)
description	description of role	yes (3-255 characters)

HTTP Response

If successful, the above command returns status code 200, otherwise please check Errors section.

{
    "id": 1
}

Update role

This endpoint updates an existing role. shell curl -X POST https://api.northgravity.com/auth/role/{roleId} -d '{ "name": "Unique, can not be blank", "description": "Can not be blank. 3 to 255 characters." }'

HTTP Request

POST https://api.northgravity.com/auth/role/{roleId}

Request Body

Parameter	Description	required
name	name of role	yes (unique)
description	description of role	yes (3-255 characters)

HTTP Response

If successful, the above command returns status code 200, otherwise please check Errors section.

{
    "id": 1
}

URL Parameters

Parameter	Description
roleId	id of the existing role

Delete role

This endpoint remove an existing role. The role has to be of type REGULAR and it can not have users assign to it. shell curl -X DELETE https://api.northgravity.com/auth/role/{roleId} -H "Authorization: Bearer yourAccessToken"

HTTP Request

DELETE https://api.northgravity.com/auth/role{id}

URL Parameters

Parameter	Description
roleId	id of the existing role

HTTP Response

If successful, the above command returns status code 200

Describe role

curl -X GET
  https://api.northgravity.com/auth/role/{id}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns role description.

HTTP Request

GET https://api.northgravity.com/auth/role/{id}

HTTP Response

If successful, the above command returns status code 200 json { "role": { "egId": 77, "name": "test name", "description": "test description", "type": "REGULAR" }, "apis": { "from": 0, "totalSize": 1, "items": [ { "id": 1, "path": "", "method":"", "resource":"", "type":"" } ] }, "files": { "from": 0, "totalSize": 1, "items": [ { "fileId": 1, "fileName": "", "groupName":"", "access":"" } ] }, "groups": { "from": 0, "totalSize": 1, "items": [ { "id": 1, "groupId": 1, "groupName":"", "access":"", "dataStart": "2021-10-01T12:00:00.000", "dataEnd": "2021-10-10T12:00:00.000", "timeZone": "Europe/Warsaw" } ] }, "symbols": { "from": 0, "totalSize": 1, "items": [ { "groupName": "Test", "symbols": { "Origin": "UAE", "Destination": "TUN", "Commodity": "RSM", "TermDate Month": "1", "TermDate Year": "2017" }, "metadata": {}, "access": "RW" } ] }, "ui": { "from": 0, "totalSize": 1, "items": [ { "id": 12, "component": "Storage", "access": "RW" } ] }, "owners": { "from": 0, "totalSize": 1, "items": [ { "id": 1, "ownerUser": 1, "ownerCompany": 1, "ownerUserName": "", "ownerCompanyName": "", "access": "" } ] }, "users": { "from": 0, "totalSize": 1, "items": [ { "userId": 1, "userName": "user@northgravity.com" } ] }, "entitlementTags": { "from": 0, "totalSize": 1, "items": [ { "id": 1, "tagName": "entitlementTag1" } ] } }

URL Parameters

Parameter	Description
id	Role id

Api entitlements for role

curl -X GET
  https://api.northgravity.com/auth/role/api/{id}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns api to which role has access to.

HTTP Request

GET https://api.northgravity.com/auth/role/api/{id}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "id": 1, "path": "", "method":"", "resource":"", "type":"" } ] }

URL Parameters

Parameter	Description
id	Role id

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Files entitlements for role

curl -X GET
  https://api.northgravity.com/auth/role/files/{id}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns files to which role has access to.

HTTP Request

GET https://api.northgravity.com/auth/role/files/{id}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "fileId": 1, "fileName": "", "groupName":"", "access":"" } ] }

URL Parameters

Parameter	Description
id	Role id

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Groups entitlements for role

curl -X GET
  https://api.northgravity.com/auth/role/groups/{id}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns groups to which role has access to.

HTTP Request

GET https://api.northgravity.com/auth/role/groups/{id}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "id": 1, "groupId": 1, "groupName":"", "access":"" } ] }

URL Parameters

Parameter	Description
id	Role id

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Symbols entitlements for role

curl -X GET
  https://api.northgravity.com/auth/role/symbols/{id}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns symbols to which role has access.

HTTP Request

GET https://api.northgravity.com/auth/role/symbols/{id}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "groupName": "Test", "symbols": { "Origin": "UAE", "Destination": "TUN", "Commodity": "RSM", "TermDate Month": "1", "TermDate Year": "2017" }, "metadata": {}, "access": "RW" } ] }

URL Parameters

Parameter	Description
id	Role id

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Multiple symbols entitlement to role

curl -X POST
  https://api.northgravity.com/auth/role/multisymbols/{role_id}
  -d '{
        "symbols": [
          {
            "symbol: {
              "key": ["value", "value1"]
            },
            "metadata": {
              "key": ["value", "value1"]
            },
            "groupId": 1,
            "access": "R"
          }
        ]
      }'
  -H "Authorization: Bearer yourAccessToken"

This endpoint is adding the multiple symbols entitlement to given role.

HTTP Request

POST https://api.northgravity.com/auth/role/multisymbols/{id}

Request Body

Endpoint is getting a list of "multiple symbols entitlement" definitions. Each object in symbols list is one entitlement.

symbol (optional) - map of symbol definition. key is a symbol column name and defining to which symbols user will have access. The logical relation is that user will see symbols which have key name with values: value OR value1
metadata (optional) - the same rules as for symbol field
groupID (optional) - id of the group
access (required) - R - read only

The logical relation between fields symbol, metadata and groupId is AND. This means that if all fields are filled symbols have to meet all of the requirements.

Following example will give read access to the all symbols from groupId: 12 which have: * in symbol definition column Symbol with value USD_CHF AND * metadata column named currency with value USD json { "symbols": [ { "symbol": { "Symbol": ["USD_CHF"] }, "metadata": { "currency": ["USD"] }, "groupId": 12, "access": "R" } ] }

Following example will give read access to the all symbols IN THE SYSTEM (no groupId specified) which have: * metadata column named currency with value USD json { "symbols": [ { "metadata": { "currency": ["USD"] }, "access": "R" } ] }

Following example will give read access to the all symbols IN THE SYSTEM (no groupId specified) which have: * metadata column named currency. json { "symbols": [ { "metadata": { "currency": ["*"] }, "access": "R" } ] }

HTTP Response

If successful, the above command returns status code 204

Role owners

curl -X GET
  https://api.northgravity.com/auth/role/owners/{id}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns owners of role.

HTTP Request

GET https://api.northgravity.com/auth/role/owners/{id}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "id": 1, "ownerUser": 1, "ownerCompany": 1, "ownerUserName": "", "ownerCompanyName": "", "access": "" } ] }

URL Parameters

Parameter	Description
id	Role id

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

UI entitlements

curl -X GET
  https://api.northgravity.com/auth/role/ui/{id}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns ui entitlements for role.

HTTP Request

GET https://api.northgravity.com/auth/role/ui/{id}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "id": 12, "component": "Storage", "access": "RW" } ] }

URL Parameters

Parameter	Description
id	Role id

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Users with role

curl -X GET
  https://api.northgravity.com/auth/role/users/{id}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns users attached to role.

HTTP Request

GET https://api.northgravity.com/auth/role/users/{id}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "userId": 32, "userName": "marcin.szczuka@northgravity.com" } ] }

URL Parameters

Parameter	Description
id	Role id

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Get user symbols

curl -X GET
  https://api.dev.northgravity.com/auth/user/symbols/{email}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns user symbols.

HTTP Request

https://api.dev.northgravity.com/auth/user/symbols/{email}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "groupName": "CTP Test", "symbols": { "Origin": "UAE", "Destination": "TUN", "Commodity": "RSM", "TermDate Month": "1", "TermDate Year": "2017" }, "metadata": {}, "access": "RW" } ] }

URL Parameters

Parameter	Description
email	user email/name

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Get user groups

curl -X GET
  https://api.dev.northgravity.com/auth/user/groups/{email}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns user groups.

HTTP Request

https://api.dev.northgravity.com/auth/user/groups/{email}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "id": 1, "groupId": 1, "groupName":"", "access":"" } ] }

URL Parameters

Parameter	Description
email	user email/name

Query Parameters

Parameter	Description
size	size of response
from	pagination parameter

Store credentials

This endpoint stores credentials to third party services like private docker repositories etc.

curl -X POST https://api.northgravity.com/auth/credentials/create
  -d '{
        "credentialsName": "",
        "login": "",
        "password": ""
      }'

If successful, the above command returns status code 200, otherwise please check Errors section.

{
    "id": 1
}

HTTP Request

POST https://api.northgravity.com/auth/credentials/create

Request Body

Parameter	Description	required
credentialsName	name of credentials	yes
login	login	yes
password	password	yes

List credentials

This endpoint retrieve list of credentials to third party services like private docker repositories etc.

curl -X GET https://api.northgravity.com/auth/credentials

If successful, the above command returns status code 200, otherwise please check Errors section.

{
    "from": 0,
    "totalSize": 2,
    "items": [
        {
            "id": 1,
            "name": ""
        },
        {
            "id": 2,
            "name": ""
        }
    ]
}

HTTP Request

GET https://api.northgravity.com/auth/credentials/{id}

Retrieve credentials by id

This endpoint retrieve list of credentials to third party services like private docker repositories etc.

curl -X GET https://api.northgravity.com/auth/credentials/{id}

If successful, the above command returns status code 200, otherwise please check Errors section.

{
    "id": 1,
    "name": "",
    "arn": ""
}

HTTP Request

GET https://api.northgravity.com/auth/credentials/{id}

Request path parameters

Parameter	Description	required
id	credentials id	yes

Create entitlement tag

This endpoint creates new entitlement tag.

curl -X POST https://api.northgravity.com/auth/enttag
  -H "Authorization: Bearer yourAccessToken"
  -d '{
    "tagName": "et1"
}'

If successful, the above command returns status code 201

{
  "entitlementTagId": 1
}

HTTP Request

POST https://api.northgravity.com/auth/enttag

Request Body

Parameter	Description	required
tagName	name of entitlement tag	yes

Delete entitlement tag

This endpoint deletes an entitlement tag.

curl -X DELETE https://api.northgravity.com/auth/enttag/{entTagName}
  -H "Authorization: Bearer yourAccessToken"

If successful, the above command returns status code 200. If tag didn't exist before method execution it will also return 200

HTTP Request

DELETE https://api.northgravity.com/auth/enttag/{entTagName}

URL parameters

Parameter	Description	required
entTagName	name of entitlement tag	yes

Get entitlement tag

This endpoint returns an entitlement tag with its id.

curl -X GET https://api.northgravity.com/auth/enttag/{entTagName}
  -H "Authorization: Bearer yourAccessToken"

{
    "id": 1,
    "tagName": "entitlementTag1"
}

If successful, the above command returns status code 200

HTTP Request

GET https://api.northgravity.com/auth/enttag/{entTagName}

URL parameters

Parameter	Description	required
entTagName	name of entitlement tag	yes

Get entitlement tag

This endpoint searches for entitlement tags. This method performs search only on entitlement tags names.

curl -X GET https://api.northgravity.com/auth/enttag/search?query=*nameToSearch*
  -H "Authorization: Bearer yourAccessToken"

{
  "from": 0,
  "totalSize": 1,
  "items": [
    {
      "id": 7,
      "tagName": "entitlementTag7"
    }
  ]
}

If successful, the above command returns status code 200

HTTP Request

GET https://api.northgravity.com/auth/enttag/search?query=*

Query Parameters

Parameter	Description
from	Index where list starts, used to load data in chunks. Default value is 0.
size	Number of records to return. Max size is 1000. Default size is 100.
query	User query string. By default will return all results.

Get entitlement tags in role

curl -X GET https://api.northgravity.com/auth/enttag/role/{roleId}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns entitlement tags assigned to a role.

HTTP Request

GET https://api.northgravity.com/auth/enttag/role/{roleId}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 1, "items": [ { "id": 1, "tagName": "entitlementTag1" } ] }

URL Parameters

Parameter	Description	required
roleId	Id of a role	yes

Query Parameters

Parameter	Description
from	Index where list starts, used to load data in chunks. Default value is 0.
size	Number of records to return. Max size is 1000. Default size is 100.

Get entitlement tags assigned to user

curl -X GET https://api.northgravity.com/auth/enttag/user/{userId}
  -H "Authorization: Bearer yourAccessToken"

This endpoint returns entitlement tags assigned to user.

HTTP Request

GET https://api.northgravity.com/auth/enttag/user/{userId}

HTTP Response

If successful, the above command returns status code 200 json { "from": 0, "totalSize": 3, "items": [ { "id": 1, "tagName": "entitlementTag1" }, { "id": 2, "tagName": "entitlementTag2" } ] }

URL Parameters

Parameter	Description	required
userId	Id of a user	yes

Query Parameters

Parameter	Description
from	Index where list starts, used to load data in chunks. Default value is 0.
size	Number of records to return. Max size is 1000. Default size is 100.

Assign entitlement tags to a role

This endpoint assigns a set of entitlement tags to a role. This method will overwrite any entitlement tags already assigned to a role with entitlement tags from request body.

curl -X PUT https://api.northgravity.com/auth/role/{roleId}/enttag
  -H "Authorization: Bearer yourAccessToken"
  -d '{
    "entTagNames": ["entitlementTag1", "entitlementTag2"]
}'

If successful, the above command returns status code 200

HTTP Request

PUT https://api.northgravity.com/auth/{roleId}/enttag

Request path parameters

Parameter	Description	required
roleId	Id of a role	yes

Request Body

Parameter	Description	required
entTagNames	set of entitlement tags names	yes

Remove entitlement tags from a role

This endpoint removes a set of entitlement tags from a role.

curl -X DELETE https://api.northgravity.com/auth/role/{roleId}/enttag
  -H "Authorization: Bearer yourAccessToken"
  -d '{
    "entTagNames": ["entitlementTag1", "entitlementTag2"]
}'

If successful, the above command returns status code 200

HTTP Request

DELETE https://api.northgravity.com/auth/{roleId}/enttag

Request path parameters

Parameter	Description	required
roleId	Id of a role	yes

Request Body

Parameter	Description	required
entTagNames	set of entitlement tags names	yes

Add entitlement tags to a role

This endpoint adds a set of entitlement tags to a role. This method will not overwrite entitlement tags already assigned to a role. It will only add new ones from request body to existing set.

curl -X PATCH https://api.northgravity.com/auth/role/{roleId}/enttag
  -H "Authorization: Bearer yourAccessToken"
  -d '{
    "entTagNames": ["entitlementTag1", "entitlementTag2"]
}'

If successful, the above command returns status code 200

HTTP Request

PATCH https://api.northgravity.com/auth/{roleId}/enttag

Request path parameters

Parameter	Description	required
roleId	Id of a role	yes

Request Body

Parameter	Description	required
entTagNames	set of entitlement tags names	yes

File Groups

Create a File Group

curl -X POST
  https://api.northgravity.com/file/group
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json"
  -d '{
      "name":"example group name", 
      "description":"group description", 
      "tags":[
        {
          "tagId":[0|someTagId],
          "name":"tag name"
        },
        {
          "tagId": [0|someTagId2],
          "name":"tag name 2"
        }
      ],
      "fields":[
        {
          "name": "field name", 
          "type": "field type [string|int|float|date|array]"
        },
        {
          "name": "field name 2", 
          "type": "field type 2 [string|int|float|date|array]",
          "defaultValue": "value"
        },
                    ...
      ] 
  }'

If successful, the above command returns status code 201, otherwise please check Errors section.

This endpoint creates a new file group.

HTTP Request

POST https://api.northgravity.com/file/group

Request Body

Name	Type	Description	Optional
name	string	Name of the group to create, between 3 and 100 characters.	No
description	string	Description of the group, up to 5000 characters.	Yes
tags	Array<Object>	Tags used for faster searching of created groups.	Yes
└─ tagId	number	Tag ID. Use `0` to create a new tag, otherwise provide an existing tag’s ID.	No(if tag added)
└─ name	string	Tag name, between 2 and 30 characters.	No(if tag added)
fields	Array<Object>	Metadata fields for the group, defined with: `name`, `type`, `defaultValue`.	Yes
└─ name	string	Name of metadata field.	No(if field added)
└─ type	string	Metadata type: [ string / int / float / date / date_milliseconds / array ]	No(if field added)
└─ defaultValue	string	Value of metadata field.	Yes

You can define a timeframe for the data contained in this group. When enabled, the system will return only timeseries data that falls within the defined timeframe. The constraint is applied when two metadata fields are added with the type date_milliseconds and the names dataStart and dataEnd.

Update a File Group

curl -X PATCH
  https://api.northgravity.com/file/group/exampleGroup
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json"
  -d '{
      "description":"group description", 
      "tags":[
        {
          "tagId":[0|someTagId],
          "name":"tag name"
        },
        {
          "tagId": [0|someTagId2],
          "name":"tag name 2"
        }
      ],
      "inheritTags": [true|false],
      "fields":[
        {
          "name": "field name", 
          "type": "field type [string|int|float|date|array]"
        },
        {
          "name": "field name 2", 
          "type": "field type 2 [string|int|float|date|array]",
          "defaultValue": "value"
        },
                    ...
      ] 
    }'

If successful, the above command returns status code 200, otherwise please check Errors section.

This endpoint changes a file group description or fields. If you need to change only one or a few fields, you must not provide all the fields.

HTTP Request

PATCH https://api.northgravity.com/file/group/{name}

URL Parameters

Parameter	Description	Optional
name	Name of the group to retrieve	No

Request Body

Name	Type	Description	Optional
description	string	Description of the group, up to 5000 characters.	Yes
tags	Array<Object>	Tags used for faster searching of created groups.	Yes
└─ tagId	number	Tag ID. Use `0` to create a new tag, otherwise provide an existing tag’s ID.	No(if tag added)
└─ name	string	Tag name, between 2 and 30 characters.	No(if tag added)
fields	Array<Object>	Metadata fields for the group, defined with: `name`, `type`, `defaultValue`.	Yes
└─ name	string	Name of metadata field.	No(if field added)
└─ type	string	Metadata type: [ string / int / float / date / date_milliseconds / array ]	No(if field added)
└─ defaultValue	string	Value of metadata field.	Yes
publicView	boolean	If `true` group becomes accessible for every user. Default: `false`	Yes

Get a Specific File Group By Name

curl https://api.northgravity.com/file/group/exampleGroup
    -H "Authorization: Bearer yourNgToken"

If successful, the above command returns JSON with code 200:

{
  "groupId": 12345,
  "name": "example group name",
  "description": "example description",
  "createTime": 1234567890,
  "fields": [
    {
      "name": "field name",
      "type": "field type [string|int|float|date|array]"
    },
    {
      "name": "field name 2",
      "type": "field type 2 [string|int|float|date|array]",
      "defaultValue": "field value"
    }
  ],
  "owner": "example.owner@company.com",
  "publicView": false,
  "access": "group access level [R|W|S], sample: R",
  "shared": false,
  "removed": false
}

This endpoint retrieves a specific file group.

HTTP Request

GET https://api.northgravity.com/file/group/{name}

URL Parameters

Parameter	Description	Optional
name	Name of the group to retrieve	No

Get a Specific File Group By Name

curl https://api.northgravity.com/file/group/id/12345
    -H "Authorization: Bearer yourNgToken"

If successful, the above command returns JSON with code 200:

{
  "groupId": 12345,
  "name": "example group name",
  "description": "example description",
  "createTime": 1234567890,
  "fields": [
    {
      "name": "field name",
      "type": "field type [string|int|float|date|array]"
    },
    {
      "name": "field name 2",
      "type": "field type 2 [string|int|float|date|array]",
      "defaultValue": "field value"
    }
  ],
  "owner": "example.owner@company.com",
  "publicView": false,
  "access": "group access level [R|W|S], sample: R",
  "shared": false,
  "removed": false
}

This endpoint retrieves a specific file group.

HTTP Request

GET https://api.northgravity.com/file/group/id/{id}

URL Parameters

Parameter	Description	Optional
id	Id of the group to retrieve	No

List all File Groups

curl https://api.northgravity.com/file/group?from=0&size=1&query=value1&writeOnly=false&sortBy=name&sortOrder=asc&publicView=false
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns JSON with code 200:

{
  "from": 0,
  "totalSize": 100,
  "items": [
    {
      "groupId": 12345,
      "name": "example group name",
      "description": "example description",
      "createTime": 1234567890,
      "fields": [
        {
          "name": "field name",
          "type": "field type [string|int|float|date|array]"
        },
        {
          "name": "field name 2",
          "type": "field type 2 [string|int|float|date|array]",
          "defaultValue": "field value"
        }
      ],
      "owner": "example.owner@company.com",
      "publicView": false,
      "access": "group access level [R|W|S], sample: R",
      "shared": false,
      "removed": false
    }
  ]
}

This endpoint executes a search for groups with given name and specific flags for group like write access or having symbols.

HTTP Request

GET https://api.northgravity.com/file/group

URL Parameters

Parameter	Description	Optional
from	Index where list starts. Default value is `0`.	Yes
size	Number of records to return. Default size is `100`.	Yes
query	Use plain text for generic results, or filters (key=value joined with &) for more specific searches. The wildcard `*` is supported.	Yes
writeOnly	If `true`, only groups to which user has write access are returned.	Yes
withSymbol	If `true`, only groups which have some symbols are returned.	Yes
publicView	If `true`, only public groups are returned.	Yes
sortBy	Field by which the results will be sorted. Either `createdOn` or `arrivalTime`. Default: `createdOn`.	Yes
sortOrder	Sort order: `asc` for ascending, `desc` for descending. Defult order is descending.	Yes

Delete a Specific File Group

curl -X DELETE
  https://api.northgravity.com/file/group/exampleGroup
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns code 200.

This endpoint deletes a specific file group.

HTTP Request

DELETE https://api.northgravity.com/file/group/{name}

URL Parameters

Parameter	Description
name	Name of the file group to delete

File Upload

Upload File

File uploading has two steps:

First step is a File Metadata Posting:

First step:

curl -X POST
  https://api.northgravity.com/file
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
        "groupName":"ExampleGroup",
        "fileName":"exampleFile.csv",
        "fileType":"SOURCE",
        "zipped": false,
        "fields":[
                {
                    "name":"String field",
                    "value":"test"
                },
                {
                    "name":"Integer field",
                    "value":"1"
                },
                {
                    "name":"Float field",
                    "value":"1.1"},
                {
                    "name":"Date field",
                    "value":"2017-09-05"
                }
                ...
        ]
     }'

If successful, the above command returns status code 201 and example json as below, otherwise please check Errors section.

{
  "location": "locationAddressToUploadFileContent",
  "fileId": "someFileId"
}

This endpoint stores the file metadata and returns a location to PUT the file content. If the file group requires metadata for the uploaded file, you can override default values and provide values for metadata fields that require values. On creation the call returns a 'location', you must PUT the file content to this location.

HTTP Request

POST https://api.northgravity.com/file

Request Body

Name	Type	Description	Optional
groupName	string	Group where file is saved.	No
fileName	string	Name of file.	No
fields	Array<Object>	Fields with file metadata.	Yes
└─ name	string	Name of metadata field.	No(if field added)
└─ value	string	Value of metadata field.	No(if field added)
zipped	boolean	If `true` file is saved in zip archive on datalak. Default: `false`	Yes
fileType	string (enum)	Type of file. Defines possible operations on file. Options: [ SOURCE / NCSV / D_NCSV / CONFIG / UICONFIG / INSIGHT ]. Default: `SOURCE`	Yes

HTTP Response

Response:

{
  "location": "https://fileUploadURL",
  "fileId": "file id"
}

A JSON object is returned with an url to upload a file content.

Second step is File Uploading:

This endpoint saves the file content in the datalake group. You will need a file on your machine. Using bash for command line tool, navigate to the directory where your file is located. You should use the 'location' link for the file from the first step response body.

Use --data-binary body option to select file from your local machine:

curl -X PUT --data-binary @"file-name.csv"
   https://fileUploadURLFromFirstStep

If successful, the above command returns status code 200.

When you want to create file from hand you can also use the following example, where file content is provided in the body:

curl -X PUT https://fileUploadURLFromFirstStep
  --H "Content-Type: application/json"
  -d '{
    "field1":"value1","field2":"value2"
  }'

HTTP Request

PUT https://fileUploadURL

Update Metadata for a File

curl -X PUT
  https://api.northgravity.com/file/exampleFileId
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
        "fileName":"test.csv",
        "fileType":[SOURCE|NCSV|D_NCSV|CONFIG|UICONFIG|DATA_PREP|GDP|INSIGHT|TASK],
        "fields":[
                {
                    "name":"String field",
                    "value":"test"
                },
                {
                    "name":"Integer field",
                    "value":"1"
                },
                {
                    "name":"Float field",
                    "value":"1.1"},
                {
                    "name":"Date field",
                    "value":"2017-09-05"
                }
                ...
        ],
        "replaceFields": false
     }'

If successful, the above command returns status code 200.

This endpoint updates a file's metadata using the file ID.

HTTP Request

PUT https://api.northgravity.com/file/{fileId}

URL Parameters

Parameter	Description	Optional
fileId	The ID of the file to update	No

Request Body

Name	Type	Description	Optional
fileName	string	Name of file.	No
fileType	string (enum)	Type of file. Defines possible operations on file. Options: [ SOURCE / NCSV / D_NCSV / CONFIG / UICONFIG / INSIGHT ]. Default: `SOURCE`	Yes
fields	Array<Object>	Fields with file metadata.	Yes
└─ name	string	Name of metadata field.	No(if field added)
└─ value	string	Value of metadata field.	No(if field added)
replaceFields	boolean	If `true` file is saved in zip archive on datalak. Default: `false`	Yes

Get a File Content

curl https://api.northgravity.com/file/exampleFileId
  -H "Authorization: Bearer yourNgToken"

A response header contains location with a file content. If file doesn't exist, the response code is 404. If successful, the above command returns json with code 200:

{
  "fileName": "example File Name.csv",
  "fileType": "[SOURCE|NCSV|D_NCSV|CONFIG|UICONFIG|DATA_PREP|GDP|INSIGHT|TASK]",
  "groupName": "example group name",
  "groupId": groupId,
  "fid": "exampleFileId",
  "fields": {
    "field1": "value1",
    "field2": "value2"
  },
  "arrivalTime": "2026-01-08T14:05:37.000",
  "owner": "example.user@company.com",
  "size": 3476,
  "checkSum": "examplechecksumvalue1234567890",
  "zipped": false,
  "shared": false,
  "removed": false,
  "archived": false,
  "version": 1,
  "rootId": "exampleRootId",
  "jobId": "exampleJobId",
  "latest": true,
  "links": []
}

This endpoint retrieves metadata of a specific file.

HTTP Request

GET https://api.northgravity.com/file/{fileId}

URL Parameters

Parameter	Description	Optional
fileId	The ID of the file to retrieve	No

Get a File History

Example request to get the history of a file:

curl https://api.northgravity.com/file/history/exampleFileId
    -H "Authorization: Bearer yourNgToken"

If successful, request returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 1,
  "items": [
    {
      "fileName": "example File Name.csv",
      "fileType": "SOURCE",
      "groupName": "example group name",
      "groupId": groupId,
      "fid": "exampleFileId",
      "fields": {
        "field1": "value1",
        "field2": "value2"
      },
      "arrivalTime": "2026-01-08T14:15:39.403",
      "owner": "example.user@company.com",
      "size": 4349,
      "checkSum": "examplechecksumvalue1234567890",
      "zipped": false,
      "shared": false,
      "removed": false,
      "archived": false,
      "version": 2,
      "rootId": "exampleRootId",
      "jobId": "exampleJobId",
      "latest": true,
      "links": []
    },
    {
      "fileName": "example File Name.csv",
      "fileType": "SOURCE",
      "groupName": "example group name",
      "groupId": groupId,
      "fid": "exampleFileId",
      "fields": {
        "field1": "value1",
        "field2": "value2"
      },
      "arrivalTime": "2026-01-08T14:05:37.000",
      "owner": "example.user@company.com",
      "size": 3476,
      "checkSum": "examplechecksumvalue1234567890",
      "zipped": false,
      "shared": false,
      "removed": false,
      "archived": false,
      "version": 1,
      "rootId": "exampleRootId",
      "jobId": "exampleJobId",
      "latest": true,
      "links": []
    }
  ]
}

This endpoint retrieves metadata for all versions of file.

HTTP Request

GET https://api.northgravity.com/file/history/{id}

URL Parameters

Parameter	Description	Optional
id	File Id	No

Search Files

Example request with search for value of field:

curl https://api.northgravity.com/file/search?size=10&from=0&query=value1
    -H "Authorization: Bearer yourNgToken"

Example request for searching latest version of files only in group "exampleGroup":

curl https://api.northgravity.com/file/search?size=10&from=0&query=%26latest%3Dtrue%26groupName%3DexampleGroup
    -H "Authorization: Bearer yourNgToken"

If successful, request returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 4,
  "items": [
    {
      "fileName": "example File Name.csv",
      "fileType": "[SOURCE|NCSV|D_NCSV|CONFIG|UICONFIG|DATA_PREP|GDP|INSIGHT|TASK]",
      "groupName": "example group name",
      "groupId": groupId,
      "fid": "exampleFileId",
      "fields": {
        "field1": "value1",
        "field2": "value2"
      },
      "arrivalTime": "2026-01-08T14:05:37.000",
      "owner": "example.user@company.com",
      "size": 3476,
      "checkSum": "examplechecksumvalue1234567890",
      "zipped": false,
      "shared": false,
      "removed": false,
      "archived": false,
      "version": 1,
      "rootId": "exampleRootId",
      "jobId": "exampleJobId",
      "latest": true,
      "links": []
    }
    ...
  ]
}

This endpoint executes a search for files with given metadata fields and values, group names and file names.

HTTP Request

GET https://api.northgravity.com/file/search?size=<size>&from=<from>&query=<query>&withStatus=<withStatus>

URL Parameters Search Files

Parameter	Description	Optional
size	Index where list starts. Default value is `0`.	Yes
from	Number of records to return. Default size is `100`.	Yes
query	Use plain text for generic results, or filters (key=value joined with &) for more specific searches. The wildcard * is supported.	Yes
withStatus	If `true`adds status details to each result item. Only affects the response payload.	Yes
sortBy	Field by which the results will be sorted. Either `createdOn` or `arrivalTime`. Default: `createdOn`.	Yes
sortOrder	Sort order: `asc` for ascending, `desc` for descending. Defult order is descending.	Yes
tokenExpiration	Scroll keep-alive duration (e.g., '1m', '30s'). Leave blank to use normal offset paging.	Yes
nextPageToken	Scroll ID from the previous response. Use together with tokenExpiration to fetch the next page.	Yes

Search Insight Files

Example request for searching insight files:

curl https://api.northgravity.com/file/search/insight?size=10&from=0&query=insightFileName
    -H "Authorization: Bearer yourNgToken"

If successful, request returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 1,
  "items": [
    {
      "fileName": "example Insight File Name.csv",
      "fileType": "INSIGHT",
      "groupName": "example group name",
      "groupId": groupId,
      "fid": "exampleFileId",
      "fields": {
        "field1": "value1",
        "field2": "value2"
      },
      "arrivalTime": "2026-01-08T14:05:37.000",
      "owner": "example.user@company.com",
      "size": 3476,
      "checkSum": "examplechecksumvalue1234567890",
      "zipped": false,
      "shared": false,
      "removed": false,
      "archived": false,
      "version": 1,
      "rootId": "exampleRootId",
      "jobId": "exampleJobId",
      "latest": true,
      "links": []
    }
  ]
}

This endpoint executes a search for insight files with given metadata fields and values, group names and file names.

HTTP Request

GET https://api.northgravity.com/file/search/insight?query=<insightName>

URL Parameters

The URL parameters are the same as in the Search Files endpoint.

Download a Specific File

Example request for downloading files:

curl -X POST https://api.northgravity.com/file/exampleFileId/download
    -H "Authorization: Bearer yourNgToken"

If successful, request returns 200 code with file content in response body.

HTTP Request

GET https://api.northgravity.com/file/{id}/download

URL Parameters

Parameter	Description	Optional
id	The Id of file to download	No

Search Task Files

Example request for searching task files:

curl -X POST https://api.northgravity.com/file/search/tasks?active=true
    -H "Authorization: Bearer yourNgToken"
    -H "Content-Type: application/json" 
    -d '[
        {
            "taskGroup": "Core Tasks",
            "taskName": "task-file-copy",
            "taskVersion": "1.0.13"
        }
    ]'

If successful, request returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 1,
  "items": [
    {
      "fileName": "example_task_name.json",
      "fileType": "TASK",
      "groupName": "Tasks",
      "groupId": 12345,
      "fid": "someTaskFileId",
      "fields": {
        "description": "Example task description",
        "name": "Example Task Name",
        "image_url": "someImageUrl",
        "timeout": "500",
        "task_name": "example-name",
        "version": "1.0",
        "memory": "500",
        "category": "Example Category",
        "cpu": "1",
        "source": "CORE",
        "params": "[{\"name\":\"Example parameter\",\"description\":\"Example parameter description\",\"defaultValue\":\"\"}]",
        "Origin": "ETL"
      },
      "arrivalTime": "2022-02-10T18:57:56.000",
      "owner": "system",
      "size": 2048,
      "checkSum": "examplechecksumvalue1234567890",
      "zipped": false,
      "shared": false,
      "removed": true,
      "archived": false,
      "version": 1,
      "rootId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "latest": false
    }
  ]
}

This endpoint executes a search for tasks files with given metadata fields and values, group names and file names.

HTTP Request

GET https://api.northgravity.com/file/search/tasks?size=<size>&from=<from>&active=<active>

URL Parameters

Parameter	Description	Optional
size	Index where list starts. Default value is `0`.	Yes
from	Number of records to return. Default size is `100`.	Yes

Request Body

Request body is a JSON array of objects with the following structure:

Name	Type	Description	Optional
taskGroup	string	Name of group where task file is stored.	No
taskName	string	Name of task.	No
taskVersion	string	Version of task.	No

Delete a Specific File

curl -X DELETE
  https://api.northgravity.com/file/exampleFileId
    -H "Authorization: Bearer yourNgToken"

If successful, request returns 200 response code.

This endpoint deletes a specific file.

HTTP Request

DELETE https://api.northgravity.com/file/{fileId}

URL Parameters

Parameter	Description	Optional
fileId	The ID of the file to delete	No

Time Series

Search Time Series Symbols

curl https://api.northgravity.com/ts/symbol/search?query=<symbol>&sortBy=<sortFields>
-H "Authorization: Bearer yourAccessToken"

<symbol> collection of symbol field names and values separated by & sign, ex.
symbol.Country=USA&symbol.name=test

<sortFields> collection of fields to sort by asc or desc, ex.
symbol.Country=desc&symbol.name=asc

If successful, the above command returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      "groupName": "group name",
      "symbols": {
        "SYM1": "A1",
        "SYM2": "B1"
      },
      "metadata": [
        "meta 1",
        "meta 2"
      ],
      "values": [
        "val 1",
        "val 2"
      ],
      "entitlementTags": [
        "enttag1",
        "enttag2"
      ]
    },
    ...
  ]
}

This endpoint returns symbols for data stored in timeseries. The endpoint allows user to access a max of 10,000 symbols. If more symbols are needed please use the streaming api /ts/symbol/search/stream.

HTTP Request

GET https://api.northgravity.com/ts/symbol/search?query=<symbol>

URL Parameters

Parameter	Description	Optional
symbol	Name of the symbol to search.	No
size	The maximum size of returned hits list. Max size is 1000. Default size is 100.	Yes
from	The index of the first hit. It allows to do paging easily. Default value is 0.	Yes

Search Time Series Symbols In Groups

curl -X POST https://api.northgravity.com/ts/symbol/search/ingroup
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"
    -d '{
        "groupQueries": [
            { "groupName": "group name A", "query": "symbols.Country=USA" },
            { "groupName": "group name B", "query": "symbols.Currency=USD" }
        ]
    }'

If successful, the above command returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      "groupName": "group name A",
      "symbols": {
        "Currency": "USD"
      },
      "metadata": {},
      "values": [
        "Rate"
      ],
      "entitlementTags": [],
      "previewAccess": false
    },
    {
      "groupName": "group name B",
      "symbols": {
        "Country": "USA"
      },
      "metadata": {},
      "values": [],
      "entitlementTags": [],
      "previewAccess": false
    }
  ]
}

HTTP Request

POST https://api.northgravity.com/ts/symbol/search/ingroup

Request Body

Name	Type	Description	Optional
groupQueries	Array<Object>	List of group queries, each with `groupName` and `query` parameters.	No
└─ groupName	string	Name of the group to search in.	No
└─ query	string	Query string for symbol search e.g. `symbols.Country=USA` or `metadata.Destination=USA`	Yes

Search Time Series Symbols Stream

curl https://api.northgravity.com/ts/symbol/search/stream?query=<symbol>&sortBy=<sortFields>
-H "Authorization: Bearer yourAccessToken"

<symbol> collection of symbol field names and values separated by & sign, ex.
symbol.Country=USA&symbol.name=test

<sortFields> collection of fields to sort by asc or desc, ex.
symbol.Country=desc&symbol.name=asc

If successful, the above command returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      "groupName": "group name",
      "symbols": {
        "SYM1": "A1",
        "SYM2": "B1"
      },
      "metadata": [
        "meta 1",
        "meta 2"
      ],
      "values": [
        "val 1",
        "val 2"
      ]
    },
    ...
  ]
}

This endpoint returns symbols for data stored in timeseries. The endpoint allows user to access a max of 50,000 symbols with one call.

HTTP Request

GET https://api.northgravity.com/ts/symbol/search/stream?query=<symbol>

URL Parameters

Parameter	Description
symbol	Name of the symbol to search.

Delete Time Series Symbol

curl -X DELETE 
    https://api.northgravity.com/ts/symbol
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"    
    -d '{
        "groupName": "group name",
        "symbols": {
            "SYM1": "A1",
            "SYM2": "B1"
        }
    }'

If successful, the above command deletes symbols and returns code 200.

This endpoint deletes all data related with the given symbol.

HTTP Request

DELETE https://api.northgravity.com/ts/symbol

Request Body

Name	Type	Description	Optional
groupName	string	Name of the group containing symbols	No
symbols	object	Map of name-value pairs. Example: `{ "SYM1": "A1", "SYM2": "B1" }`, where `SYM1` is column name and `A1` is the column value.	No

Search Time Series Data

curl -X POST 
  https://api.northgravity.com/ts?size=5
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"
  -d '{
      "startDate": "2017-01-11T10:01:03",
      "endDate": "2017-12-11T10:01:03",
      "stats": "true",
      "timeZone": "America/New_York",
      "corrections": true,
      "onDateTime": "2018-12-01T10:01:03.999",
      "formatType": "STANDARD",
      "keys": [{
        "columns": ["Open", "Close", "High"],
        "symbols": {
          "SYM1": "A1",
          "SYM2": "B1"
        },
        "groupName": "fileGroupName",
        "timeZone": "America/Chicago",
        "pattern": true,
        "patternExactMatch": false
      }]
  }'

The above command returns JSON or CSV structured response. It depends on the header value and formatType variable in request

Standard format type:

{
  "hasNextPage": true,
  "nextPageToken": 1501218000000,
  "columns": [
    {
      "id": someColumnId,
      "symbols": {
        "SYM2": "B1",
        "SYM1": "A1"
      },
      "groupId": someGroupId,
      "groupName": "fileGroupName",
      "valueName": "Value",
      "valueType": "Allowed values: I, DB, DT, D, S, LS (metadata: MD-S, MD-I, MD-DB, MD-D, MD-DT). Example: DB"
    }
  ],
  "values": [
    {
      "time": "2018-01-01T12:00:00",
      "values": [
        14.1
      ]
    },
    ....
  ],
  "stats": [
    {
      "name": "count",
      "values": [
        20.0
      ]
    },
    ....
  ]
}

UI optimized format type:

{
  "hasNextPage": false,
  "columns": [
    {
      "otherValues": [
        "A2",
        "A3"
      ],
      "metadata": {
        "Description": "description and other metadata"
      },
      "symbols": {
        "State": "27",
        "County": "065"
      },
      "groupId": 457,
      "valueName": "A1",
      "offset": 0,
      "valueType": "DB",
      "zoneId": "Z",
      "fillType": "NONE"
    },
    {
      "otherValues": [
        "B2",
        "B3"
      ],
      "metadata": {
        "Description": "description and other metadata"
      },
      "symbols": {
        "State": "27",
        "County": "065"
      },
      "groupId": 457,
      "valueName": "B1",
      "offset": 0,
      "valueType": "DB",
      "zoneId": "Z",
      "fillType": "NONE"
    }
  ],
  "values": [
    {
      "{\"symbols\":{\"State\":\"27\",\"County\":\"065\"},\"valueName\":\"A1\"}": "8340.0",
      "timeMills": "1419984000000",
      "{\"symbols\":{\"State\":\"27\",\"County\":\"065\"},\"valueName\":\"B1\"}": "22",
      "time": "2014-12-31T00:00:00.000"
    },
    {
      "{\"symbols\":{\"State\":\"27\",\"County\":\"065\"},\"valueName\":\"A1\"}": "16000.0",
      "timeMills": "1483142400000",
      "{\"symbols\":{\"State\":\"27\",\"County\":\"065\"},\"valueName\":\"B1\"}": "144",
      "time": "2016-12-31T00:00:00.000"
    }
  ],
  "stats": [
    {
      "name": "options: [lastDataDate|std|mean|min|max|count|sum|25.0%|50.0%|75.0%|overallQuality|gaps|firstDataDate|10.0%|90.0%], example: std",
      "values": {
        "{\"symbols\":{\"State\":\"27\",\"County\":\"065\"},\"valueName\":\"A1\"}": 2336.733081727157,
        "{\"symbols\":{\"State\":\"27\",\"County\":\"065\"},\"valueName\":\"B1\"}": 0.0
      }
    },
    {
      "name": "options: [lastDataDate|std|mean|min|max|count|sum|25.0%|50.0%|75.0%|overallQuality|gaps|firstDataDate|10.0%|90.0%], example: min",
      "values": {
        "{\"symbols\":{\"State\":\"27\",\"County\":\"065\"},\"valueName\":\"A1\"}": 8340.0,
        "{\"symbols\":{\"State\":\"27\",\"County\":\"065\"},\"valueName\":\"B1\"}": 0.0
      }
    },
    ...
  ]
}

CSV format(by header):

Symbol Values,A1;B1;
Date(UTC),Open
2025-01-15T14:55:00.000,72.11,71.11
2025-01-15T10:21:00.000,83.11,82.11,81.11
2025-01-15T10:05:00.000,93.11,92.11,91.11
...

If patterns for symbols are provided in the request body, the 'pattern' value property should be set to true. In the example below, to enable filtering by SYM1 and SYM2:

"symbols": {
"SYM1": "A1",
"SYM2": "B1"
},
"pattern": true,
"patternExactMatch": false

It will return us symbolsLines which contain symbols matching the pattern, possibly with other symbols: (simplified response)

"symbols": {
"SYM1": "A1",
"SYM2": "B1"
}

"symbols": {
"SYM1": "A1",
"SYM2": "B1",
"SYM3": "C1"
}

If we want to receive symbolsLines which contain symbols matching the pattern exclusively, patternExactMatch: true should be used. In this case, for the above pattern only the first result is returned.

Wildcards "*" can also be used in patterns to make sure a symbolLine contain the given symbol key:

"symbols": {
"SYM1": "*",
"SYM2": "B1"
}

This endpoint retrieves timeseries data for specific symbols in the provided time range. If the symbols do not exist, column is not displayed.

HTTP Request

POST https://api.northgravity.com/ts?size=<size>

URL Parameters

Parameter	Description	Optional
nextPageToken	Token returned by last response to get next page of data	yes
size	Number of rows per page. Max size is 10 000. Default size is 10 000.	yes
order	Sort order: `ASC` for ascending, `DESC` for descending. Defult order is descending.	yes
omitNulls	If `true`, omits fields with null values from the response.	yes
absoluteSize	Number of records to skip	yes
symbolSize	Maximum number of symbols to return. Default size is 500.	yes
sortSymbols	Sorts symbols ascending by creation time. Special characters in symbol names must be URL-encoded (e.g., "SYM1=DA1" → "SYM1%3DA1"). Common encodings: "=", "*", "-".	yes

Request Body Ts

Name	Type	Description	Default	Optional
keys	Array<Object>	Array of key objects. Minimum 1 key is required. See Fields inside keys Ts for object structure.	null	No
startDate	string	Date (ISO 8601). Start of the date range. Results earlier than this date are excluded. Example: `"2025-09-01T00:00:00"`. Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	null	Yes
endDate	string	Date (ISO 8601). End of the date range. Results later than this date are excluded. Example: `"2025-09-02T00:00:00"`. Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	null	Yes
stats	boolean	Whether to include statistics. Statistics are included only if symbol values exist.	false	Yes
metadata	boolean	Whether to include symbol metadata.	false	Yes
metadataType	boolean	Whether to include metadata types when `dateFormat` is set to `"STANDARD"`.	false	Yes
corrections	string	If `"true"`, includes corrected(previous) values with timestamps (and insert time if `dateFormat` is `STANDARD`). If `"false"`, returns only the latest values.	false	Yes
delta	boolean	If `true`, the system first limits the search to symbols with relevant data for the specified range using insertion date. Then, the results can be filtered by transaction date (from the CSV file) using `deltaTransDateLimitType` and `deltaTransDateLimitAmount`. If `false`, no preliminary symbol filtering is applied, and the transaction date parameters are ignored.	false	Yes
deltaTransDateLimitType	string (enum)	Transaction date limit unit for delta. Options: [MINUTE / HOUR / DAY / WEEK / MONTH / YEAR ].	null	Yes
deltaTransDateLimitAmount	number	Time offset from the current time. The meaning of this value depends on `deltaTransDateLimitType` (e.g., if `"DAY"` value is in days). Negative values are allowed.	null	Yes
timeZone	string	Valid time zone name. Full list: Oracle Time Zone List	UTC	Yes
dateFormat	string	Format string for date values to return (e.g., "yyyy-MM-dd'T'HH:mm:ss.SSS")	null	Yes
formatType	string (enum)	Type of format returned by timeseries. Options: [STANDARD / CSV / PANDAS / NCSV]	STANDARD	Yes
fillEmptyFields	string	String representation of a numeric value used to fill empty fields (e.g., "1.5").	null	Yes
range	string (enum)	Search period type: [ ALL / BETWEEN / LAST / NEXT ]. See Parameter Range Ts for details.	BETWEEN	Yes
lastType	string (enum)	Options: [ MINUTE / HOUR / DAY / BUSINESS_DAY / MONTH / YEAR / YEAR_TO_DATE / VALUE]. Applied only when range is `"LAST"` or `"NEXT"`.	null	Yes
lastTypeAmount	number	Number of time units (like days) defined by the `lastType` parameter and is used to determine how far in the past or future a search range should extend — depending on whether `range` is LAST or NEXT. Searches for insert time in that range.	null	Yes
lastTypeOnDate	string	Range start date for `range`=`"LAST"` (yyyy-MM-dd).	current date	Yes
lastTypeOnTime	string	Range start time for `range`=`"LAST"` ("HH:mm:ss").	current time	Yes
lastTypeOnTimeTimezone	string	Valid time zone name applied to parameters `lastTypeOnDate` and `lastTypeOnTime`. Full list: Oracle Time Zone List	UTC	Yes
holidayCalendar	string	Name of the holiday calendar. Used with `lastType` = `"BUSINESS_DAY"` and range values like `"LAST"` or `"NEXT"` to skip non-business days. Example: a 9-day search may extend to 11 days if 2 days of holidays are encountered.	null	Yes
includeFileId	boolean	When formatType is `"STANDARD"`, set to true to include fileIds in the response.	false	Yes
decimalPrecision	string	Number of digits after the decimal point. "0" means no decimals; "n" means n digits.	1	Yes
roundingMode	string (enum)	Rounding mode options: [ UP / DOWN / CEILING / FLOOR / HALF_UP / HALF_EVEN]	HALF_UP	Yes
skipEmptyColumns	boolean	Skip empty columns and symbols, where columns are without values.	false	Yes
failOnMissingSymbols	boolean	Fail if there are missing symbols.	true	Yes
nonEmpty	boolean	If true, returns only entries that have both a column name and a corresponding value in dynamoDb search.	false	Yes
csvHeaders	Array<Object>	CSV header configuration list. Used only when `formatType` = `"CSV"`. See CSV Header Configuration for details.	null	Yes
onDateTime	string	Accepts either an ISO 8601 datetime format (yyyy-MM-dd'T'HH:mm:ss.SSS) or a date placeholder: yesterday, today, or tomorrow. Displays values for dates prior to the specified date.	null	Yes
isoDateTypes	boolean	Whether to return date or datetime types of columns as UTC instants or as ISO-formatted date/time strings (YYYY-MM-DD, YYYY-MM-DDTHH:mm:ss). If `true`, values remain in their original form.	false	Yes
withUtcOffset	boolean	If `true` and `formatType` is `"STANDARD"` includes each timezone symbol for values in date/datetime columns	false	Yes

Fields inside keys Ts

Name	Type	Description	Optional
columns	Array<String>	List of columns to query. Example: `"columns": ["Price", "Open", "Close"]`. If omitted, all available columns are returned.	Yes
symbols	object	Key–value pairs representing symbol attributes. Example: `{ "Code": "AL123", "Exchange": "EXA" }`, where `"Code"` is the column name and `"AL123"` its value.	No
metadatas	object	Key–value pairs for metadata attributes. Example: `{ "DataType": "CC Month" }`	Yes
groupName	string	Group name for the key, where symbols, metadata, columns exist	No
offsetAmount	number	Numeric value added to or subtracted from returned results based on offsetType. Example: "offsetAmount": 5 (adds 5 days if offsetType = "DAY").	Yes
offsetType	string (enum)	Time unit used for offset. Options: [MINUTE / HOUR / DAY / WEEK / MONTH / YEAR / POINT]	Yes
timeZone	string (enum)	Valid time zone name for symbol. Defaults to `UTC`. Full list: Oracle Time Zone List	Yes
fillType	string (enum)	Determines how missing data is filled. Options include: [ NONE / FORWARD / CHANGE / PERCENTAGE_CHANGE / CAL_MTH_AVG_REL(Average by Relative Calendar Month) / CAL_MTH_AVG_LAST_VAL(Average by Calendar Month - displayed as Last Value) / CAL_WEEK_AVG_REL(Average by Relative Calendar Week) / CAL_WEEK_AVG_LAST_VAL(Average by Calendar Week - displayed as Last Value) / DAYS_AVG_REL(Average by Relative Days) / VALUES_AVG_LAST_VAL(Average by Relative Values) / VALUES_AVG_REL(Average by Values - displayed as Last Value)]	Yes
pattern	boolean	Enables wildcard filtering in symbol values. Example: `{ "Code": "*" }`	Yes
patternExactMatch	boolean	When true, validates that symbol column names match exactly. Requires specifying all column names for the symbols in the request.	Yes
symbolValuesExactMatch	boolean	If true, matches only exact symbol values (e.g. "MAR"). If false, also matches values containing the symbol with delimiters (e.g. "AB-MAR").	Yes
metaDataExactMatch	boolean	If true, matches only exact metadata values (e.g. "MET"). If false, also matches values where metadata is part of another string (e.g. "HUB-MET").	Yes

Parameter Range Ts

Possible values for range:

"BETWEEN" – Returns data between specific start and end dates. Uses startDate and endDate parameters to define the time range.
Example: "range": "BETWEEN", "startDate": "2025-09-01T00:00:00", "endDate": "2025-09-02T00:00:00" - searches for values between September 1, 2025 and September 2, 2025.
"LAST" – Returns values from the past (relative to the current time). Uses lastType and lastTypeAmount to define search range.
- lastType - One of: "MINUTE", "HOUR", "DAY", "MONTH", "YEAR", "YEAR_TO_DATE", "VALUE", "VALUE_COLUMN"
- lastTypeAmount - Number corresponding to lastType (e.g., 3 for 3 days if lastType = "DAY").
  Example: "range": "LAST", "lastType": "DAY", "lastTypeAmount": 5 - searches for values in the last 5 days.
"NEXT" - Returns values projected into the future (after the current time). Uses the same parameters as "LAST" (lastType and lastTypeAmount).
Example: "range": "NEXT", "lastType": "MONTH", "lastTypeAmount": 2 - searches for values in the next 2 months.
"ALL" - Returns all available data for the specified keys (symbols, metadata, and columns), without applying any date filters.

CSV Header Configuration

Each object in csvHeaders can include:

includeSymbolColumns (boolean, default: true)
includeSymbolValues (boolean, default: true)
includeGroupNames (boolean, default: false)
includeSymbolKeys (boolean, default: false)
symbolKeys, metadataKeys (key-value pairs) — custom column name mappings.
Example: "symbolKeys": {"SYMBOL_ID": "id", "SYMBOL_NAME": "name"};
"metadataKeys": {"COUNTRY": "country", "CURRENCY": "currency_code"}.

Example in json: "csvHeaders": [{ "includeSymbolColumns": true, "includeSymbolValues": true, "includeGroupNames": false, "includeSymbolKeys": false, "symbolKeys": {"SYMBOL_ID": "id","SYMBOL_NAME": "name"}, "metadataKeys": {"COUNTRY": "country","CURRENCY": "currency_code"} }]

Get all possible symbol field value variants

curl -X POST 
    https://api.northgravity.com/ts/symbol/values?from=0&limit=10&sort=asc&metadata=true
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"    
    -d '{
            "groupName": "group name",
            "key": "symbolField",
            "symbols": {
                "SYM1": ["A1","A2"],
                "SYM2": ["B1"]
            },
            "metadatas": {
                    "MD1": ["M1"]
            }
      }'

If successful, the above command returns a list of variants with response code 200:

{
  "from": 0,
  "totalSize": 5,
  "items": [
    {
      "name": "A1",
      "type": "SYMBOL"
    },
    {
      "name": "A2",
      "type": "SYMBOL"
    },
    ...
  ]
}

This endpoint retrieves all symbol field variants.

HTTP Request

POST https://api.northgravity.com/ts/symbol/values

URL Parameters

Parameter	Description	Optional
from	Index of first element to return.	Yes
limit	Maximum number of entries to return.	Yes
sort	Sort order: `ASC` for ascending, `DESC` for descending. Defult order is ascending.	Yes
metadata	Enable to return metadata values.	Yes
query	Symbol or metadata name. Supports "" wildcards (e.g., `al`,`*01`). If not specified, searches all by default.	Yes

Request Body

Name	Type	Description	Optional
groupName	string	Group name, where symbols, metadatas exist	No
key	string	Name of the symbol or metadata field to search values for.	No
symbols	map of strings	Symbol names mapped to columns with lists of search values. Example: `"symbols": {"RIC": ["AAPL", "GOOG]},`. Values support "" wildcards.	Yes
metadatas	map of strings	Metadata names mapped to columns with lists of search values. Example: `"metadatas": {"Currency": ["USD", "EUR]},`. Values support "*" wildcards.	Yes

Get symbols columns

curl -X POST
    https://api.northgravity.com/ts/symbol/columns?from=0&limit=10&sort=asc
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"    
    -d '{

            {
                "symbols": {
                    "SYM1": "A1"
                },
                "metadatas": {
                    "Close": "2732",
                    "Open": "2777"
                },
                "groupName": "Example Group"
            }

      }'

If successful, the above command returns a list of columns names with response code 200:

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      "name": "COLUMN1",
      "type": "SYMBOL"
    },
    {
      "name": "COLUMN2",
      "type": "SYMBOL"
    }
  ]
}

This endpoint returns list of column.

HTTP Request

POST https://api.northgravity.com/ts/symbol/columns

Query Parameters

Parameter	Description	Optional
from	Index of first element to return.	Yes
limit	Maximum number of entries to return.	Yes
sort	Sort order: `ASC` for ascending, `DESC` for descending. Defult order is ascending.	Yes
metadata	Enable to return metadata values.	Yes
query	Column name filter. Supports "" wildcards (e.g., `al`,`*01`). If not specified, searches all by default.	Yes

Request Body

Name	Type	Description	Optional
groupName	string	Group name where the target columns are located.	Yes
symbols	map of strings	Symbol names mapped to columns with lists of search values. Example: `"symbols": {"RIC": ["AAPL", "GOOG]},`. Values support "" wildcards.	Yes
metadatas	map of strings	Metadata names mapped to columns with lists of search values. Example: `"metadatas": {"Currency": ["USD", "EUR]},`. Values support "*" wildcards.	Yes

Get symbols keys

curl -X POST
    https://api.northgravity.com/ts/symbol/keys?from=0&limit=20&query=*key*&sort=asc&metadata=true
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"    
    -d '{
            {
                "symbols": {
                    "SYM1": "A1"
                },
                "metadatas": {
                    "Close": "2732"
                },
                "groupName": "Example Group"
            }
      }'

If successful, the above command returns a list of symbol and metadata names with response code 200:

{
  "from": 0,
  "items": [
    {
      "name": "SYM1",
      "type": "SYMBOL"
    },
    {
      "name": "Country",
      "type": "METADATA"
    }
  ],
  "totalSize": 3
}

This endpoint returns list of symbol and metadata names.

HTTP Request

POST https://api.northgravity.com/ts/symbol/keys

Query Parameters

Parameter	Description	Optional
from	Index of first element to return.	Yes
limit	Maximum number of entries to return.	Yes
sort	Sort order: `ASC` for ascending, `DESC` for descending. Defult order is ascending.	Yes
metadata	Enable to return metadata values.	Yes
query	Symbol and metadata filter. Supports "" wildcards (e.g. `cur*`). If not specified, searches all by default.	Yes

Request Body

Name	Type	Description	Optional
groupName	string	Group name, where target keys are located.	Yes
symbols	map of strings	Symbol names mapped to columns with lists of search values. Example: `"symbols": {"RIC": ["AAPL", "GOOG]},`. Values support "" wildcards.	Yes
metadatas	map of strings	Metadata names mapped to columns with lists of search values. Example: `"metadatas": {"Currency": ["USD", "EUR]},`. Values support "*" wildcards.	Yes

Describe timeseries symbol data

curl -X POST 
    https://api.northgravity.com/ts/symbol/describe
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"    
    -d '{
            "ids": ["someSha1Hash", "someSha2Hash"],
      }'

If successful, the above command returns response code 200 with JSON structured response:

[
  {
    "id": "someId",
    "groupName": "Example Group",
    "symbols": {
      "Symbol": "SYM1"
    },
    "metadata": {
      "SomeMetadata": "metaValue",
      "Currency": "USD"
    },
    "values": [
      "Value1",
      "Value2"
    ],
    "entitlementTags": [],
    "previewAccess": false
  }
]

This endpoint returns data for specific symbol - metadata, columns values and entitlement tags.

HTTP Request

PATCH https://api.northgravity.com/symbol/describe

Request Body

Name	Type	Description	Optional
ids	list of strings	Opensearch sha hash ids	No

Get symbol name and group to sha mapping

curl -X POST 
    https://api.northgravity.com/ts/symbol/sha
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"    
    -d '{
        "groupName": "Example Group",
        "symbols": {
            "Symbol": "SYM1"
        }
    }'

If successful, the above command returns response code 200 with JSON structured response:

{
  "sha": "someShaHashValue"
}

This endpoint returns sha for specific symbol name and group. It can be used with "Describe timeseries symbol" data endpoint to get symbol details.

HTTP Request

PATCH https://api.northgravity.com/symbol/sha

Request Body

Name	Type	Description	Optional
groupName	string	Name of group	No
symbols	key-value	Symbol column name and value pairs. Example: `"symbols": {"Symbol1": "SYM1", "Symbol2": "SYM2"},`	No

Get all symbols from file

curl https://api.northgravity.com/ts/symbol/file/someFileId
  -H "Authorization: Bearer yourAccessToken"

If successful, the above command returns response code 200 with JSON structured response:

[
  {
    "id": "example_id",
    "groupName": "Example Group",
    "symbols": {
      "Symbol1": "SYM1",
      "Symbol2": "SYM2"
    },
    "metadata": {
      "TimeZone": "UTC",
      "Currency": "USD"
    },
    "values": [
      "Value 2(S)",
      "Value 1(DB)"
    ],
    "entitlementTags": [],
    "previewAccess": false
  },
  ...
]

This endpoint returns symbols, metadata, column names and entitlement tags from NCSV file.

HTTP Request

GET https://api.northgravity.com/symbol/file/{fileId}

URL Parameters

Parameter	Description	Optional
fileId	ID of NCSV file	No

Update timeseries data

curl -X PATCH 
    https://api.northgravity.com/ts/data
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"    
    -d '{
            "updates": [
                {
                    "symbols": {
                        "SYM": "A123"
                    },
                    "values": {
                        "Close": "2732",
                        "Open": "2777"
                    },
                    "groupName": "Example Group",
                    "time": "2019-01-01T10:26:00"
                }
            ]
      }'

If successful, the above command returns response code 200.

This endpoint updates Times Series data.

HTTP Request

PATCH https://api.northgravity.com/ts/data

Request Body

Name	Type	Description	Optional
groupName	string	Name of the group containing symbols	No
symbols	Key-value	Column symbol names to symbol keys map. Example: `"symbols": {"SYM": "A123"}`, where "SYM" - symbol column name, "A123" - symbol value name	No
values	Key-value	Column values names to values map. Example: `"values": {"Close": "2732"}`, where "Close" - values column name, "2732" - value	No
time	string	UTC time for timeseries data. Example: `"2025-10-10T10:30:00"`	No

Validate timeseries data

curl -X POST 
  https://api.northgravity.com/ts/symbol/validate?size=100
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
      "startDate": "2017-01-11T10:01:03",
      "endDate": "2017-12-11T10:01:03",
      "keys": [{
        "columns": ["Open", "Close", "High"],
        "symbols": {
          "SYM1": "A1",
          "SYM2": "B1"
        },
        "groupName": "group name",
        "timeZone": "America/NewYork",
        "pattern": true,
        "patternExactMatch": false
      }],
      "timeZone": "America/NewYork",
      "formatType": "STANDARD",
    }'

If successful, the above command returns response code 200 with JSON structured response:

[
  {
    "key": {
      "allColumns": [
        {
          "name": "High",
          "type": "DB"
        },
        {
          "name": "Close",
          "type": "DB"
        },
        {
          "name": "Open",
          "type": "DB"
        }
      ],
      "requestedColumns": [
        "Close"
      ],
      "requestedColumnTypes": {
        "Close": "DB"
      },
      "symbols": {
        "SYM1": "A1",
        "SYM2": "B1"
      },
      "allMetadatas": [
        {
          "name": "TimeZone",
          "value": "America/NewYork",
          "type": "S"
        }
      ],
      "id": "a712104a45678bec4a8b41217276e42b9c",
      "groupName": "group name",
      "groupId": 1,
      "pattern": false,
      "patternExactMatch": false
    },
    "index": 0,
    "zoneId": "America/NewYork",
    "startDate": -62167219200000,
    "endDate": 253370764800000,
    "offset": 0
  },
  {
    ...
  }
]

This endpoint returns list of all columns and metadata with type details for symbols. Limit of symbols is 2000.

HTTP Request

POST https://api.northgravity.com/ts/symbol/validate?size=<size>

URL Parameters

Parameter	Description	Optional
nextPageToken	Token returned by last response to get next page of data	Yes
size	Number of rows per page. Max size is 10 000. Default size is 10 000.	Yes
order	Sort order: `ASC` for ascending, `DESC` for descending.	Yes
omitNulls	If true removes fields with null values	Yes
absoluteSize	Number of records to skip	Yes
symbolSize	Specifies the maximum number of symbols to return. Default size is 500.	Yes
sortSymbols	Sorts symbols ascending by creation time. Special characters in symbol names must be URL-encoded (e.g., "SYM1=DA1" → "SYM1%3DA1"). Common encodings: "=", "*", "-".	Yes

Request Body

See Request Body Ts in the Search Time Series Data section — both endpoints share the same request format.

Holiday Calendars

NorthGravity maintains a list of holiday calendars for use with third-party timeseries.

Calendar Files

Field Name	Description	Type	Example(s)
Calendar	The name of the calendar.	Text	`Holidays_US` `Holidays_CME`
Date	Date specified without a time zone.	YYYY-MM-DD	`2020-12-25`
Value(S)	Holiday name or `Yes`.	Text	`Christmas`

Holiday Calendars Search

curl https://api.dev.northgravity.com/ts/symbol/holiday-calendars
    -H "Authorization: Bearer yourAccessToken"

If successful, the above command returns response code 200 with JSON structured response:

{
  "from": 0,
  "items": [
    {
      "name": "EXAMPLE_CALENDAR",
      "type": "SYMBOL"
    }
  ],
  "totalSize": 1
}

This endpoint lists all accessible calendars to user.

HTTP Request

GET https://api.northgravity.com/ts/symbol/holiday-calendars

URL Parameters

Parameter	Description	Optional
from	Index of first element to return.	Yes
limit	Maximum number of entries to return.	Yes
sort	Sort order: `ASC` for ascending, `DESC` for descending. Defult order is ascending.	Yes
query	Calendar names filter. Supports "" wildcards (e.g. `cur*`). If not specified, searches all by default.	Yes

Holiday Calendars Details

curl https://api.dev.northgravity.com/ts/symbol/holiday-calendars/{holidayCalendarName}
    -H "Authorization: Bearer yourAccessToken"

If successful, the above command returns response code 200 with JSON structured response:

{
  "from": 0,
  "items": [
    {
      "name": "EXAMPLE_CALENDAR",
      "type": "SYMBOL"
    }
  ],
  "totalSize": 4
}

This endpoint returns the details of the requested calendar.

HTTP Request

GET https://api.northgravity.com/ts/symbol/holiday-calendars/{holidayCalendarName}

Search groups with symbols and user has access

curl -X POST 
    https://api.northgravity.com/ts/symbol/group
    -d '{
        "nextPageToken": {
            "group": "groupName"
        }
    }'

If successful, the above command returns response code 200 with a JSON response:

{
  "hasNextPage": true,
  "nextPageToken": {
    "group": "test"
  },
  "items": [
    {
      "name": "USDAdata-test01"
    },
    {
      "name": "Wikipedia"
    }
  ]
}

This endpoint return groups with symbols to which user has access.

HTTP Request

POST https://api.northgravity.com/ts/symbol/group?query=<query>&size=<size>&order=<order>

Request query parameters

Parameter	Description	Optional
query	Group names filter. Supports "" wildcards (e.g. `cur*`). If not specified, searches all by default.	Yes
size	Number of returned group names. Default: 30	Yes
order	Sort order: `ASC` for ascending, `DESC` for descending. Defult order is ascending. Default: asc	Yes

Request body parameters

There has to be body in form of at least {} to avoid 400 error.

Name	Description	Optional
nextPageToken	Used for pagination. Name of next group with symbols is returned in reponse body. Example: `"nextPageToken": {"group": "example"}`	Yes

Assign entitlement tags to a symbol

This endpoint assigns a set of entitlement tags to a symbol. This method will overwrite any entitlement tags already assigned to a symbol with entitlement tags from request body. Either sha or symbol names and values map can be provided to identify the symbol. Method will prioritize sha if both are provided.

curl -X PUT https://api.northgravity.com/ts/symbol/enttag
    -H "Authorization: Bearer yourAccessToken"
    -H "Content-Type: application/json"    
    -d '{
      "sha": "12ab3cd456e7fa890bc12d3e4f56789a0bc12d34",
      "entTagNames": ["enttag1", "enttag2"]
    }'

or

curl -X PUT https://api.northgravity.com/ts/symbol/enttag
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "entTagNames": ["enttag1", "enttag2"],
    "groupName": "group name",
    "symbol": {
        "SYM1": "A1",
        "SYM2": "A2"
    }
}'

If successful, the above command returns status code 200

HTTP Request

PUT https://api.northgravity.com/ts/symbol/enttag

Request Body

Parameter	Type	Description	Optional
sha	string	Symbol sha	No (Yes if symbol is provided)
groupName	string	Group name containing the symbol	No (Yes if sha is provided)
symbol	key-value	Map of name-value pairs. Example: `{ "Code": "AL123", "Exchange": "ICE" }`, where `Code` is column name and `AL123` is the column value	No (Yes if sha is provided)
entTagNames	list of strings	Set of entitlement tags names	No

Remove entitlement tags from a symbol

This endpoint deletes a set of entitlement tags from a symbol. Either sha or symbol names and values map can be provided to identify the symbol. Method will prioritize sha if both are provided.

curl -X DELETE https://api.northgravity.com/ts/symbol/enttag
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "sha": "12ab3cd456e7fa890bc12d3e4f56789a0bc12d34",
    "entTagNames": ["enttag1", "enttag2"]
  }'

curl -X DELETE https://api.northgravity.com/ts/symbol/enttag
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "entTagNames": ["enttag1", "enttag2"],
    "groupName": "group name",
    "symbol": {
        "SYM1": "A1",
        "SYM2": "A2"
    }
  }'

If successful, the above command returns status code 200

HTTP Request

DELETE https://api.northgravity.com/ts/symbol/enttag

Request Body

Parameter	Type	Description	required
sha	string	Symbol sha	No (if symbol is not provided)
groupName	string	Group name containing the symbol	No (if sha is not provided)
symbol	key-value	Map of name-value pairs. Example: `{ "Code": "AL123", "Exchange": "ICE" }`, where `Code` is column name and `AL123` is the column value	No (if sha is not provided)
entTagNames	list of strings	Set of entitlement tags names	No

Add entitlement tags to a symbol

This endpoint adds a set of entitlement tags to a symbol. This method will not overwrite any entitlement tags already assigned to a symbol. It will only add new ones from request body. Either sha or symbol names and values map can be provided to identify the symbol. Method will prioritize sha if both are provided.

curl -X PATCH https://api.northgravity.com/ts/symbol/enttag
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "sha": "12ab3cd456e7fa890bc12d3e4f56789a0bc12d34",
    "entTagNames": ["enttag1", "enttag2"]
  }'

curl -X PATCH https://api.northgravity.com/ts/symbol/enttag
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "entTagNames": ["enttag1", "enttag2"],
    "groupName": "group name",
    "symbol": {
        "SYM1": "A1",
        "SYM2": "A2"
    }
  }'

If successful, the above command returns status code 200

HTTP Request

PATCH https://api.northgravity.com/ts/symbol/enttag

Request Body

Parameter	Type	Description	Optional
sha	string	Symbol sha	No (if symbol is not provided)
groupName	string	Group name containing the symbol	No (if sha is not provided)
symbol	key-value	Map of name-value pairs. Example: `{ "Code": "AL123", "Exchange": "ICE" }`, where `Code` is column name and `AL123` is the column value	No (if sha is not provided)
entTagNames	list of strings	Set of entitlement tags names	No

Assign entitlement tags to a symbol (using enttag ids)

curl -X PUT https://api.northgravity.com/ts/symbol/enttagid
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "sha": "12ab3cd456e7fa890bc12d3e4f56789a0bc12d34",
    "entTagIds": [1, 2]
  }'

curl -X PUT https://api.northgravity.com/ts/symbol/enttagid
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "entTagIds": [1, 2],
    "groupName": "group name",
    "symbol": {
        "SYM1": "A1",
        "SYM2": "A2"
    }
  }'

If successful, the above command returns status code 200

HTTP Request

PUT https://api.northgravity.com/ts/symbol/enttagid

Request Body

Parameter	Type	Description	Optional
sha	string	Symbol sha	No (if symbol is not provided)
groupName	string	Group name containing the symbol	No (if sha is not provided)
symbol	key-value	Map of name-value pairs. Example: `{ "Code": "AL123", "Exchange": "ICE" }`, where `Code` is column name and `AL123` is the column value	No (if sha is not provided)
entTagIds	list of strings	Set of entitlement tags ids	No

Remove entitlement tags from a symbol (using enttag ids)

This endpoint deletes a set of entitlement tags from a symbol. Either sha or symbol names and values map can be provided to identify the symbol. Method will prioritize sha if both are provided.

curl -X DELETE https://api.northgravity.com/ts/symbol/enttagid
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "sha": "12ab3cd456e7fa890bc12d3e4f56789a0bc12d34",
    "entTagIds": [1, 2]
  }'

curl -X DELETE https://api.northgravity.com/ts/symbol/enttagid
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "entTagNames": [1, 2],
    "groupName": "group name",
    "symbol": {
        "SYM1": "A1",
        "SYM2": "A2"
    }
  }'

If successful, the above command returns status code 200

HTTP Request

DELETE https://api.northgravity.com/ts/symbol/enttagid

Request Body

Parameter	Type	Description	Optional
sha	string	Symbol sha	No (if symbol is not provided)
groupName	string	Group name containing the symbol	No (if sha is not provided)
symbol	key-value	Map of name-value pairs. Example: `{ "Code": "AL123", "Exchange": "ICE" }`, where `Code` is column name and `AL123` is the column value	No (if sha is not provided)
entTagIds	list of strings	Set of entitlement tags ids	No

Add entitlement tags to a symbol (using enttag ids)

curl -X PATCH https://api.northgravity.com/ts/symbol/enttagid
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "sha": "12ab3cd456e7fa890bc12d3e4f56789a0bc12d34",
    "entTagIds": ["enttag1", "enttag2"]
  }'

curl -X PATCH https://api.northgravity.com/ts/symbol/enttagid
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
    "entTagIds": [1, 2],
    "groupName": "group name",
    "symbol": {
        "SYM1": "A1",
        "SYM2": "A2"
    }
  }'

If successful, the above command returns status code 200

HTTP Request

PATCH https://api.northgravity.com/ts/symbol/enttagid

Request Body

Parameter	Type	Description	Optional
sha	string	Symbol sha	No (if symbol is not provided)
groupName	string	Name of the group with symbol	No (if sha is not provided)
symbol	key-value	Map of name-value pairs. Example: `{ "Code": "AL123", "Exchange": "ICE" }`, where `Code` is column name and `AL123` is the column value	No (if sha is not provided)
entTagIds	list of strings	Set of entitlement tags ids	No

Remove symbol column

This endpoint deletes a column from symbol. The delete acts as soft delete and does not delete the data in both databases.

curl -X DELETE https://api.northgravity.com/ts/column 
  -H "Authorization: Bearer yourAccessToken"
  -H "Content-Type: application/json"    
  -d '{
        "groupName": "group name",
        "symbols": {
            "SYM1": "A1",
            "SYM2": "A2"
          },
        "columnToDelete": "nameOfColumnToDelete"
      }'

If successful, the above command returns status code 204

HTTP Request

DELETE https://api.northgravity.com/ts/column

Request Body

Parameter	Type	Description	Optional
groupName	string	Group name containing the column.	No
symbols	key-value	Map of name-value pairs. Example: `{ "Code": "AL123", "Exchange": "ICE" }`, where `Code` is column name and `AL123` is the column value.	No
columnToDelete	string	Name of the column to delete.	No

curl -X POST 
  https://api.northgravity.com/ts/validate/ncsv
  -H "Authorization: Bearer yourAccessToken"
  -H 'content-type: text/plain'
  --data-binary '@file.csv'

If validation successful, the above command returns status code 204.

If validation failed, the above command returns status code 400 and JSON:

[
  {
    "columnNumber": -1,
    "rowNumber": -1,
    "message": "Parser error. Missing at least one metadata header."
  }
]

Check whether the data loads into the time series or returns a list of errors. Request body should contain CSV file as binary data.

HTTP Request

POST https://api.northgravity.com/ts/validate/ncsv

curl -X POST 
  https://api.northgravity.com/ts/validate/ncsv/someFileId
  -H "Authorization: Bearer yourAccessToken"
  -H 'content-type: text/plain'

If validation successful, the above command returns status code 204.

If validation failed, the above command returns status code 400 and JSON:

[
  {
    "columnNumber": -1,
    "rowNumber": -1,
    "message": "Parser error. Missing at least one metadata header."
  }
]

Check whether the data loads into the time series or returns a list of errors.

HTTP Request

POST https://api.northgravity.com/ts/validate/ncsv/{fileId}

URL Parameters

Parameter	Description	Optional
fileId	Id of NCSV file to validate	No

curl -X POST 
  https://api.northgravity.com/ts/symbol/metadata
  -H "Authorization: Bearer yourAccessToken"
  -H 'content-type: text/plain'
  -d '{"groupName":"Example Group","useEs":true}'

If successful, the above command returns response code 200 with JSON structured response:

{
  "from": 0,
  "items": [
    {
      "name": "ValueA",
      "type": "METADATA"
    },
    {
      "name": "ValueB",
      "type": "METADATA"
    }
  ],
  "totalSize": 2
}

Returns list of metadata names for symbols in group.

HTTP Request

POST https://api.northgravity.com/ts/symbol/metadata?from=<from>&limit=<limit>&query=<query>&sort=<sort>

URL Parameters

Parameter	Description	Optional
from	Index of first element to return.	Yes
limit	Maximum number of entries to return.	Yes
sort	Sort order: `ASC` for ascending, `DESC` for descending. Defult order is ascending.	Yes
query	Metadata name filter. Supports "" wildcards (e.g. `cur*`). If not specified, all metadata names are searched by default.	Yes

Request Body

Field	Type	Description	Optional
groupName	string	Group name where file with symbol was uploaded.	No
useEs	string	If true, searches symbol metadata in OpenSearch; if false, searches in the database. Default is false.	Yes

Get Time Series Data By Stream

curl -X POST  
  https://api.northgravity.com/ts/stream
  -H 'Content-Type: application/json'
  -H "Authorization: Bearer yourAccessToken"
  -d '{
        "startDate": null,
        "endDate": null,
        "keys": [
          {
            "symbols": {
              "Symbol": "*"
            },
            "metadatas": {},
            "groupName": "GroupName",
            "pattern": true,
            "metaDataExactMatch": true
          }
        ],
        "range": "LAST",
        "lastType": "VALUE_COLUMN",
        "lastTypeAmount": 1,
        "metadata": true
      }'

Response

Symbol	Date (UTC)	Close	High	Low	Code (S)	Open	PeriodAbs (S)	PeriodEnd (D)	PeriodRel (S)	PeriodStart (D)	PeriodType (S)	TenorGeneric (S)	TenorUnique (S)	Currency (MD-S)	DataGranularity (MD-S)	DataType (MD-S)	Description (MD-S)	FuturesRoot (MD-S)	Market (MD-S)	Product (MD-S)	Source (MD-S)	SourceRegion (MD-S)	TimeZone (MD-S)	Units (MD-S)	ValueType (MD-S)
product_AC_M.202702	2025-02-07T12:00:00	12.1917	12.2366	12.1169	16d67039-8300-4aa2-845f-c39a3c176bc8	12.1748	2027-02	2027-02-28	25	2027-02-01	Month	M24	G27	USD	Intraday	Futures	product LNG - SMT	product	Natural Gas	LNG	SMT	Europe	UTC	MMBTU	Pricing
product_CC_M.007	2025-02-07T12:00:00	16.6485	16.6592	16.5523	16d67039-8300-4aa2-845f-c39a3c176bc8	16.5936	2025-08	2025-08-31	7	2025-08-01	Month	M06	Q25	USD	Intraday	CC Month	product LNG - SMT	product	Natural Gas	LNG	SMT	Europe	UTC	MMBTU	Pricing
product_CC_M.012	2025-02-07T12:00:00	15.2477	15.2769	15.1433	16d67039-8300-4aa2-845f-c39a3c176bc8	15.186	2026-01	2026-01-31	12	2026-01-01	Month	M11	F26	USD	Intraday	CC Month	product LNG - SMT	product	Natural Gas	LNG	SMT	Europe	UTC	MMBTU	Pricing

HTTP Request

POST https://api.northgravity.com/ts/stream?size=<size>&order=<order>

URL Parameters

Parameter	Description	Optional
size	The maximum number of rows displayed at once. Default: empty (returns all)	true
order	Sort order: `ASC` for ascending, `DESC` for descending. Defult order is descending.	true

Request Body

Top-Level Fields

Parameter	Type	Description	Optional
keys	object	The maximum number of rows displayed at once. (see Fields inside keys)	no
range	string	Defines how the search period is calculated. (see Parameter Range)	yes
startDate	string	Date (ISO 8601). Start of the date range. Results earlier than this date are excluded. Example: `"2025-09-01T00:00:00"`. Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	yes
endDate	string	Date (ISO 8601). End of the date range. Results later than this date are excluded. Example: `"2025-09-02T00:00:00"`. Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	yes
lastType	string	Defines the type of the “last period”. (see Parameter Range)	yes
lastTypeAmount	number	Specifies the number of periods for the last selected type. (see Parameter Range)	yes
metadata	boolean	If true, includes symbol metadata in the response. Default: `false`	yes
formatType	boolean	Formats: `NCSV`, `CSV`. Default: `NCSV`	yes

Fields inside keys

Field	Type	Description	Optional
groupName	string	Group name for the key.	no
symbols	key-value	Map of name-value pairs. Example: `{ "Code": "AL123", "Exchange": "ICE" }`, where `Code` is column name and `AL123` is the column value.	no
metadatas	key-value	Map of metadata attributes. Example: `{ "DataType": "CC Month" }`, where `DataType` is column name and `CC Month` is value from this column. If multiple are provided, the last one takes precedence.	yes
pattern	boolean	Required if any `symbols` or `metadatas` value equals `"*"`. Enables pattern matching.	yes
patternExactMatch	boolean	When `true`, validates that symbol column names match exactly. Requires specifying all column names for the symbols in the request. Defaults to `false`.	Yes
symbolValuesExactMatch	boolean	Match exact symbol values only. If `true`, returns only exact matches (e.g. "MAR"). If `false`, also returns values where the symbol is combined with other text using any delimiters (e.g. "AB-MAR"). Defaults to `false`.	Yes
metaDataExactMatch	boolean	Match exact metadata values only. If `true`, returns only exact matches (e.g. "MET"). If `false`, also returns values where the symbol is combined with other text using any delimiters (e.g. "HUB-MET"). Defaults to `false`.	Yes

Parameter Range

Possible values for range:

"BETWEEN" – Returns data between specific start and end dates. Uses startDate and endDate parameters to define the time range.
Example: "range": "BETWEEN", "startDate": "2025-09-01T00:00:00", "endDate": "2025-09-02T00:00:00" - searches for values between September 1, 2025 and September 2, 2025.
"LAST" – Returns values from the past (relative to the current time). Uses lastType and lastTypeAmount to define search range.
- lastType - One of: "MINUTE", "HOUR", "DAY", "MONTH", "YEAR", "YEAR_TO_DATE", "VALUE", "VALUE_COLUMN"
- lastTypeAmount - Number corresponding to lastType (e.g., 3 for 3 days if lastType = "DAY").

Data Prep

Search DataPreps

curl https://api.northgravity.com/dataprep/search?query=exampleDataPrep
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      "id": "dataPrepId1",
      "name": "dataprep name 1",
      "groupName": "Example Group",
      "status": "CREATED",
      "checkCompletness": false,
      "version": 2,
      "withType": false,
      "prevDataPrepId": "prevDataPrepId",
      "generatedFileId": "",
      "modifyDate": "2025-11-14T10:00:00.000",
      "longRun": false,
      "adjustTimeToTimezone": false,
      "failOnMissingSymbols": false,
      "skipEmptyColumns": false,
      "ncsvEmptySymbolsInResult": false,
      "delta": false,
      "links": [],
      "groupFilter": false
    },
    ...
  ]
}

This endpoint returns list of stored data preps.

HTTP Request

GET https://api.northgravity.com/dataprep/search?query=<dataprepName>&latest=<latest>

URL Parameters

Parameter	Description	Optional
dataprepName	Name of the dataprep to search for. Supports wildcard "*" patterns.	No
latest	Returns the latest version when set to `true`. Returns all versions when set to `all`. Default: `true`	Yes

Create a Data Prep

curl -X POST
  https://api.northgravity.com/dataprep
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
        "name": "example dataprep name",
        "symbols": [
            {
                "valueColumnNames": [
                    "SomeColumnName1", "SomeColumnName2"
                ],
                "symbol": {
                    "SomeSymbolName1": "SymbolValue1",
                    "SomeSymbolName2": "SymbolValue2"
                },
                "groupName": "testGroupK2",
                "pattern": false,
                "patternExactMatch": false
            }
        ],
        "outputGroup": "example Output Group Name",
        "range": "ALL",
        "dateFrom": "2017-10-01T00:00:00",
        "dateTo": "2017-11-01T00:00:00",
        "outputLayout": "Fast_ncsv",
        "withType": false,
        "attachMetadataToNcsv": false,
        "roundingMode": "HALF_UP",
        "failOnMissingSymbols": false,
        "ncsvEmptySymbolsInResult": false,
        "skipEmptyColumns": false,
        "delta": false,
        "corrections": "false",
        "order": "DESC"
  }'

If successful, the above command returns status code 200 and a new data prep id, otherwise please check Errors section. Response example:

{
  "id": "Data prep id"
}

This endpoint creates a new data prep.

HTTP Request

POST https://api.northgravity.com/dataprep

Request Body Dataprep

Name	Type	Description	Optional
name	string	Name of the dataprep.	No
symbols	Array<Object>	List of symbols. For details see Dataprep symbols	No
outputGroup	string	Name of the output group where the generated files will be saved. Defaults to the user’s home group if not specified.	No
outputFileName	string	Name of the generated file. Defaults to dataprep name.	Yes
range	string	Search period type: [ ALL / BETWEEN / LAST / NEXT ]. Default: `ALL`. More details in Timeseries range	Yes
dateFrom	string	Date (ISO 8601). Start of the date range. Results earlier than this date are excluded. Example: `"2025-09-01T00:00:00"`. Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	Yes
dateTo	string	Date (ISO 8601). End of the date range. Results later than this date are excluded. Example: `"2025-09-02T00:00:00"`. Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	Yes
lastType	string	Options: [ MINUTE / HOUR / DAY / BUSINESS_DAY / MONTH / YEAR / YEAR_TO_DATE / VALUE]. Applied only when range is `"LAST"` or `"NEXT"`.	Yes
lastTypeAmount	string	Number of time units (like days) defined by the `lastType` parameter and is used to determine how far in the past or future a search range should extend — depending on whether `range` is LAST or NEXT. Searches for insert time in that range.	Yes
lastTypeOnTime	string	Range start time for `range`=`"LAST"` ("HH:mm:ss").	Yes
lastTypeOnTimeTimezone	string	Valid time zone name applied to parameters `lastTypeOnDate` and `lastTypeOnTime`. Full list: Oracle Time Zone List	Yes
holidayCalendar	string	Name of the holiday calendar. Used with `lastType` = `"BUSINESS_DAY"` and range values like `"LAST"` or `"NEXT"` to skip non-business days. Example: a 9-day search may extend to 11 days if 2 days of holidays are encountered.	Yes
outputLayout	string	Output format of dataprep file. Options: [ Vertical / Horizontal / Fast_ncsv ]	Yes
withType	boolean	If the output layout is Vertical or Horizontal, enabling this option adds the data types to the output headers.	Yes
attachMetadataToNcsv	boolean	Adds metadata columns to the file generated by the dataprep. This option is only supported when `outputLayout` is set to `Fast_ncsv`	Yes
dateFormat	boolean	Format string for date values to return (e.g., "yyyy-MM-dd'T'HH:mm:ss.SSS")	Yes
decimalPrecision	number	Number of digits after the decimal point. "0" means no decimals; "n" means n digits.	Yes
roundingMode	string (enum)	Rounding mode options: [ UP / DOWN / CEILING / FLOOR / HALF_UP / HALF_EVEN]	Yes
failOnMissingSymbols	boolean	Fail if there are missing symbols.	Yes
ncsvEmptySymbolsInResult	boolean	When enabled, empty symbols are are included in the output results.	Yes
skipEmptyColumns	boolean	Skip empty columns and symbols, where columns are without values.	Yes
corrections	boolean	If `"true"`, includes corrected(previous) values with timestamps (and insert time if `dateFormat` is `STANDARD`). If `"false"`, returns only the latest values.	Yes
delta	boolean	If `true`, filters results based on the transaction date (dates used in csv file) using using `deltaTransDateLimitType` and `deltaTransDateLimitAmount`. If `false`, these parameters are ignored.	Yes
deltaTransDateLimitType	string (enum)	Transaction date limit unit for delta. Options: [MINUTE / HOUR / DAY / WEEK / MONTH / YEAR ].	Yes
deltaTransDateLimitAmount	number	Time offset from the current time. The meaning of this value depends on `deltaTransDateLimitType` (e.g., if `"DAY"` value is in days). Negative values are allowed.	Yes
symbolQuery	boolean	Dynamic query for retrieving symbols.	Yes
queryColumnNames	boolean	Column names returned by the symbolQuery.	Yes
order	string	Sort order: `asc` for ascending, `desc` for descending(latest to oldest date). Defult order is descending.	Yes
onDateTime	string	Accepts either an ISO 8601 datetime format (yyyy-MM-dd'T'HH:mm:ss.SSS) or a date placeholder: yesterday, today, or tomorrow. Displays values for dates prior to the specified date.	null

Dataprep symbols

Name	Type	Description	Optional
groupName	string	Group name where symbol or metadata exist	No
symbol	object	Key–value pairs representing symbol attributes. Example: `{ "Code": "AL123", "Exchange": "EXA" }`, where `"Code"` is the column name and `"AL123"` its value.	No
metadata	object	Key–value pairs for metadata attributes. Example: `{ "DataType": "CC Month" }`	Yes
valueColumnNames	Array<String>	List of symbol column names. Example: `"valueColumnNames": ["Price", "Open", "Close"]`. Default: `"*"` - takes all columns.	Yes
offsetAmount	number	Numeric value added to or subtracted from returned results based on offsetType. Example: "offsetAmount": 5 (adds 5 days if offsetType = "DAY").	Yes
offsetType	string (enum)	Time unit used for offset. Options: [MINUTE / HOUR / DAY / WEEK / MONTH / YEAR / POINT]	Yes
fillType	string (enum)	Determines how missing data is filled. Options include: [ NONE / FORWARD / CHANGE / PERCENTAGE_CHANGE / CAL_MTH_AVG_REL(Average by Relative Calendar Month) / CAL_MTH_AVG_LAST_VAL(Average by Calendar Month - displayed as Last Value) / CAL_WEEK_AVG_REL(Average by Relative Calendar Week) / CAL_WEEK_AVG_LAST_VAL(Average by Calendar Week - displayed as Last Value) / DAYS_AVG_REL(Average by Relative Days) / VALUES_AVG_LAST_VAL(Average by Relative Values) / VALUES_AVG_REL(Average by Values - displayed as Last Value)]	Yes
pattern	boolean	Enables wildcard filtering in symbol values. Example: `{ "Code": "*" }`	Yes
patternExactMatch	boolean	When true, validates that symbol column names match exactly. Requires specifying all column names for the symbols in the request.	Yes

Update a Data Prep

curl -X PUT
  https://api.northgravity.com/dataprep/exampleDataprepId
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
        "name": "example dataprep name",
        "symbols": [
            {
                "valueColumnNames": [
                    "SomeColumnName1", "SomeColumnName2"
                ],
                "symbol": {
                    "SomeSymbolName1": "SymbolValue1",
                    "SomeSymbolName2": "SymbolValue2"
                },
                "groupName": "testGroupK2",
                "pattern": false,
                "patternExactMatch": false
            }
        ],
        "outputGroup": "example Output Group Name",
        "range": "ALL",
        "dateFrom": "2017-10-01T00:00:00",
        "dateTo": "2017-11-01T00:00:00",
        "outputLayout": "Fast_ncsv",
        "withType": false,
        "attachMetadataToNcsv": false,
        "roundingMode": "HALF_UP",
        "failOnMissingSymbols": false,
        "ncsvEmptySymbolsInResult": false,
        "skipEmptyColumns": false,
        "delta": false,
        "corrections": "false",
        "order": "DESC"
  }'

If successful, the above command returns status code 200 and a new data prep id, otherwise please check Errors section. Response example:

{
  "id": "Data prep id"
}

This endpoint updates a data prep.

HTTP Request

PUT https://api.northgravity.com/dataprep/{dataprepId}

URL Parameters

Parameter	Description	Optional
dataprepId	DataPrep id	No

Request Body

Request body the same as in Create a Data Prep section.(see Data prep properties)

Update a Data Prep By Name

curl -X PUT
  https://api.northgravity.com/dataprep/name/exampleDataprepName
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
        "name": "example dataprep name",
        "symbols": [
            {
                "valueColumnNames": [
                    "SomeColumnName1", "SomeColumnName2"
                ],
                "symbol": {
                    "SomeSymbolName1": "SymbolValue1",
                    "SomeSymbolName2": "SymbolValue2"
                },
                "groupName": "testGroupK2",
                "pattern": false,
                "patternExactMatch": false
            }
        ],
        "outputGroup": "example Output Group Name",
        "range": "ALL",
        "dateFrom": "2017-10-01T00:00:00",
        "dateTo": "2017-11-01T00:00:00",
        "outputLayout": "Fast_ncsv",
        "withType": false,
        "attachMetadataToNcsv": false,
        "roundingMode": "HALF_UP",
        "failOnMissingSymbols": false,
        "ncsvEmptySymbolsInResult": false,
        "skipEmptyColumns": false,
        "delta": false,
        "corrections": "false",
        "order": "DESC"
  }'

If successful, the above command returns status code 200 and a new data prep id, otherwise please check Errors section. Response example:

{
  "id": "Data prep id"
}

This endpoint updates a data prep.

HTTP Request

PUT https://api.northgravity.com/dataprep/name/{dataprepName}

URL Parameters

Parameter	Description	Optional
dataprepName	DataPrep name	No

Request Body

Request body the same as in Create a Data Prep section.(see Data prep properties)

Get a Specific Data Prep

curl https://api.northgravity.com/dataprep/exampleDataprepId
    -H "Authorization: Bearer yourNgToken"

If successful, the above command returns a list of columns names with response code 200:

{
  "id": "data prep id",
  "name": "data prep name",
  "status": "data prep status [CREATED|RUNNING|ERROR|COMPLETED|INFO]",
  "tags": [
    "A1",
    "A2"
  ],
  "outputGroup": "name of the output group name",
  "symbols": [
    {
      "groupName": "test group 1",
      "symbol": {
        "sym1": "A1",
        "sym2": "A2"
      },
      "valueColumnNames": [
        "*"
      ]
    }
  ],
  "rootId": "root data prep id",
  "prevDataPrepId": "previous data prep id",
  "version": 44,
  "dateFormat": "yyyy-MM-dd'T'HH:mm:ss.SSS",
  "range": "date range type [ALL|BETWEEN|LAST]",
  "outputLayout": "output layout type [Vertical|Horizontal|Fast_ncsv]",
  "withType": true,
  "roundingMode": "rounding mode type [UP|DOWN|CEILING|FLOOR|HALF_UP|HALF_EVEN]",
  "corrections": "[false|true]",
  "failOnMissingSymbols": false,
  "skipEmptyColumns": false,
  "ncsvEmptySymbolsInResult": false,
  "delta": true,
  "attachMetadataToNcsv": true,
  "order": "[DESC|ASC]",
  "groupFilter": false
}

This endpoint retrieves a specific data prep.

HTTP Request

GET https://api.northgravity.com/dataprep/{dataprepId}

URL Parameters

Parameter	Description	Optional
dataprepId	DataPrep id	No
withMetadata	If `true`, returns symbols with metadata included. Default: `false`	Yes
resolvePattern	If `true`, resolves and returns all symbols matching the pattern; If `false`, returns the pattern itself without resolving it. Default: `false`	Yes

Get a Specific Dataprep by name

curl https://api.northgravity.com/dataprep/name/exampleDataprepName
    -H "Authorization: Bearer yourNgToken"

If successful, the above command returns a list of columns names with response code 200:

{
  "id": "data prep id",
  "name": "data prep name",
  "status": "data prep status [CREATED|RUNNING|ERROR|COMPLETED|INFO]",
  "tags": [
    "A1",
    "A2"
  ],
  "outputGroup": "name of the output group name",
  "symbols": [
    {
      "groupName": "test group 1",
      "symbol": {
        "sym1": "A1",
        "sym2": "A2"
      },
      "valueColumnNames": [
        "*"
      ]
    }
  ],
  "rootId": "root data prep id",
  "prevDataPrepId": "previous data prep id",
  "version": 44,
  "dateFormat": "yyyy-MM-dd'T'HH:mm:ss.SSS",
  "range": "date range type [ALL|BETWEEN|LAST]",
  "outputLayout": "output layout type [Vertical|Horizontal|Fast_ncsv]",
  "withType": true,
  "roundingMode": "rounding mode type [UP|DOWN|CEILING|FLOOR|HALF_UP|HALF_EVEN]",
  "corrections": "[false|true]",
  "failOnMissingSymbols": false,
  "skipEmptyColumns": false,
  "ncsvEmptySymbolsInResult": false,
  "delta": true,
  "attachMetadataToNcsv": true,
  "order": "[DESC|ASC]",
  "groupFilter": false
}

This endpoint retrieves a specific data prep.

HTTP Request

GET https://api.northgravity.com/dataprep/name/{dataprepName}

URL Parameters

Parameter	Description	Optional
dataprepName	DataPrep name	No
withMetadata	If `true`, returns symbols with metadata included. Default: `false`	Yes
resolvePattern	If `true`, resolves and returns all symbols matching the pattern; If `false`, returns the pattern itself without resolving it. Default: `false`	Yes

Get a Specific Dataprep by group, name and version

curl https://api.northgravity.com/dataprep/exampleGroupName/exampleDataprepName/4?withMetadata=true&resolvePattern=false
    -H "Authorization: Bearer yourNgToken"

If successful, the above command returns a list of columns names with response code 200:

{
  "id": "data prep id",
  "name": "data prep name",
  "status": "data prep status [CREATED|RUNNING|ERROR|COMPLETED|INFO]",
  "tags": [
    "A1",
    "A2"
  ],
  "outputGroup": "name of the output group name",
  "symbols": [
    {
      "groupName": "test group 1",
      "symbol": {
        "sym1": "A1",
        "sym2": "A2"
      },
      "valueColumnNames": [
        "*"
      ]
    }
  ],
  "rootId": "root data prep id",
  "prevDataPrepId": "previous data prep id",
  "version": 44,
  "dateFormat": "yyyy-MM-dd'T'HH:mm:ss.SSS",
  "range": "date range type [ALL|BETWEEN|LAST]",
  "outputLayout": "output layout type [Vertical|Horizontal|Fast_ncsv]",
  "withType": true,
  "roundingMode": "rounding mode type [UP|DOWN|CEILING|FLOOR|HALF_UP|HALF_EVEN]",
  "corrections": "[false|true]",
  "failOnMissingSymbols": false,
  "skipEmptyColumns": false,
  "ncsvEmptySymbolsInResult": false,
  "delta": true,
  "attachMetadataToNcsv": true,
  "order": "[DESC|ASC]",
  "groupFilter": false
}

This endpoint retrieves a specific data prep.

HTTP Request

GET https://api.northgravity.com/dataprep/{dataprepGroupName}/{dataprepName}/{dataprepVersion}?withMetadata=<withMetadata>&resolvePattern=<resolvePattern>

URL Parameters

Parameter	Description	Optional
dataprepGroupName	Name of group where Dataprep was saved.	No
dataprepName	Dataprep name	No
dataprepVersion	Dataprep version	No
withMetadata	If `true`, returns symbols with metadata included. Default: `false`	Yes
resolvePattern	If `true`, resolves and returns all symbols matching the pattern; If `false`, returns the pattern itself without resolving it. Default: `false`	Yes

Delete Data Prep

curl -X DELETE 
  https://api.northgravity.com/dataprep/exampleDataprepId
  -H "Authorization: Bearer yourNgToken"

The above command deletes dataprep and returns 200 code if succeeded.

This endpoint deletes dataprep.

HTTP Request

DELETE https://api.northgravity.com/dataprep/{dataprepId}

URL Parameters

Parameter	Description	Optional
dataprepId	DataPrep id	No

Delete Data Prep by name

curl -X DELETE 
  https://api.northgravity.com/dataprep/name/exampleDataprepName 
  -H "Authorization: Bearer yourNgToken"

The above command deletes dataprep and returns 200 code if succeeded.

This endpoint deletes dataprep.

HTTP Request

DELETE https://api.northgravity.com/dataprep/name/{dataprepName}

URL Parameters

Parameter	Description	Optional
dataprepName	DataPrep name	No

Execute data prep

Execute data prep can be requested with empty json or with a filled json to override execution parameters:

curl -X POST 
  https://api.northgravity.com/dataprep/executor/exampleDataprepId
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
      "symbols": [
          {
              "groupName": "DP_Test_group01",
              "symbol": {
                  "DP_SYM1": "DP_A1"
              },
              "valueColumnName": "columnName",
              "offsetAmount": null,
              "offsetType": null
          }
      ],
      "range": "BETWEEN",
      "dateFrom": "2017-01-01T00:00:00",
      "dateTo": "2019-01-01T00:00:00",
      "outputLayout": "Vertical",
      "outputGroup": "name of the output group",
  }'

If successful, the above command executes data prep and returns code 200 with a job id. If the symbols do not exist, column for that symbol is not displayed.

{
  "jobId": "job_id"
}

Request Body Dataprep Execution

Name	Type	Description	Optional
symbols	Array<Object>	List of symbols. For details see Dataprep symbols	Yes
symbolQuery	boolean	Query for retrieving symbols.	Yes
queryColumnNames	boolean	Column names returned by the symbolQuery.	Yes
range	string	Search period type: [ ALL / BETWEEN / LAST / NEXT ]. Default: `ALL`. More details in Timeseries range	Yes
dateFrom	string	Date (ISO 8601). Start of the date range. Results earlier than this date are excluded. Example: `"2025-09-01T00:00:00"`. Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	Yes
dateTo	string	Date (ISO 8601). End of the date range. Results later than this date are excluded. Example: `"2025-09-02T00:00:00"`. Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	Yes
lastType	string	Options: [ MINUTE / HOUR / DAY / BUSINESS_DAY / MONTH / YEAR / YEAR_TO_DATE / VALUE]. Applied only when range is `"LAST"` or `"NEXT"`.	Yes
lastTypeAmount	string	Number of time units (like days) defined by the `lastType` parameter and is used to determine how far in the past or future a search range should extend — depending on whether `range` is LAST or NEXT. Searches for insert time in that range.	Yes
outputLayout	string	Output format of dataprep file. Options: [ Vertical / Horizontal / Fast_ncsv ]	Yes
outputGroup	string	Name of the output group where the generated files will be saved. Defaults to the user’s home group if not specified.	Yes
decimalPlaces	number	Number of digits after the decimal point. "0" means no decimals; "n" means n digits.	Yes
roundingMode	string (enum)	Rounding mode options: [ UP / DOWN / CEILING / FLOOR / HALF_UP / HALF_EVEN]	Yes
corrections	boolean	If `"true"`, includes corrected(previous) values with timestamps (and insert time if `dateFormat` is `STANDARD`). If `"false"`, returns only the latest values.	Yes
dateFormat	boolean	Format string for date values to return (e.g., "yyyy-MM-dd'T'HH:mm:ss.SSS")	Yes
onDateTime	string	Accepts either an ISO 8601 datetime format (yyyy-MM-dd'T'HH:mm:ss.SSS) or a date placeholder: yesterday, today, or tomorrow. Displays values for dates prior to the specified date.	Yes

HTTP Request

POST https://api.northgravity.com/dataprep/executor/{dataprepId}

Path Parameters

Parameter	Description	Optional
dataprepId	Data prep id	No

Execute data prep by name

Execute data prep can be requested with empty json or with a filled json to override execution parameters:

curl -X POST 
  https://api.northgravity.com/dataprep/executor/name/exampleDataprepName
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
        "symbols": [
            {
                "groupName": "Testgroup01",
                "symbol": {
                    "DP_SYM1": "A1"
                },
                "valueColumnName": "columnName",
                "offsetAmount": null,
                "offsetType": null
            }
        ],
        "range": "LAST",
        "lastType" : "DAY",
        "lastTypeAmount" : "100",
        "outputLayout": "Vertical"
  }'

If successful, the above command executes data prep and returns code 200 with a job id. If the symbols does not exist, column for that symbol is not displayed.

{
  "jobId": "job_id"
}

Request Body

Same as in Execute data prep section.(see Dataprep Execution properties)

HTTP Request

POST https://api.northgravity.com/dataprep/executor/name/{dataprepName}

Path Parameters

Parameter	Description	Optional
dataprepName	Data prep name	No

Log

Search logs

curl https://api.northgravity.com/log?jobid=12345678&size=10
    -H "Authorization: Bearer yourNgToken"

If successful, the above command returns response code 200 with JSON structured response:

{
  "nextPageToken": "next page token",
  "items": [
    {
      "message": "the log message",
      "datetime": "2020-03-31T18:36:50.472539473+00:00",
      "timestamp": 1585679810472,
      "level": "INFO",
      "jobid": "12345678",
      "component": "ts-symbol-loader",
      "source": "ts-symbol-loader-12345678-abcde",
      "logger": "n.g.NGLogger"
    },
    ...
  ]
}

This endpoint returns the logs for the given request.

HTTP Request

GET https://api.northgravity.com/log?jobid=<jobid>&size=<size>&nextPageToken=<token>

URL Parameters

Parameter	Description	Optional
jobid	The jobid of the pipeline or ETL process.	Yes
component	Name of a specific component to filter logs for.	Yes
level	Log level to filter by. Options: INFO, ERROR, WARN.	Yes
size	Number of log entries to return per page.	Yes
nextPageToken	Token used for pagination. Pass this value to retrieve the next page of results.	Yes
tokenExpiration	Duration for which the nextPageToken remains valid. Accepts time units like s (seconds) or m (minutes). Example: "10s", "10m". Default: 1m.	Yes
sort	Sort order: `Asc` for ascending, `Desc` for descending. Defult order is descending(latest entries first).	Yes
logger	Filters logs by logger name.	Yes
task	When set to true, returns only logs generated by tasks. To view logs from other components, this parameter must be omitted.	Yes

Statuses

Search statuses

curl https://api.northgravity.com/status?from=0&size=10&type=ETL&onlyError=false&onlyRunning=false&aggregate=true&query=pjm*
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns json with code 200:

{
  "from": 0,
  "totalSize": 5,
  "items": [
    {
      "jobId": "10a49d80-a134-4978-b299-f0c6da5584be",
      "type": "PIPELINE",
      "types": {
        "pipeline": true,
        "dataprep": false,
        "etl": true
      },
      "name": "All PJM",
      "status": "INFO",
      "startTime": "2025-08-18T13:01:22.819",
      "endTime": "2025-08-18T13:01:58.024",
      "payload": {
        "pipelineName": "All PJM",
        "groupName": "Simple Auto Pipeline",
        "rootId": "9834d80d-126d-49f3-b82a-574b109e6cae",
        "lastChangeBy": "example_user2@northgravity.com",
        "userName": "example_user2@northgravity.com",
        "version": "1",
        "pipelineId": "9834d80d-126d-49f3-b82a-574b109e6cae"
      },
      "warnStatuses": [],
      "latestStatus": {
        "eId": "68aa5ba0-61a6-4236-90a1-17fc1577300e",
        "prevEId": "bc32bb84-bd28-4687-887e-bbadc4291422",
        "component": "Datalake",
        "status": "INFO",
        "message": "Uploading file finished.",
        "startTime": "2025-08-18T13:01:55.174",
        "endTime": "2025-08-18T13:01:57.398",
        "payload": {
          "fileName": "All PJM Symbols.csv",
          "groupName": "Example Group",
          "userName": "example_user@northgravity.com",
          "fileType": "GDP",
          "fileId": "919ea007-377e-45c2-8591-217c94eaad71"
        }
      },
      "componentStatuses": [
        {
          "eId": "ee64cd63-d8fb-42f4-855b-00010613d471",
          "prevEId": "",
          "component": "Exec-Manual",
          "status": "INFO",
          "message": "Started by : rafal.mierniczek@northgravity.com",
          "startTime": "2025-08-18T13:01:22.259",
          "endTime": "2025-08-18T13:01:22.259",
          "payload": {}
        },
        {
          "eId": "bc32bb84-bd28-4687-887e-bbadc4291422",
          "prevEId": "",
          "component": "Data Prep",
          "status": "INFO",
          "message": "The file has been generated.",
          "startTime": "2025-08-18T13:01:23.034",
          "endTime": "2025-08-18T13:01:57.494",
          "payload": {
            "nodeId": "50f1538c-0720-4a26-984e-c9175bc4fd65",
            "version": "1.0.23",
            "pipelineId": "9834d80d-126d-49f3-b82a-574b109e6cae",
            "fileId": "5761bacd-1676-4d3f-a17a-5dce2bd28799",
            "fileName": "All PJM Symbols.csv",
            "fileType": "GDP",
            "groupName": "Example Group",
            "dataprepId": "0c4a3bfb-a0e5-4c66-9998-4bbb9cbd2dcf",
            "dataprepName": "All PJM Symbols"
          }
        },
        {
          "eId": "68aa5ba0-61a6-4236-90a1-17fc1577300e",
          "prevEId": "bc32bb84-bd28-4687-887e-bbadc4291422",
          "component": "Datalake",
          "status": "INFO",
          "message": "Uploading file finished.",
          "startTime": "2025-08-18T13:01:55.174",
          "endTime": "2025-08-18T13:01:57.398",
          "payload": {
            "fileName": "All PJM Symbols.csv",
            "groupName": "Example Group",
            "userName": "example_user@northgravity.com",
            "fileType": "GDP",
            "fileId": "919ea007-377e-45c2-8591-217c94eaad71"
          }
        }
      ]
    },
    ...
  ]
}

This endpoint executes a search for statuses from all file groups.

HTTP Request

GET https://api.northgravity.com/status

URL Parameters

Name	Description	Optional
from	Index of first element to return	Yes
size	Number of statuses returned. Default number is 10 000.	Yes
jobId	Filters by job ID.	Yes
query	Filters by status name. Supports * wildcards.	Yes
type	Filters by status type. Options: [ DATAPREP / ETL / PIPELINE ]	Yes
groupName	Filters by group name of datapreps, pipelines, processes, or files.	Yes
aggregate	Returns only the latest status per status name.	Yes
onlyError	If `true`, includes only items whose latest status is `ERROR`.	Yes
onlyRunning	If `true`, includes only items whose latest status is `RUNNING`.	Yes
onlyWarn	If `true`, includes only items whose latest status is `WARN`.	Yes
onlyPaused	If `true`, includes only items whose latest status is `PAUSED`.	Yes
onlySuccess	If `true`, includes only items whose latest status is `INFO` (success).	Yes
tag	For `PIPELINE` type: filters by pipeline tags. Tags must be URL-encoded in brackets (`[]`).	Yes
tagOperator	Defines tag matching logic: `or` for OR search, otherwise uses AND (default).	Yes

Search for multiple statuses

curl -X POST https://api.northgravity.com/status/search
  -H "Authorization: Bearer yourNgToken" 
  -H "Content-Type: application/json"   
  -d '{
    "jobIds": [
            "4235c641-334c-4e89-86a3-97d11db69236",
            "ef5e43a4-9133-44f0-ac3d-4562421fc966"
      ] 
    }'

If successful, the above command returns json with code 200:

[
  {
    "jobId": "4235c641-334c-4e89-86a3-97d11db69236",
    "type": "PIPELINE",
    "types": {
      "pipeline": true,
      "dataprep": false,
      "etl": true
    },
    "name": "Example pipeline 1",
    "status": "ERROR",
    "startTime": "2025-12-05T15:00:17.630",
    "endTime": "2025-12-05T15:00:52.736",
    "payload": {
      "pipelineName": "Example pipeline 1",
      "groupName": "example_group",
      "rootId": "be6112ba-05ea-4ee3-89b1-d9efa3276cc4",
      "lastChangeBy": "example_user",
      "version": "8",
      "pipelineId": "8c44ed4e-4fd3-4868-a688-eefc46188c8c"
    },
    "warnStatuses": [
      "e8b47c2c-b2d3-443f-be4c-089d2b185b3b"
    ],
    "latestStatus": {
      "eId": "ed939ee9-5159-4132-a7c6-fef0f8db5762",
      "prevEId": "e8b47c2c-b2d3-443f-be4c-089d2b185b3b",
      "component": "NCSV Validator",
      "status": "ERROR",
      "message": "NCSV contains errors. File name: [output_task_{yyyy-MM-dd}] group [example_group] id: [fdd368a5-982b-4819-a961-2f979ae088bc]. Errors: [row: [-1], column: [-1], cause: [Parser error. Missing at least one metadata header.]]",
      "startTime": "2025-12-05T15:00:41.117",
      "endTime": "2025-12-05T15:00:41.819",
      "payload": {
        "fileName": "output_task_WIG_{yyyy-MM-dd}",
        "groupName": "example_group",
        "fileType": "NCSV",
        "fileId": "fdd368a5-982b-4819-a961-2f979ae088bc"
      }
    },
    "componentStatuses": [
      {
        "eId": "0e88507c-d6b8-458b-a0eb-d8f0748d5075",
        "prevEId": "",
        "component": "scheduler",
        "status": "INFO",
        "message": "{prevFireTime=2025-12-04T15:00:08.351, origin=scheduler, jobGroup=example_group---pipeline1, NGT_DETAILS={\"PIPELINE_ID\":\"8c44ed4e-4fd3-4868-a688-eefc46188c8c\"}, NGT_JOB_ID=, NGT_TYPE=cron, NGT_START=0, NGT_TIME_ZONE=Europe/Warsaw, NGT_CRON=0 0 16 ? * MON-FRI, jobComponent=mgmt, firetime=1764946811626, NGT_FRAME=518922de-5877-40e1-a8c3-9bcc7d8842c2_45781684-57f7-4ec7-9fe8-f06e5929f5c3, jobDetails=null}",
        "startTime": "2025-12-05T15:00:11.661",
        "endTime": "2025-12-05T15:00:11.661",
        "payload": {}
      },
      {
        "eId": "f0a988db-4cfc-4c5b-85f6-1b346771c15f",
        "prevEId": "",
        "component": "Schedule Trigger",
        "status": "INFO",
        "message": "INFO",
        "startTime": "2025-12-05T15:00:18.572",
        "endTime": "2025-12-05T15:00:18.572",
        "payload": {
          "nodeId": "137e2504-17c4-4b08-9071-3b8a8b80b8cc",
          "version": "1.0.0",
          "pipelineId": "8c44ed4e-4fd3-4868-a688-eefc46188c8c"
        }
      }
    ]
  },
  {
    "jobId": "ef5e43a4-9133-44f0-ac3d-4562421fc966",
    "type": "PIPELINE",
    "types": {
      "pipeline": true,
      "dataprep": false,
      "etl": false
    },
    "name": "Example pipeline 2",
    "status": "RUNNING",
    "startTime": "2025-10-16T10:32:49.761",
    "endTime": "2025-10-16T10:32:49.761",
    "payload": {
      "pipelineName": "Example pipeline 2",
      "groupName": "example_group",
      "rootId": "b343731a-451f-4da4-a8e8-7f5623441a59",
      "lastChangeBy": "example_user",
      "userName": "example_user",
      "version": "14",
      "pipelineId": "879c59ed-bdb5-475d-9fc6-b96bdaaf218c"
    },
    "warnStatuses": [],
    "componentStatuses": [
      {
        "eId": "ddf85191-19b0-450b-856d-630a9c04b5df",
        "prevEId": "",
        "component": "Exec-Manual",
        "status": "INFO",
        "message": "Started by : example_user",
        "startTime": "2025-10-16T10:32:46.651",
        "endTime": "2025-10-16T10:32:46.651",
        "payload": {}
      },
      {
        "eId": "9eef5aaa-8085-49c4-8f94-8e409577c43d",
        "prevEId": "",
        "component": "Datalake",
        "status": "INFO",
        "message": "Uploading file finished.",
        "startTime": "2025-10-16T10:32:50.001",
        "endTime": "2025-10-16T10:33:32.279",
        "payload": {
          "fileName": "tilesOrder.txt",
          "groupName": "example_group",
          "userName": "example_user",
          "fileType": "SOURCE",
          "fileId": "6c9435a6-d498-4a15-821c-0fa319ce867f"
        }
      },
      {
        "eId": "92867057-8b36-4754-be1f-36c563ef4959",
        "prevEId": "",
        "component": "Email",
        "status": "INFO",
        "message": "INFO",
        "startTime": "2025-10-16T10:33:51.433",
        "endTime": "2025-10-16T10:33:56.591",
        "payload": {
          "nodeId": "35512fde-5861-40d6-ba2e-7220e399d6fd",
          "version": "1.0.5",
          "pipelineId": "879c59ed-bdb5-475d-9fc6-b96bdaaf218c"
        }
      }
    ]
  }
]

HTTP Request

POST https://api.northgravity.com/status/search

Request Body

Name	Type	Description	Optional
jobIds	Array<String>	Filters by a list of job IDs.	No

Get timeseries status for pipeline

curl https://api.northgravity.com/status/pipeline/ts/612917ae-eee4-45ee-92ff-e727371d8021aa
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns json with code 200:

{
  "isRunningOrPending": false,
  "isError": false,
  "message": [
    "File: 'file1.csv' Group: 'example_group1' File id: '3437ec8b-c0b0-47db-95db-631558c8cef4'.\n\rTS status: [TimeSeries finished: TsProcessingStatus(isFinished=true, status=INFO)] | [TimeSeries SQL finished: TsProcessingStatus(isFinished=true, status=INFO)] | [TimeSeries Symbols finished: TsProcessingStatus(isFinished=true, status=INFO)]",
    "File: 'file2.csv' Group: 'example_group2' File id: 'c642105b-5722-45f0-a2f0-cdc86350bea2'.\n\rTS status: [TimeSeries finished: TsProcessingStatus(isFinished=true, status=INFO)] | [TimeSeries SQL finished: TsProcessingStatus(isFinished=true, status=INFO)] | [TimeSeries Symbols finished: TsProcessingStatus(isFinished=true, status=INFO)]",
    "File: 'file3' Group: 'null' File id: '89f0853e-ff21-3adb-927a-68776b40b535'.\n\rTS status: [TimeSeries finished: TsProcessingStatus(isFinished=true, status=INFO)] | [TimeSeries SQL finished: TsProcessingStatus(isFinished=true, status=INFO)] | [TimeSeries Symbols finished: TsProcessingStatus(isFinished=true, status=INFO)]"
  ]
}

This endpoint returns timeseries statuses for a given pipeline job.

HTTP Request

GET https://api.northgravity.com/status/pipeline/ts/{pipelineJobId}

URL Parameters

Name	Description	Optional
pipelineJobId	Pipeline job Id.	No

Send status

curl -X POST 
  https://api.northgravity.com/status 
  -H "Authorization: Bearer yourNgToken" 
  -H "Content-Type: application/json"   
  -d '{
    "eId": "uuid",
    "jobId": "uuid",
    "status": "INFO",
    "message": "OK",
    "className": "com.ng.classname",
    "groupName": "groupName",
    "componentName": "Component name",
    "time": "2011-12-03T10:15:30+01:00",
    "startTime": "2011-12-03T10:15:30+01:00"
}'

If successful, the above command returns code 200.

This endpoint returns statuses for a given job, component, and group or returns all statuses if no parameters are provided.

HTTP Request

POST https://api.northgravity.com/status

Request Body

Name	Type	Description	Optional
eId	string	Execution Id	Yes
jobId	string	Job id	No
status	string(enum)	Statu type: [ PENDING / RUNNING / INFO / WARN / WARN_STOP / ERROR ]	No
message	string	Message for status	No
className	string	Name of the class/or place in the code from which this status was send (information which part of code send this status)	No
groupName	string	Group name to which this status should be assigned. For pipelines should be group in which pipeline is.	Yes
componentName	string	Name of the component or task from which status is send	No
time	string	Current time in ISO format in UTC timezone. Example: "2011-12-03T10:15:30+01:00".	No
startTime	string	Time when component or task started working. ISO format in UTC timezone. Example: "2011-12-03T10:15:30+01:00".	Yes

Pipeline Task Variables

The following environment variables provide all necessary information for sending task status updates:

JOBID – Unique job identifier
EID – Execution identifier
NG_COMPONENT_NAME – Name of the component or task
NG_API_ENDPOINT – Base API URL (e.g., https://api.northgravity.com)
NG_API_AUTHTOKEN – Authorization token for API requests

Attach payload to status.

curl -X PUT 
  https://api.northgravity.com/status/payload 
  -H "Authorization: Bearer yourNgToken" 
  -H "Content-Type: application/json"   
  -d '{
    "eId": "40bce248-bb26-4abf-bf24-8625d11292f4",
    "payload": {
          "fileName": "testFile.txt",
          "groupName": "example_group",
          "userName": "example_user",
          "fileId": "6c9435a6-d498-4a15-821c-0fa319ce867f",
          "comment": "File uploaded successfully"
    }
}'

If successful, the above command returns code 200.

This endpoint allows attaching a payload to an existing status identified by eId.

HTTP Request

PUT https://api.northgravity.com/status/payload

Request Body

Name	Type	Description	Optional
eId	string	Execution Id	No
payload	Array<Object>	Key-value pairs. At least one key is required.	No

Errors

The NorthGravity API uses the following error codes:

Error Code	Meaning
400	Bad Request -- The request you sent is incorrect.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The requested resource is hidden and may be accessed by the administrators only.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The resource requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many times! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Model Management

Create task

curl -X POST
  https://api.northgravity.com/mgmt/task
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
       "name": "Task Name",
       "groupName": "Destination Group",
       "readableName": "Readable task name",
       "description": "Description of the task",
       "cpu": 1,
       "memory": 4,
       "imageUrl": "example image url of docker in docker repository : `123.dkr.ecr.us-east-1.amazon.com/example-task:1.0.0`",
       "privateCredentialsId": "id",
       "category": "Other",
       "icon": "ui icon of the task",
       "params": [
          {
            "additional": false,
            "description": "Example description",
            "dynamic": false,
            "name": "File Load Parameter",
            "optional": false,
            "options": [],
            "type": "INPUT",
            "valueType": "DATALAKE_FILE"
        },
          {
            "additional": false,
            "defaultValue": "exampleText",
            "description": "Example description",
            "dynamic": false,
            "name": "Example String parameter",
            "optional": false,
            "options": [],
            "type": "INPUT",
            "valueType": "STRING"
        },
       ]
    }'

If successful, the above command returns status code 201 and JSON structured response:

{
  "taskId": "exampleTaskId"
}

This endpoint creates a task file in datalake and task definition which can be used in pipelines.

HTTP Request

POST https://api.northgravity.com/mgmt/task

Request Body

Name	Type	Description	Optional
name	string	Name of task (3–32 characters, only alphanumerics and spaces).	No
groupName	string	Group name of task.	No
readableName	string	Readable name of task.	No
description	string	Description of task (3–100 characters).	No
imageUrl	string	URL of task Docker image (example: `123.dkr.ecr.us-east-1.amazon.com/example-name:0.0.1-SNAPSHOT`).	No
cpu	number	Number of CPU cores. Minimum: `1`. Default: `1`.	Yes
memory	number	Amount of RAM memory. Minimum: `4`. Default: `512`.	Yes
category	string (enum)	Category of the task. Options: [ Triggers/ Inputs / Downloaders / Parsers / Pre-processing / ML Preprocessing / Features engineering / ML Forecasting / Trading Forecasting / Code Execution / NLP / Utils / File Converter / Post-trade / Results / Quality Checks / Notifications / Other ]. Default: `Other`.	Yes
icon	string	Icon of the task.	Yes
source	string (enum)	Task source. Options: [ USER / COMPANY / CORE ]. Default: `COMPANY`.	Yes
execType	string (enum)	Execution type. Options: [ LAMBDA / FARGATE ]. Default: `FARGATE`.	Yes
timeout	number	Number of minutes before the task times out. Default: `14440`.	Yes
params	array	List of task parameters.	Yes
└─ name	string	Name of task parameter (3–32 characters).	No(if params are used)
└─ description	string	Description of task parameter (3–100 characters).	No(if params are used)
└─ defaultValue	string	Default value of task param.	Yes
└─ type	string (enum)	Type of task parameter. Options: [ INPUT / OUTPUT ].	No(if params are used)
└─ valueType	string (enum)	Type of parameter value. Options: [ DATALAKE_FILE / GROUP / GROUP_READ / SELECT / MULTI_SELECT / STRING / TEXT_AREA / BOOLEAN / BOOLEAN_PAUSE / NUMBER / DATA_PREP_PARAM / DATE / SYMBOL / PASSWORD / SECRET / EMAIL / PIPELINE / TIMEZONE / SLACK_NAME / HOLIDAY_CALENDAR / JSON / CRON / SYMBOL_FILTER/ MULTI_SYMBOL_FILTER / METADATA_FILTER / MULTI_METADATA_FILTER / SYMBOL_COLUMN / MULTI_SYMBOL_COLUMN/ TIMEZONE / SLACK_NAME / CRON / SYMBOL_KEY / MULTI_SYMBOL_KEY / SYMBOL_VALUE / MULTI_SYMBOL_VALUE / DATA_SHARING_PROVIDER ]. Default: `STRING`	Yes
└─ dynamic	boolean	If `true`, value for this parameter can be taken from or to a different task.	Yes
└─ additional	boolean	If `true`, parameter is hidden in UI and can be accessed by clicking on eye icon.	Yes
└─ optional	boolean	If `true`, parameter is not required to run task.	Yes
└─ isHidden	boolean	If `true`, parameter is not visible in UI.	Yes
└─ expression	boolean	If true, an expression can be provided for this task parameter. Examples of expressions: `something-${otherParamName}.csv`, `something-${uuuu-MM-dd'T'HH:mm:ss}.csv`, `something-${date("uuuu-MM-dd'T'HH:mm:ss")}.csv`, `something-${date("uuuu-MM-dd'T'HH:mm:ss", "America/Chicago"))}.csv`.	Yes
└─ options	array	Options to choose from the dropdown. Only for the `SELECT` and `MULTISELECT`.	Yes
└─ withProvider	boolean	If `true`, allows selecting files from data providers. Used only when `valueType` is `DATALAKE_FILE`.	Yes
└─ conditionParam	string	Name of another task parametr for which contions is checked. If of condition check is hidden then this parameter also will be hidden.	Yes
└─ conditionOperation	string	Condition operation. see	Yes
└─ conditionValue	string	Value used for condition comparison. May be omitted depending on the operation.	Yes
└─ dependsOn	string	Gives name of parametr on which this parameter depends on. Only for `SYMBOL_COLUMN`, `SYMBOL_KEY`, `METADATA_KEY`, `MULTI_SYMBOL_COLUMN`, `MULTI_SYMBOL_KEY`, `MULTI_METADATA_KEY`, `DATA_SHARING_PROVIDER`.	Yes
└─ fileExtension	string	Extension of file. For example `csv`, `txt`.	No(if valueType is DATALAKE_FILE)
└─ fileType	string	Type of file loaded from datalake. Options: [ NCSV / COMMAND_JSON / CONFIG / DATA_PREP / D_NCSV / EMAIL / GDP / INSIGHT / MARKDOWN / PIPELINE / SOURCE / SYM_NCSV / TASK / UIConfig ]	No(if valueType is DATALAKE_FILE)

Condition operations

conditionOperation — Operation used to compare conditionParam and conditionValue.

eq, == — equal (case-insensitive)
neq, != — not equal (case-insensitive)
gt, > — greater than (numeric)
lt, < — less than (numeric)
gte, >=, => — greater than or equal (numeric)
lte, <=, =< — less than or equal (numeric)
notnull — conditionParam exists (conditionValue optional)
isnull — conditionParam does not exist (conditionValue optional)
oneOf — value is one of comma-separated values (case-insensitive)
includes — value contains text (case-insensitive)
not_includes — value does not contain text (case-insensitive)

Update task

curl -X PUT
  https://api.northgravity.com/mgmt/task/{taskId}
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
       "name": "Task Name",
       "groupName": "Destination Group",
       "readableName": "Readable task name",
       "description": "Description of the task",
       "cpu": 1,
       "memory": 4,
       "imageUrl": "example image url of docker in docker repository : `123.dkr.ecr.us-east-1.amazon.com/example-task:1.0.0`",
       "privateCredentialsId": "",
       "category": "Other",
       "icon": "ui icon of the task",
       "source": "source of the task",
       "markdownId": "id of the markdown file",
       "params": [
          {
            "name": "ENV_NAME",
            "description": "desc",
            "type": "INPUT",
            "dynamic": true
          },
          {
            "name": "STRING_PARAM",
            "description": "String parameter",
            "type": "INPUT",
            "dynamic": false,
            "defaultValue": "Test"
          }
       ]
    }'

If successful, the above command returns 200 code with JSON structured response:

{
  "taskId": "updated task id or same task id if version not changed"
}

This endpoint updates a task. If only the parameters icon, description, category, markdownId, source are changed - the version will not be incremented. If other parameters are changed, version will be incremented.

HTTP Request

PUT https://api.northgravity.com/mgmt/task/{taskId}

Request Body

Name	Type	Description	Optional
name	string	Name of task (3–32 characters, only alphanumerics and spaces).	No
groupName	string	Group name of task.	No
readableName	string	Readable name of task.	No
description	string	Description of task (3–100 characters). Changing this parameter does not affect the version.	No
imageUrl	string	URL of task Docker image (example: `123.dkr.ecr.us-east-1.amazon.com/example-name:0.0.1-SNAPSHOT`).	No
cpu	number	Number of CPU cores. Minimum: `1`. Default: `1`.	Yes
memory	number	Amount of RAM memory. Minimum: `4`. Default: `512`.	Yes
category	string (enum)	Category of the task. Options: [ Triggers/ Inputs / Downloaders / Parsers / Pre-processing / ML Preprocessing / Features engineering / ML Forecasting / Trading Forecasting / Code Execution / NLP / Utils / File Converter / Post-trade / Results / Quality Checks / Notifications / Other ]. Default: `Other`. Changing this parameter does not affect the version.	Yes
icon	string	Icon of the task. Changing this parameter does not affect the version.	Yes
source	string (enum)	Task source. Options: [ USER / COMPANY / CORE ]. Default: `COMPANY`. Changing this parameter does not affect the version.	Yes
execType	string (enum)	Execution type. Options: [ LAMBDA / FARGATE ]. Default: `FARGATE`.	Yes
timeout	number	Number of minutes before the task times out. Default: `14440`.	Yes
markdownId	string	File ID of the markdown file in the datalake. Changing this parameter does not affect the version.	Yes
params	array	List of task parameters.	Yes
└─ name	string	Name of task parameter (3–32 characters).	No(if params are used)
└─ description	string	Description of task parameter (3–100 characters).	No(if params are used)
└─ defaultValue	string	Default value of task param.	Yes
└─ type	string (enum)	Type of task parameter. Options: [ INPUT / OUTPUT ].	No(if params are used)
└─ valueType	string (enum)	Type of parameter value. Options: [ DATALAKE_FILE / GROUP / GROUP_READ / SELECT / MULTI_SELECT / STRING / TEXT_AREA / BOOLEAN / BOOLEAN_PAUSE / NUMBER / DATA_PREP_PARAM / DATE / SYMBOL / PASSWORD / SECRET / EMAIL / PIPELINE / TIMEZONE / SLACK_NAME / HOLIDAY_CALENDAR / JSON / CRON / SYMBOL_FILTER/ MULTI_SYMBOL_FILTER / METADATA_FILTER / MULTI_METADATA_FILTER / SYMBOL_COLUMN / MULTI_SYMBOL_COLUMN/ TIMEZONE / SLACK_NAME / CRON / SYMBOL_KEY / MULTI_SYMBOL_KEY / SYMBOL_VALUE / MULTI_SYMBOL_VALUE / DATA_SHARING_PROVIDER ]. Default: `STRING`	Yes
└─ dynamic	boolean	If `true`, value for this parameter can be taken from or to a different task.	Yes
└─ additional	boolean	If `true`, parameter is hidden in UI and can be accessed by clicking on eye icon.	Yes
└─ optional	boolean	If `true`, parameter is not required to run task.	Yes
└─ isHidden	boolean	If `true`, parameter is not visible in UI.	Yes
└─ expression	boolean	If true, an expression can be provided for this task parameter. Examples of expressions: `something-${otherParamName}.csv`, `something-${uuuu-MM-dd'T'HH:mm:ss}.csv`, `something-${date("uuuu-MM-dd'T'HH:mm:ss")}.csv`, `something-${date("uuuu-MM-dd'T'HH:mm:ss", "America/Chicago"))}.csv`.	Yes
└─ options	array	Options to choose from the dropdown. Only for the `SELECT` and `MULTISELECT`.	Yes
└─ withProvider	boolean	If `true`, allows selecting files from data providers. Used only when `valueType` is `DATALAKE_FILE`.	Yes
└─ conditionParam	string	Name of another task parametr for which contions is checked. If of condition check is hidden then this parameter also will be hidden.	Yes
└─ conditionOperation	string	Condition operation. see	Yes
└─ conditionValue	string	Value used for condition comparison. May be omitted depending on the operation.	Yes
└─ dependsOn	string	Gives name of parametr on which this parameter depends on. Only for `SYMBOL_COLUMN`, `SYMBOL_KEY`, `METADATA_KEY`, `MULTI_SYMBOL_COLUMN`, `MULTI_SYMBOL_KEY`, `MULTI_METADATA_KEY`, `DATA_SHARING_PROVIDER`.	Yes
└─ fileExtension	string	Extension of file. For example `csv`, `txt`.	No(if valueType is DATALAKE_FILE)
└─ fileType	string	Type of file loaded from datalake. Options: [ NCSV / COMMAND_JSON / CONFIG / DATA_PREP / D_NCSV / EMAIL / GDP / INSIGHT / MARKDOWN / PIPELINE / SOURCE / SYM_NCSV / TASK / UIConfig ]	No(if valueType is DATALAKE_FILE)

URL Parameters

Parameter	Description	Optional
taskId	Unique id of the task	No

Get task

curl https://api.northgravity.com/mgmt/task/exampleTaskId
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 1,
  "items": [
    {
      "id": "example-task-uuid",
      "root": "example-root-uuid",
      "latest": true,
      "removed": false,
      "archived": false,
      "prevManualFireTime": "2025-12-16T07:38:15.512",
      "name": "exampleTask",
      "version": 2,
      "lastChange": "2025-12-16T07:38:45.600",
      "lastChangeBy": "marcin.szczuka@northgravity.com",
      "groupName": "exampleGroup",
      "tags": [
        "exampleTag1"
      ],
      "uiPayloadId": "example-ui-payload-uuid"
    }
  ]
}

This endpoint returns the task configuration information.

HTTP Request

GET https://api.northgravity.com/mgmt/task/{taskId}

URL Parameters

Parameter	Description	Optional
taskId	Unique id of the task	No

Search tasks

curl https://api.northgravity.com/mgmt/task?query=exampleTask&from=0&size=1&sortBy=name
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 4,
  "items": [
    {
      "id": "6626c2e5-42bb-4b93-9765-95a61ddcc8cd",
      "name": "exampleTask",
      "readableName": "Example Task",
      "description": "Example task description",
      "groupName": "exampleGroup",
      "version": "1.0.0",
      "arrivalTime": "2025-10-22T15:03:07.595",
      "imageUrl": "example image url of docker in docker repository : `123.dkr.ecr.us-east-1.amazon.com/example-task:1.0.0`",
      "privateCredentialsId": "",
      "markdownId": "exampleMarkdownId",
      "cpu": 1,
      "memory": 2048,
      "timeout": 900,
      "params": [
        {
          "name": "Input File",
          "description": "File which you want to process",
          "type": "INPUT",
          "valueType": "DATALAKE_FILE",
          "dynamic": true,
          "optional": false,
          "withProvider": true,
          "additional": false,
          "isHidden": false,
          "expression": false
        },
        {
          "name": "Output Group",
          "description": "Where to save the output of the task",
          "type": "INPUT",
          "valueType": "GROUP",
          "dynamic": false,
          "optional": false,
          "withProvider": false,
          "additional": false,
          "isHidden": false,
          "expression": false
        },
        {
          "name": "Output File",
          "description": "Returned file from the task",
          "type": "OUTPUT",
          "valueType": "DATALAKE_FILE",
          "dynamic": true,
          "optional": false,
          "withProvider": false,
          "additional": false,
          "isHidden": false,
          "expression": false
        }
      ],
      "active": true,
      "category": "Other",
      "categoryReadableName": "Other",
      "icon": "ExampleIcon",
      "source": "NorthGravity",
      "execType": "LAMBDA_DOCKER",
      "root": "exmapleRootId",
      "user": "exampleUser@northgravity.com",
      "cpuArch": "",
      "latest": true
    }
  ]
}

HTTP Request

GET https://api.northgravity.com/mgmt/task?query=<query>&size=<size>&from=<from>

URL Parameters

Parameter	Description	Optional
query	Query to search tasks. User can provide just a string to search all fields or can provide in it any number of fields: `name`, `description`, `type`, `category`. Both full-text and keyword matching are supported.	No
size	The maximum size of returned hits list. Max size is `1000`. Default size is `100`.	Yes
from	The index of the first hit. It allows to do paging easily. Default value is `0`.	Yes
sortBy	Field name to sortBy. Examples: `name`, `category`.	Yes
sortOrder	Sort order: `asc` for ascending, `desc` for descending. Defult order is ascending.	Yes

Sample queries:

query=category=Other&name=Hello World&description=Desc
query=category=Other&Hello World
query=category=Utils&description=Sample description
query=category=Other,

List versions of task

This endpoint lists previous versions of the task with given taskId.

curl https://api.northgravity.com/mgmt/task/versions/exampleTaskId?query=*from=0&size=10
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns 200 code with JSON structured response:

{
  "from": 0,
  "totalSize": 4,
  "items": [
    {
      "id": "example-version-uuid-2",
      "name": "exampleTask",
      "readableName": "Example Task",
      "description": "Example task description",
      "groupName": "exampleGroup",
      "version": "2",
      "arrivalTime": "2025-10-22T15:03:07.595",
      "imageUrl": "example image url of docker in docker repository : `123.dkr.ecr.us-east-1.amazon.com/example-task:1.0.0`",
      "privateCredentialsId": "",
      "markdownId": "exampleMarkdownId",
      "cpu": 1,
      "memory": 2048,
      "timeout": 900,
      "params": [
        {
          "name": "Example parameter",
          ...
        },
        {
          "name": "Example parameter 2",
          ...
        }
      ],
      "active": true,
      "category": "Other",
      "categoryReadableName": "Other",
      "icon": "ExampleIcon",
      "source": "NorthGravity",
      "execType": "LAMBDA_DOCKER",
      "root": "exmapleRootId",
      "user": "exampleUser@northgravity.com",
      "cpuArch": "",
      "latest": true
    },
    {
      "id": "example-version-uuid-1",
      "name": "exampleTask",
      "readableName": "Example Task",
      "description": "Example task description",
      "groupName": "exampleGroup",
      "version": "1",
      "arrivalTime": "2025-10-22T15:03:07.595",
      "imageUrl": "example image url of docker in docker repository : `123.dkr.ecr.us-east-1.amazon.com/example-task:1.0.0`",
      "privateCredentialsId": "",
      "markdownId": "exampleMarkdownId",
      "cpu": 1,
      "memory": 2048,
      "timeout": 900,
      "params": [
        {
          "name": "Example parameter",
          ...
        }
      ],
      "active": true,
      "category": "Other",
      "categoryReadableName": "Other",
      "icon": "ExampleIcon",
      "source": "NorthGravity",
      "execType": "LAMBDA_DOCKER",
      "root": "exmapleRootId",
      "user": "exampleUser@northgravity.com",
      "cpuArch": "",
      "latest": false
    }
  ]
}

HTTP Request

GET https://api.northgravity.com/mgmt/task/versions/{taskId}?query=<query>size=<size>&from=<from>

URL Parameters

Parameter	Description	Optional
taskId	Unique task id of the latest version of the task.	No
query	Query to search task versions. Use `*` to list all task versions or specify a particular version (e.g. `1.0.0`).	No
size	The maximum size of returned hits list. Max size is `1000`. Default size is `100`.	Yes
from	The index of the first hit. It allows to do paging easily. Default value is `0`.	Yes

EXECUTE TASK

This endpoint executes a task immediately.

curl -X POST https://api.northgravity.com/mgmt/task/execute
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
        "taskName":"Task name",
        "taskGroupName":"Group name, where task file is kept in Datalake", 
        "taskVersion":"Task version e.g. 1.0.0"
        "params": {
            "Input File": "{\"name\":\"ExampleFile.csv\",\"groupName\":\"Example file group\"}",
            "Output Group": "Example output group",
            "Example param": "Example param value"
        }
    }'

If successful, the above command returns 200 code with JSON structured response:

{
  "lambdaResponse": "{\"Output File\":\"Example Output File Content\"}"
}

HTTP Request

GET https://api.northgravity.com/mgmt/task/execute

URL Parameters

Parameter	Description	Optional
withOpenAiKey	If `true`, injects OpenApi key to parameter with name "OpenAI API Key Secret Name" or "Amazon Bedrock Secret Name" in task.	Yes

Request Body

Name	Type	Description	Optional
taskName	string	Name of the task.	No
taskGroupName	string	Name of the group where the task files are stored in the Datalake.	No
taskVersion	string	Version of the task (e.g. `1.0.0`).	No

TASK USAGE

This endpoint returns information about pipelines that use a specific task.

curl -X POST https://api.northgravity.com/mgmt/task/usage/{taskId}
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json"

If successful, the above command returns 200 code with JSON structured response:

{
  "pipelineAndTasks": [
    {
      "name": "example-pipeline",
      "id": "example-pipeline-uuid",
      "version": 1,
      "group": "Example Group",
      "tags": [],
      "taskAndVersions": [
        {
          "id": "example-task-uuid-1",
          "name": "example-task",
          "readableName": "Example Task",
          "version": "1.0.0",
          "files": []
        }
      ]
    }
  ]
}

HTTP Request

GET https://api.northgravity.com/mgmt/task/usage/{taskId}?allTaskVersions=<allTaskVersions>

URL Parameters

Parameter	Description	Optional
taskId	Unique task id of the latest version of the task.	No
allTaskVersions	If `true`, shows usage for all versions of task.	Yes

FILE USAGE

This endpoint returns information about entities that use the specified file (such as tasks, pipelines, or datapreps).

curl -X POST https://api.northgravity.com/mgmt/task/file/usage?name=exampleFileName&groupName=Example Group Name&fileType=all
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns 200 code with JSON structured response:

{
  "pipelineAndTasks": [
    {
      "name": "example pipeline name",
      "id": "example-pipeline-uuid",
      "version": 1,
      "group": "Example Group Name",
      "tags": [],
      "taskAndVersions": [
        {
          "id": "example-task-uuid-1",
          "name": "example-task-1",
          "readableName": "Example Task 1",
          "version": "1.0.0",
          "files": []
        },
        {
          "id": "example-task-uuid-2",
          "name": "example-task-2",
          "readableName": "Example Task 2",
          "version": "1.0.0",
          "files": [
            {
              "name": "exampleFileName",
              "groupName": "Example Group Name",
              "type": "DATALAKE_FILE",
              "taskId": "example-task-uuid-2"
            }
          ]
        }
      ]
    }
  ]
}

HTTP Request

GET https://api.northgravity.com/mgmt/task/file/usage?name=<name>&groupName=<groupName>&fileType=<fileType>

URL Parameters

Parameter	Description	Optional
name	Name of the file, dataprep, pipeline etc.	No
groupName	Name of the group where the file is stored.	No
fileType	Type of searched file. Options: [ data_prep_param / pipeline / datalake_file / dataprep / datalake / all ]	Yes

Create pipeline

curl -X POST
  https://api.northgravity.com/mgmt/pipeline
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
    "pipeline":{
        "name":"Pipeline name",
        "groupName":"Name of the group",
        "tags":["tag1", "tag2"],
        "summary": "example summary of the pipeline",
    },
    "batchConfig": {
        "tasks": [
            {
                "taskId": "Task id",
                "taskName": "Task name",
                "taskReadableName": "Readable name",
                "taskGroup": "Group name, where task is kept in Datalake",
                "taskCategory": "Category where task is located",
                "taskVersion": "Task version e.g. `1.0.1`",
                "prevTasks": [
                    {
                        "id": "Task id"
                    }
                ],
                "nextTasks": [
                    {
                        "id": "Task id"
                    }
                ],
                "taskOverrides": {
                    "cpu":"1",
                    "memory":"4",
                    "timeout":"14400",
                    "params": {
                        "DATA_GROUP_NAME": "New group name",
                        "Example Param": "Example Value"
                    }
                },
                "arraySize": 1,
                "sequential": false
            }
        ]
    }
    ,
    "payload":""
}'

If successful, the above command returns status code 201 and JSON structured response:

{
  "pipelineId": "pipeline id"
}

This endpoint creates a pipeline.

HTTP Request

POST https://api.northgravity.com/mgmt/pipeline

Request Body

Name	Type	Description	Optional
pipeline	object	Pipeline definition.	No
└─ name	string	Pipeline name (1–100 characters, cannot contain the following characters: `; , . / \ \	: _ % ( ) & ^ $ +` or whitespace ).
└─ groupName	string	Group name where the pipeline file is stored in the Datalake.	No
└─ tags	array	List of pipeline tags (cannot contain `; , . / \ \	: _ % ( ) & ^ $ +` or whitespace).
└─ summary	string	Pipeline description (max 256 characters).	Yes
batchConfig	object	Configuration of tasks for the pipeline.	Yes
└─ tasks	array	List of existing tasks to be executed in the pipeline. Task identifiers should be copied from existing tasks.	No
── └─ taskId	string	Node ID of the task. Must be unique within the pipeline.	No
── └─ prevTasks	array	List of previous task objects.	Yes
── ── └─ id	string	Id of previos task.	Yes
── └─ nextTasks	array	List of next task objects.	Yes
── ── └─ id	string	Id of next task.	Yes
── └─ taskGroup	string	Group name where the task is stored in the Datalake.	No
── └─ taskName	string	Name of the task.	No
── └─ taskVersion	number	Version of the task.	No
── └─ taskReadableName	string	Readable name of the task (1-32 characters).	No
── └─ taskOverrides	object	Container with task override values.	Yes
── ── └─ cpu	number	Number of CPU cores. Minimum: `1`. Default: `1`.	Yes
── ── └─ memory	number	Amount of RAM memory. Minimum: `4`. Default: `512`.	Yes
── ── └─ timeout	number	Task timeout in seconds.	Yes
── ── └─ params	object	Map of task parameters, containing values required to run the task.	Yes
── └─ arraySize	number	Size of the task array. If greater than `2`, tasks are executed as an array task.	Yes
── └─ sequential	boolean	If `true` and `arraySize` is greater than `2`, tasks are executed sequentially. Default: `false`.	Yes
── └─ isPaused	boolean	If `true` all tasks are paused. Default: `false`.	Yes
payload	String	Additional payload data passed to the pipeline, in JSON format as a string.	Yes

Example payload:

"{\"positions\":{\"exampleTaskId\":{\"x\":positionX,\"y\":positionY}},\"comments\":[],\"commentsVisible\":true}"

Update pipeline

curl -X PUT
  https://api.northgravity.com/mgmt/pipeline/examplePipelineId
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
    "pipeline":{
        "name":"Pipeline name",
        "groupName":"Name of the group",
        "tags":["tag1", "tag2"],
        "summary": "example summary of the pipeline",
    },
    "batchConfig": {
        "tasks": [
            {
                "taskId": "Task id",
                "taskName": "Task name",
                "taskReadableName": "Readable name",
                "taskGroup": "Group name, where task is kept in Datalake",
                "taskCategory": "Category where task is located",
                "taskVersion": "Task version e.g. `1.0.1`",
                "prevTasks": [
                    {
                        "id": "Task id"
                    }
                ],
                "nextTasks": [
                    {
                        "id": "Task id"
                    }
                ],
                "taskOverrides": {
                    "cpu":"1",
                    "memory":"4",
                    "timeout":"14400",
                    "params": {
                        "DATA_GROUP_NAME": "New group name",
                        "Example Param": "Example Value"
                    }
                },
                "arraySize": 1,
                "sequential": false
            }
        ]
    }
    ,
    "payload":""
}'

If successful, the above command returns status code 200 and JSON structured response:

{
  "pipelineId": "pipeline id"
}

This endpoint updates a pipeline. Pipeline version is not affected by changes to comments, tags or task positions(payload field).

HTTP Request

PUT https://api.northgravity.com/mgmt/pipeline/{pipelineId}

URL Parameters

Parameter	Description	Optional
pipelineId	pipeline id which you want to update	No

Request Body

Name	Type	Description	Optional
pipeline	object	Pipeline definition.	No
└─ name	string	Pipeline name (1–100 characters, cannot contain the following characters: `; , . / \ \	: _ % ( ) & ^ $ +` or whitespace ).
└─ groupName	string	Group name where the pipeline file is stored in the Datalake.	No
└─ tags	array	List of pipeline tags (cannot contain `; , . / \ \	: _ % ( ) & ^ $ +` or whitespace).
└─ summary	string	Pipeline description (max 256 characters).	Yes
batchConfig	object	Configuration of tasks for the pipeline.	Yes
└─ tasks	array	List of existing tasks to be executed in the pipeline. Task identifiers should be copied from existing tasks.	No
── └─ taskId	string	Node ID of the task. Must be unique within the pipeline.	No
── └─ prevTasks	array	List of previous task objects.	Yes
── ── └─ id	string	Id of previos task.	Yes
── └─ nextTasks	array	List of next task objects.	Yes
── ── └─ id	string	Id of next task.	Yes
── └─ taskGroup	string	Group name where the task is stored in the Datalake.	No
── └─ taskName	string	Name of the task.	No
── └─ taskVersion	number	Version of the task.	No
── └─ taskReadableName	string	Readable name of the task (1-32 characters).	No
── └─ taskOverrides	object	Container with task override values.	Yes
── ── └─ cpu	number	Number of CPU cores. Minimum: `1`. Default: `1`.	Yes
── ── └─ memory	number	Amount of RAM memory. Minimum: `4`. Default: `512`.	Yes
── ── └─ timeout	number	Task timeout in seconds.	Yes
── ── └─ params	object	Map of task parameters, containing values required to run the task.	Yes
── └─ arraySize	number	Size of the task array. If greater than `2`, tasks are executed as an array task.	Yes
── └─ sequential	boolean	If `true` and `arraySize` is greater than `2`, tasks are executed sequentially. Default: `false`.	Yes
── └─ isPaused	boolean	If `true` all tasks are paused. Default: `false`.	Yes
payload	String	Additional payload data passed to the pipeline, in JSON format as a string.	Yes

Get pipeline

This endpoint retrieves the configuration of a pipeline by its ID.

curl https://api.northgravity.com/mgmt/pipeline/examplePipelineId
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns status code 200 and JSON structured response:

{
  "pipeline": {
    "id": "unique-pipeline-uuid",
    "root": "unique-pipeline-root-uuid",
    "latest": true,
    "removed": false,
    "archived": false,
    "prevFireTime": "2026-01-14T17:00:08.932",
    "prevManualFireTime": "2026-01-16T16:44:10.374",
    "name": "example pipeline name",
    "version": 4,
    "lastChange": "2026-01-19T11:56:14.794",
    "lastChangeBy": "example user",
    "groupName": "example group",
    "tags": [
      "exampleTag1"
    ],
    "uiPayloadId": "example-ui-payload-uuid"
  },
  "batchConfig": {
    "tasks": [
      {
        "taskId": "example-task-id",
        "prevTasks": [],
        "nextTasks": [],
        "taskGroup": "Group name, where task is kept in Datalake",
        "taskName": "Exmaple task name",
        "taskVersion": "1.0.0",
        "taskReadableName": "Readable task name in UI",
        "taskOverrides": {
          "params": {
            "Input File": "{\"name\":\"exampleFile.csv\",\"groupName\":\"example group\"}",
            "Output Group": "example group",
            ...
          }
        },
        "arraySize": 1,
        "sequential": false,
        "isPaused": false
      }
    ]
  },
  "payload": "{\"positions\":{\"47f9df20-41f2-4aa2-afc5-ddb0cebea71b\":{\"x\":517,\"y\":254}},\"comments\":[{\"author\":\"example user\",\"id\":\"unique-id\",\"text\":\"comment\",\"position\":{\"x\":750,\"y\":148}}],\"commentsVisible\":true}",
  "taskDefinitions": [
    {
      "id": "unique-task-id",
      "name": "example-task-name",
      "readableName": "Example Readable name",
      "description": "Example description",
      "groupName": "Example group name",
      "version": "1.0.0",
      "arrivalTime": "2025-10-22T15:03:07.595",
      "imageUrl": "example image url of docker in docker repository : `123.dkr.ecr.us-east-1.amazon.com/example-task:1.0.0`",
      "privateCredentialsId": "",
      "markdownId": "example-markdown-id",
      "cpu": 1,
      "memory": 2048,
      "timeout": 900,
      "params": [
        {
          "name": "Input File",
          "description": "Load data from file to task",
          "type": "INPUT",
          "valueType": "DATALAKE_FILE",
          "dynamic": true,
          "optional": false,
          "withProvider": true,
          "additional": false,
          "isHidden": false,
          "expression": false
        },
        ...
      ],
      "active": true,
      "category": "Example category",
      "categoryReadableName": "Example category",
      "icon": "ExampleIcon",
      "source": "CORE",
      "execType": "LAMBDA_DOCKER",
      "root": "unique-task-root-uuid",
      "user": "exampleUser",
      "cpuArch": "",
      "latest": true
    }
  ],
  "isPipelineBroken": false,
  "missingTaskOutputList": []
}

This endpoint returns the pipeline.

HTTP Request

GET https://api.northgravity.com/mgmt/pipeline/{id}

URL Parameters

Parameter	Description	Optional
id	Unique pipeline id	No

Get pipeline by name, group and version

curl 
    https://api.northgravity.com/mgmt/pipeline/examplePipelineGroup/examplePipelineName/examplePipelineVersion
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns status code 200 and JSON structured response as in Get pipeline

This endpoint returns the pipeline with specific group, name and version.

HTTP Request

GET https://api.northgravity.com/mgmt/pipeline/{groupName}/{pipelineName}/{version}

URL Parameters

Parameter	Description	Optional
groupName	Name of the group where pipeline is stored.	No
pipelineName	Name of the pipeline to retrieve.	No
version	Version of the pipeline to retrieve e.g. `5` or `latest` to get the latest version.	No

Search pipelines

This endpoint searches for pipelines and supports filtering based on one or more query parameters (such as name, group, or other attributes).

curl https://api.northgravity.com/mgmt/pipeline?query=<query>&from=<from>&size=<size>&latest=<latest>
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns status code 200 and JSON structured response:

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      "id": "unique-pipeline-uuid",
      "root": "unique-pipeline-root-uuid",
      "latest": true,
      "removed": false,
      "archived": false,
      "prevManualFireTime": "2025-06-05T14:22:10.336",
      "name": "example pipeline name",
      "version": 1,
      "lastChange": "2025-06-12T10:20:37.092",
      "lastChangeBy": "example user",
      "groupName": "example group",
      "uiPayloadId": "example-ui-payload-uuid"
    },
    ...
  ]
}

HTTP Request

GET https://api.northgravity.com/mgmt/pipeline?query=<query>&size=<size>&from=<from>&latest=<latest>

URL Parameters

Parameter	Description	Optional
query	Query to search pipelines.	No
size	The maximum size of returned hits list. Max size is `1000`. Default size is `100`.	Yes
from	The index of the first hit. It allows to do paging easily. Default value is `0`.	Yes
latest	If set to false, search will return also previous versions of the pipelines. Default: `true`.	Yes
sortOrder	Field name to sortBy. Examples: `name`, `version`, `groupMame`.	Yes
sortBy	If set to false, search will return also previous versions of the pipelines. Default: `true`.	Yes

Get pipeline versions

This endpoint returns previous versions along with the latest version of the pipeline.

curl 
    https://api.northgravity.com/mgmt/pipeline/versions/examplePipelineId
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns status code 200 and JSON structured response:

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      "id": "unique-pipeline-uuid",
      "root": "unique-pipeline-root-uuid",
      "latest": true,
      "removed": false,
      "archived": false,
      "prevFireTime": "2026-01-14T17:00:08.932",
      "prevManualFireTime": "2026-01-16T16:44:10.374",
      "name": "example pipeline name",
      "version": 2,
      "lastChange": "2026-01-19T12:22:13.459",
      "lastChangeBy": "example user",
      "groupName": "example group",
      "uiPayloadId": "example-ui-payload-uuid"
    },
    {
      "id": "unique-pipeline-uuid",
      "root": "unique-pipeline-root-uuid",
      "latest": false,
      "removed": false,
      "archived": false,
      "prevFireTime": "2026-01-14T17:00:08.932",
      "prevManualFireTime": "2026-01-16T15:14:15.915",
      "name": "example pipeline name",
      "version": 1,
      "lastChange": "2026-01-16T15:14:12.532",
      "lastChangeBy": "example user",
      "groupName": "example group",
      "tags": [
        "exampleTag1"
      ],
      "uiPayloadId": "example-ui-payload-uuid"
    }
  ]
}

HTTP Request

GET https://api.northgravity.com/mgmt/pipeline/{id}

URL Parameters

Parameter	Description	Optional
id	Unique pipeline id	No

Get pipeline versions

This endpoint returns historical versions of pipeline

curl 
    https://api.northgravity.com/mgmt/pipeline/versions/examplePipelineGroup/examplePipelineName
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns status code 200 and JSON structured response:

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      "id": "unique-pipeline-uuid",
      "root": "unique-pipeline-root-uuid",
      "latest": true,
      "removed": false,
      "archived": false,
      "prevFireTime": "2026-01-14T17:00:08.932",
      "prevManualFireTime": "2026-01-16T16:44:10.374",
      "name": "example pipeline name",
      "version": 2,
      "lastChange": "2026-01-19T12:22:13.459",
      "lastChangeBy": "example user",
      "groupName": "example group",
      "uiPayloadId": "example-ui-payload-uuid"
    },
    {
      "id": "unique-pipeline-uuid",
      "root": "unique-pipeline-root-uuid",
      "latest": false,
      "removed": false,
      "archived": false,
      "prevFireTime": "2026-01-14T17:00:08.932",
      "prevManualFireTime": "2026-01-16T15:14:15.915",
      "name": "example pipeline name",
      "version": 1,
      "lastChange": "2026-01-16T15:14:12.532",
      "lastChangeBy": "example user",
      "groupName": "example group",
      "tags": [
        "exampleTag1"
      ],
      "uiPayloadId": "example-ui-payload-uuid"
    }
  ]
}

HTTP Request

GET https://api.northgravity.com/mgmt/pipeline/{groupName}/{pipelineName}

URL Parameters

Parameter	Description	Optional
groupName	Name of the group where pipeline is stored.	No
pipelineName	Name of the pipeline to retrieve.	No

Retreive pipline params

Retrieve all values for a pipeline and job or retrieve a single value for the given key for the given pipelineId and jobId

> Single value

curl https://api.northgravity.com/mgmt/store/{pipelineId}/{keyName}
  -H "Authorization: Bearer yourNgToken" 
  -H "X-KH-JOB-ID={jobId}"

> Retrieve all values

curl https://api.northgravity.com/mgmt/store/{pipelineId}
  -H "Authorization: Bearer yourNgToken" 
  -H "X-KH-JOB-ID={jobId}"

If successful, the above commands returns a status code of 200 and a JSON-formatted response. If no values are found, the response will be an empty list for all - [] values and null for single value.

JSON for single value:

{
  "dataStorageId": 70,
  "pipelineId": "example-pipeline-id-1",
  "jobId": "unique-job-id-1",
  "index": -1,
  "key": "RESULTS_FILE_ID",
  "value": "example-value-1"
}

JSON for all values:

[
  {
    "dataStorageId": 70,
    "pipelineId": "example-pipeline-id-1",
    "jobId": "unique-job-id-1",
    "index": -1,
    "key": "RESULTS_FILE_ID",
    "value": "example-value-2"
  },
  {
    "dataStorageId": 71,
    "pipelineId": "example-pipeline-id2",
    "jobId": "unique-job-id-2",
    "index": -1,
    "key": "RESULTS_FILE_ID_2",
    "value": "example-value-2"
  }
]

HTTP Request

Retrieve single value

GET https://api.northgravity.com/mgmt/store/{pipelineId}/{keyName}

Retrieve all values

GET https://api.northgravity.com/mgmt/store/{pipelineId}

HTTP Request Headers

Header	Description	Optional
X-KH-JOB-ID	Unique jobId of the pipeline.	No

URL Parameters

Parameter	Description	Optional
pipelineId	Unique pipeline id.	No
keyName	The name of the key are you getting the value for.	Yes

Delete pipeline

This endpoint deletes a particular pipeline with all versions.

curl DELETE -X
    https://api.northgravity.com/mgmt/objective/examplePipelineId
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns status code 200.

HTTP Request

DELETE https://api.northgravity.com/mgmt/objective/{pipelineId}

URL Parameters

Parameter	Description	Optional
pipelineId	Unique id of the pipeline	No

Execute pipeline

This endpoint executes a particular pipeline.

curl POST -X
    https://api.northgravity.com/mgmt/pipeline/execute/examplePipelineId
    -H "Authorization: Bearer yourNgToken"
    -H "Content-Type: application/json" 
    -d '{
          "details": {
              "PIPELINE_ID": "examplePipelineId"
          }
    }'

If successful, the above command returns status code 200 and JSON structured response:

{
  "jobId": "{jobId}"
}

HTTP Request

POST https://api.northgravity.com/mgmt/pipeline/execute/{pipelineId}

URL Parameters

Parameter	Description	Optional
pipelineId	Unique id of the pipeline which you want to execute	No

Request Body

Name	Type	Description	Optional
details	object	Key-value pairs. Example: "`"details": {"PIPELINE_ID": "examplePipelineId"}`"	Yes

Schedule pipeline

This endpoint creates and updates pipeline triggers.

curl PUT -X
    https://api.northgravity.com/mgmt/pipeline/trigger/examplePipelineId
    -H "Authorization: Bearer yourNgToken"
    -H "Content-Type: application/json"
    -d '{
            "triggers": [
                {
                    "type": "cron | startAt | now",
                    "cron": "* * * * * ? *",
                    "startAt": "2019-06-04T14:20:39.230",
                    "timeZone": "UTC",
                    "details": 
                    {
                      "PIPELINE_ID": "examplePipelineId"
                    }
                }
        ]
    }'

If successful, the above command returns status code 200.

HTTP Request

PUT https://api.northgravity.com/mgmt/pipeline/trigger/{pipelineId}

URL Parameters

Parameter	Description	Optional
pipelineId	Unique id of the pipeline which you want to schedule	No

Request Body

Name	Type	Description	Optional
triggers	array	List of triggers to schedule pipeline.	No
└─ frame	string	Unique name of trigger. Used when updating exisitng trigger.	Yes
└─ type	string	Options: [ cron / startAt ].	No
└─ cron	string	Cron expression specifying when the task runs. Example: `0 0 17 ? * MON-FRI` runs Monday–Friday at 17:00 UTC.	No(if `type` is `cron`)
└─ startAt	string	Date when tigger is started in format `yyyy-MM-dd'T'HH:mm:ss.SSS`.	No(if `type` is `startAt`)
└─ timeZone	string	Valid time zone name. Full list: Oracle Time Zone List. Default: `UTC`	Yes
└─ details	object	Key-value pairs. Example: "`"details": {"PIPELINE_ID": "examplePipelineId"}`"	Yes

Get pipeline schedules

This endpoint gets pipeline triggers by using pipeline ID.

curl https://api.northgravity.com/mgmt/pipeline/trigger/{pipelineId}?from=<from>&size=<size>
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns status code 200 and JSON structured response:

{
  "from": 0,
  "totalSize": 1,
  "items": [
    {
      "type": "cron",
      "frame": "frameName-example-frame-uuid",
      "cron": "0 0 8 ? * * *",
      "startAt": "1970-01-01T00:00:00.000",
      "timeZone": "UTC",
      "details": {
        "PIPELINE_ID": "example-pipeline-id"
      },
      "nextFireTime": "Jan 21, 2026, 8:00:00 AM",
      "prevFireTime": "Jan 20, 2026, 8:00:00 AM",
      "state": "NORMAL | PAUSED"
    }
  ]
}

HTTP Request

GET https://api.northgravity.com/mgmt/pipeline/trigger/{pipelineId}?from=<from>&size=<size>

URL Parameters

Parameter	Description	Optional
pipelineId	Unique id of the pipeline.	No
from	Index where list starts, used to load data in chunks. Default value is `0`.	Yes
size	Number of records to return. Max size is 1000. Default size is `100`.	Yes

Terminate pipeline

This endpoint terminates running pipeline.

curl DELETE -X
    https://api.northgravity.com/mgmt/pipeline/execute/{pipelineId}
  -H "Authorization: Bearer yourNgToken" 
  -H "X-KH-JOB-ID={jobId}"

If successful, the above command returns status code 200.

HTTP Request

DELETE https://api.northgravity.com/mgmt/pipeline/execute/{pipelineId}

HTTP Request Headers

Header	Description	Optional
X-KH-JOB-ID	Unique jobId of the pipeline	No

URL Parameters

Parameter	Description	Optional
pipelineId	Unique pipeline id, which you want to terminate	No

This endpoint shares a particular pipeline with given users and sends email with custom text.

curl POST -X
    https://api.northgravity.com/mgmt/pipeline/share/examplePipelineId
    -H "Authorization: Bearer yourNgToken"
    -H "Content-Type: application/json"
    -d '{
        "emails": ["exampleEmail1@domain.com", "exampleEmail2@domain.com"]],
        "url": "http://dashboard.northgravity.com/Science/Creator/groupName/pipelineName/version or latest",
        "message": "Your custom, optional message",
        "access": "R"
    }'

If successful, the above command returns status code 200.

HTTP Request

POST https://api.northgravity.com/mgmt/pipeline/share/{pipelineId}

URL Parameters

Parameter	Description	Optional
pipelineId	Unique id of the pipeline which you want to share	No

Request Body

Name	Type	Description	Optional
email	array	List of emails(only users registered on platform).	No
url	string	Pipeline URL.	No
message	string	Message which is included in email.	Yes
access	string	Specifies the level of access granted to another user.	No

Export pipeline

This endpoint allows user to generate input necessary for creating new pipeline on another environment. In the process all environment exclusive task parameters as well as confidential data like passwords are removed and have to be set once again.

curl https://api.northgravity.com/mgmt/pipeline/export/examplePipelineId
  -H "Authorization: Bearer yourNgToken"

The above command returns a valid pipeline configuration input, which can be used as the payload to create pipelines. See Create Pipeline section for more details.

HTTP Request

GET https://api.northgravity.com/mgmt/pipeline/export/{pipelineId}

URL Parameters

Parameter	Description
pipelineId	Unique id of the pipeline which you want to export.

HTTP Response

{
  "pipeline": {
    "name": "Pipeline name",
    "version": 1
  },
  "batchConfig": {
    "tasks": [
      {
        "taskId": "example-task-id",
        "prevTasks": [],
        "nextTasks": [],
        "taskGroup": "Group name, where task is kept in Datalake",
        "taskName": "Exmaple task name",
        "taskVersion": "1.0.0",
        "taskReadableName": "Readable task name in UI",
        "taskOverrides": {
          "params": {
            "Input File": "{\"name\":\"exampleFile.csv\",\"groupName\":\"example group\"}",
            "Output Group": "example group",
            ...
          }
        },
        "arraySize": 1,
        "sequential": false,
        "isPaused": false
      }
    ]
  },
  "payload": ""
}

Validate pipeline

This endpoint allows user to check if create pipeline input is valid without saving it in the database. Main use case for it is to check if task versions used for a pipeline are on the environment.

curl -X POST
  https://api.northgravity.com/mgmt/pipeline/validate
  -H "Authorization: Bearer yourNgToken"
  -H "Content-Type: application/json" 
  -d '{
    "pipeline":{
        "name":"Pipeline name",
        "groupName":"Name of the group",
        "tags":["tag1", "tag2"],
        "summary": "example summary of the pipeline",
    },
    "batchConfig": {
        "tasks": [
            {
                "taskId": "Task id",
                "taskName": "Task name",
                "taskReadableName": "Readable name",
                "taskGroup": "Group name, where task is kept in Datalake",
                "taskCategory": "Category where task is located",
                "taskVersion": "Task version e.g. `1.0.1`",
                "prevTasks": [
                    {
                        "id": "Task id"
                    }
                ],
                "nextTasks": [
                    {
                        "id": "Task id"
                    }
                ],
                "taskOverrides": {
                    "cpu":"1",
                    "memory":"4",
                    "timeout":"14400",
                    "params": {
                        "DATA_GROUP_NAME": "New group name",
                        "Example Param": "Example Value"
                    }
                },
                "arraySize": 1,
                "sequential": false
            }
        ]
    }
    ,
    "payload":""
}'

If successful, the above request returns status code 200 with task definitions used in pipeline. -- and would create a pipeline.<---?

{
  "taskDefinitions": [
    {
      "id": "Id of task definition",
      "name": "Name of task definition",
      "readableName": "Readable name of task definition",
      "description": "Description of the task",
      "groupName": "Group name",
      "version": "Task version",
      "type": "Task type",
      "imageUrl": "Url of the docker image in docker repository",
      "markdownId": "Md file id",
      "cpu": 1,
      "memory": 512,
      "timeout": 14400,
      "params": [],
      "active": true,
      "category": "Task category",
      "icon": "Task icon",
      "source": "source of the task"
    }
  ]
}

If validation not successful request returns code 400 and a json validation response:

{
  "type": "VALIDATION",
  "validationErrors": [
    {
      "field": "batchConfig.tasks",
      "message": "Cannot find tasks in version: {name: task-pv-symbol-delete, group: System Tasks, version: wrong-version}. Cannot find tasks on environment: {name: task-pv-symbol-delete, group: Wrong-group}, {name: wrong-name, group: System Tasks}. ",
      "payload": [
        {
          "incorrectVersions": [
            "{name: task-pv-symbol-delete, group: System Tasks, version: wrong-version}"
          ]
        },
        {
          "missingTasks": [
            "{name: task-pv-symbol-delete, group: Wrong-group}",
            "{name: wrong-name, group: System Tasks}"
          ]
        }
      ]
    }
  ]
}

HTTP Request

POST https://api.northgravity.com/mgmt/pipeline/validate?latest=<latest>

Parameter	Description	Optional
latest	If `true`, it checks whether the tasks in the configuration are using the latest version. Default: `false`	Yes

Request Body

Name	Type	Description	Optional
batchConfig	object	Configuration of tasks for the pipeline.	Yes
└─ tasks	array	List of existing tasks to be executed in the pipeline. Task identifiers should be copied from existing tasks.	No
── └─ taskId	string	Node ID of the task. Must be unique within the pipeline.	No
── └─ prevTasks	array	List of previous task objects.	Yes
── ── └─ id	string	Id of previos task.	Yes
── └─ nextTasks	array	List of next task objects.	Yes
── ── └─ id	string	Id of next task.	Yes
── └─ taskGroup	string	Group name where the task is stored in the Datalake.	No
── └─ taskName	string	Name of the task.	No
── └─ taskVersion	number	Version of the task.	No
── └─ taskReadableName	string	Readable name of the task (1-32 characters).	No
── └─ taskOverrides	object	Container with task override values.	Yes
── ── └─ cpu	number	Number of CPU cores. Minimum: `1`. Default: `1`.	Yes
── ── └─ memory	number	Amount of RAM memory. Minimum: `4`. Default: `512`.	Yes
── ── └─ timeout	number	Task timeout in seconds.	Yes
── ── └─ params	object	Map of task parameters, containing values required to run the task.	Yes
── └─ arraySize	number	Size of the task array. If greater than `2`, tasks are executed as an array task.	Yes
── └─ sequential	boolean	If `true` and `arraySize` is greater than `2`, tasks are executed sequentially. Default: `false`.	Yes
── └─ isPaused	boolean	If `true` all tasks are paused. Default: `false`.	Yes
payload	String	Additional payload data passed to the pipeline, in JSON format as a string.	Yes

GET GROUP USAGE BY PIPELINES

This endpoint retrieves information about pipelines that use the specified group.

curl https://api.dev.northgravity.com/mgmt/group/usage/exampleGroup
  -H "Authorization: Bearer yourNgToken"

If successful, the above command returns status code 200 and JSON structured response:

[
  {
    "name": "Example Pipeline",
    "groupName": "exampleGroup",
    "lastChange": "2025-07-07T16:36:43.352",
    "tasks": []
  },
  {
    "name": "Example Pipeline 2",
    "groupName": "exampleGroup",
    "lastChange": "2026-01-16T14:00:43.099",
    "tasks": [
      {
        "readableName": "Example task",
        "name": "exmaple-task",
        "groupName": "Example group with tasks",
        "params": [
          {
            "name": "Example parameter",
            "value": "Example value",
            "valueType": "STRING"
          }
        ]
      }
    ]
  }
]

HTTP Request

GET https://api.northgravity.com/mgmt/group/usage/{groupName}

URL Parameters

Parameter	Description	Optional
groupName	Name of group where pipeline was created	No

Normalized CSV file (NCSV)

Overview

The NCSV file is simply a CSV file, that will be interpreted with the following rules

The file will be comma separated.
Rows starting with '#' are considered comments and will be ignored.
The first non comment row will be used as the header.
All column names in the header must be unique.
Only one "Date" column is allowed. i.e. one column labeled in the header with "Date".

The date should also follow the ISO_8601 standards

All columns to the left of the "Date" column will be considered as part of the unique identifier for that row and record
All columns to the right of the "Date" column will value columns. The default type (column without a type indicator) is "double" i.e. a double-precision floating point number.
If there are no values in a file, "Date" column should not be there. For the use case, see the "Insert NCSV with no values" paragraph

NCSV format

Example

The following is a simple example file. The file has two unique identifiers MySymbol01 and MySymbol02, two doubles value columns val01 and val02 and a Description column


#Sample comment line
MySymbol01	MySymbol02	Date	val01	val02	Description(MD-S)
ABC.01D	XYZ.01E	2019-05-26T00:00:00Z	22	21	description1
ABC.02D	XYZ.02E	2019-05-27T00:00:00Z	1	21	description1
ABC.03D	XYZ.03E	2019-05-28T00:00:00Z	2	21	description2
ABC.04D	XYZ.04E	2019-05-29T00:00:00Z	78	21	description2
# this row will be ignored
ABC.05D	XYZ.05E	2019-05-30T00:00:00Z		21	description2
ABC.05D	XYZ.06E	2019-06-01T00:00:00Z	1	21	description3
ABC.06D	XYZ.07E	2019-05-22T00:00:00Z	5	21	description3

Time zones

All dates are stored in milliseconds to take one common chronology. However, they can be inserted in various time zones or offsets by specifying it. You can specify timezone by putting this next to date column name or offset by putting this offset to the date. If you do not specify any timezone or offset we will treat this as a UTC. You never should use both.

Sample of timezone definition:

MySymbol	Date(Europe/Warsaw)	Val1(I)	...
ABC.01.D	2019-05-26T12:00:00	1	...
ABC.01.D	2019-05-23T12:00:00	2	...
ABC.01.D	2019-05-22T12:00:00	3	...

Sample of offset definition:

MySymbol	Date	Val1(I)	...
ABC.01.D	2019-05-26T12:00:00+02:00	1	...
ABC.01.D	2019-05-23T12:00:00+02:00	2	...
ABC.01.D	2019-05-22T12:00:00+02:00	3	...

In timeseries we are able to display data in a given time zone. If you do not select timezone in which you want to get data, then we will use defined default timezone. You can define this default timezone by adding metadata column with name 'TimeZone'. If you do not define that column we will generate this and as a timezone we will use timezone from your date column.

In example, if you use that input:

MySymbol	Date(Europe/Warsaw)	Val1(I)	TimeZone(MD-S)
ABC.01.D	2019-05-26T12:00:00	1	Europe/London
ABC.01.D	2019-05-23T12:00:00	2	Europe/London
ABC.01.D	2019-05-22T12:00:00	3	Europe/London

We will load date in Europe/Warsaw timezone, but if you fetch data in default timezone you will receive Europe/London time, which is in this case 11:00.

Value Types & Metadata

Supported types

We support two types of data:

Values: are stored in Time Series
Available types of values:
- (DB) - Double (default)
- (S) - String (max size 255 chars)
- (LS) - Long String (max size 2,048 chars)
- (I) - Integer
- (D) - ISO-8601 Date
- (DT) - ISO-8601 Date Time
Metadata
Available types of metadata:
- (MD-DB) - Double
- (MD-S) - String (max size 255 chars)
- (MD-I) - Integer
- (MD-D) - ISO-8601 Date
- (MD-D) - ISO-8601 Date Time

If a Description(MD-S) column is provided, it will be displayed in timeseries while searching

When a column is of Date, Value Date or Metadata Date type, the date can be initially inserted in various formats. Steps on how to do it:

Insert dates into the column
On the right-hand side there are drop-down lists that enable to specify the timezone and current date format of the date that you just inserted. As stated before, we need to store the NCSV dates in UTC timezone. To adhere to it, there is a 'Format' button below the drop-downs to do the conversion to UTC.
- Select columns to convert.
- Select the timezone of the inserted dates.
- Select current date format. Pay attention here. If you first provide the date with time, and you choose here not to consider it, it will be cut off.

Examples:

Date: 2021-07-07T06:57:18
Selected timezone: Europe/Warsaw
Current date format: yyyy-MM-dd'T'HH:mm:ss
After formatting: 2021-07-07T04:57:18 - simple conversion from Europe/Warsaw timezone to UTC
Date: 2021-07-07T06:57:18
Selected timezone: Europe/Warsaw
Current date format: yyyy-MM-dd
After formatting: 2021-07-06T22:00:00 - before conversion, the time is cut off, and the date is perceived as 2021-07-07 (T00:00:00 as default). Formatting (timezone conversion) goes back in time to 2021-07-06T22:00:00 as there is 2 hours difference.

We can assume there is a one to one (1:1) relationship between the metadata column and the unique identifier. And because of this there is no need to repeat the metadata column on each record row. Last non blank metadata record would be considered the most recent value.

Example

MySymbol	Date	Val1(I)	Val2(S)	Val3	Description(MD-S)	Year of production(MD-I)	Units(MD-S)
ABC.01.D	2019-05-26T00:00:00Z	1	BA	22	Description1	1999	ft
ABC.01.D	2019-05-23T00:00:00Z	3	CD	21	Description2	1998	ft
ABC.01.D	2019-05-22T00:00:00Z	4	FD	11	Description3	1996	ft

Interpretation

Unique identifier of every row is MySymbol & Date
Val1 column is Integer type value, exist in timeseries
Val2 column is String type value, exist in timeseries
Val3 column is Double type by default, exist in timeseries
Description column is String Metadata, it will exist in timeseries while searching
Year of production column is Integer Metadata, it will exist in timeseries while searching
Units column is also String Metadata, it will exist in timeseries while searching

Timeseries result

When we make a search in timeseries for MySymbol = ABC.01.D and select all values we will get following result:

Time	MySymbol: ABC.01.D (val3)	MySymbol: ABC.01.D (Val1)	MySymbol: ABC.01.D (Val2)
2019-05-26 00:00:00	22	1	BA
2019-05-23 00:00:00	21	3	CD
2019-05-22 00:00:00	11	4	FD

NCSV Validation

NCSV Validator

After uploading NCSV file to datalake the data is being validated by NCSV Validator. Validator goes through each cell in NCSV to check if data is in correct format. In case Validator finds incorrect values it returns error status with message indicating the line and column where erroneous value was found. NCSV data will not be loaded to timeseries until all errors are fixed and the file is reuploaded (the process is the same for Delete NCSV).

Correct data for each type:

(DB) - Double type values shall use dot as a decimal separator and no other special characters.
Correct double type values: 1; 0; -1; 100; 123.4; 0.0
Incorrect double type values: 1,000.0; 2,000; 9,999,999.99; 9 999 999.99
(S) - String type values should follow RFC4180 standard. Each String value may or may not be enclosed in double quotes. If a value contains comma, line break or double quote it should be enclosed in double quotes. A double quote appearing inside a field it must be escaped by preceding it with another double quote.
Correct integer type values: 1; 0; -1; 100; 123
Incorrect integer type values: 1.0; 1,000; 2.5; 2,000; 1 000 000
(I) - Integer type values shall not use any characters other than numbers.
Correct string type values: a; something; "word"; "Austin, Texas"; Value 1; "a""b""c"
Incorrect string type values: ** a"; "something""; Austin, Texas; "a"b"c"**
(D) - All dates should follow ISO-8601 format. Other formats might cause error or incorrect data being loaded into ts.
Correct date type values: 1970-01-01T00:00:00; 1970-01-01; 2023-05-11T15:34:34
Incorrect date type values: 1970-01-01 00:00:00; 1970/01/01; 12-31-1999; 1683805451

Special cases

Insert NCSV with empty data

We can insert NCSV file with empty cells on the right from Date, it will be loaded correctly

Example of correct NCSV

MySymbol	Date	Val1(I)	Val2(S)	Val3	Description(MD-S)	Year of production(MD-I)	Units(MD-S)
ABC.01.D	2019-05-26T00:00:00Z		BA	22		1999	ft
ABC.01.D	2019-05-23T00:00:00Z	3		21	Description2	1998	ft
ABC.01.D	2019-05-22T00:00:00Z	4	FD		Description3	1996	ft

Timeseries result When we make a search in timeseries for MySymbol = ABC.01.D and select all values we will get following result:

Time	MySymbol: ABC.01.D (val1)	MySymbol: ABC.01.D (Val2)	MySymbol: ABC.01.D (Val3)
2019-05-26 00:00:00		BA	22
2019-05-23 00:00:00	3		21
2019-05-22 00:00:00	4	FD

Insert NCSV with this same key(Update)

Let's say we have already loaded following data:

MySymbol	Date	Val1(I)	Val2(S)	Val3	Description(MD-S)	Year of production(MD-I)	Units(MD-S)
ABC.01.D	2019-05-26T00:00:00Z	1	BA	22	Description1	1999	ft
ABC.01.D	2019-05-23T00:00:00Z	3	CD	21	Description2	1998	ft
ABC.01.D	2019-05-22T00:00:00Z	4	FD	11	Description3	1996	ft

and we are loading second file with following data:

MySymbol	Date	Val1(I)	Val2(S)	Val3	Description(MD-S)	Year of production(MD-I)	Units(MD-S)
ABC.01.D	2019-05-26T00:00:00Z			100	New Description	1999
ABC.01.D	2019-05-23T00:00:00Z	50	ABC	120	Description2	2010	ft
ABC.01.D	2019-05-22T00:00:00Z	4		11	Description3	1996	ft

Interpretation

All rows will be completely updated;

Timeseries result

When we make a search in timeseries for MySymbol = ABC.01.D and select all values we will get following result:

Time	MySymbol: ABC.01.D (val1)	MySymbol: ABC.01.D (Val2)	MySymbol: ABC.01.D (Val3)
2019-05-26 00:00:00			100
2019-05-23 00:00:00	50	ABC	120
2019-05-22 00:00:00	4		11

Insert NCSV with this same key and different number of columns(Update)

Let's say we have already loaded following data:

MySymbol	Date	Val1(I)	Val2(S)	Val3	Description(MD-S)	Year of production(MD-I)	Units(MD-S)
ABC.01.D	2019-05-26T00:00:00Z	1	BA	22	Description1	1999	ft
ABC.01.D	2019-05-23T00:00:00Z	3	CD	21	Description2	1998	ft
ABC.01.D	2019-05-22T00:00:00Z	4	FD	11	Description3	1996	ft

and we are loading second file with following data:

MySymbol	Date	Val2(S)	Val3	Description(MD-S)	Year of production(MD-I)	Units(MD-S)
ABC.01.D	2019-05-26T00:00:00Z		100	New Description	1999
ABC.01.D	2019-05-23T00:00:00Z	ABC	120	Description2	2010	ft
ABC.01.D	2019-05-22T00:00:00Z		11	Description3	1996	ft

Interpretation

The data from the new file overrides the previous one in any case.

Timeseries result

When we make a search in timeseries for MySymbol = ABC.01.D and select all values we will get following result:

Time	MySymbol: ABC.01.D (Val2)	MySymbol: ABC.01.D (Val3)
2019-05-26 00:00:00		100
2019-05-23 00:00:00	ABC	120
2019-05-22 00:00:00		11

Insert NCSV with this same key and different number of columns(Partial Update)

It is also possible to make partial updates on timeseries data. To make a partial update we need to set the PARTIAL_UPDATE flag to true in the POST endpoint payload to upload a file.

Example:

"fields":[{"name":"PARTIAL_UPDATE","value":"true"},{"name":"AVOID_DUPLICATES","value":"false"},{"name":"SKIP_METADATA","value":"false"}]

From the UI perspective, to make a partial update we need to check the respective checkbox named 'Partial Update' after choosing a file to upload.

Let's say we have already loaded the following data:

MySymbol	Date	Val1(I)	Val2(S)	Val3	Description(MD-S)	Year of production(MD-I)	Units(MD-S)
ABC.01.D	2019-05-26T00:00:00Z	1	BA	22	Description1	1999	ft
ABC.01.D	2019-05-23T00:00:00Z	3	CD	21	Description2	1998	ft
ABC.01.D	2019-05-22T00:00:00Z	4	FD	11	Description3	1996	ft

and we are loading a second file with the following data:

MySymbol	Date	Val2(S)	Val3	Description(MD-S)	Year of production(MD-I)	Units(MD-S)
ABC.01.D	2019-05-26T00:00:00Z		100	New Description	1999
ABC.01.D	2019-05-23T00:00:00Z	ABC	120	Description2	2010	ft
ABC.01.D	2019-05-22T00:00:00Z		11	Description3	1996	ft

Interpretation If some fields in a new column are empty, the update outcome is fields will be filled with empty values. The difference between the full update presented before and this one is when a column that was filled before is empty in the new file. Full update ignores the column that was wiped out (it is removed since then), on the other hand the partial update retains the data from the old column.

Timeseries result When we make a search in timeseries for MySymbol = ABC.01.D and select all values we will get following result:

Time	MySymbol: ABC.01.D (val1)	MySymbol: ABC.01.D (Val2)	MySymbol: ABC.01.D (Val3)
2019-05-26 00:00:00	1		100
2019-05-23 00:00:00	3	ABC	120
2019-05-22 00:00:00	4		11

Insert NCSV with no values

We can insert an NCSV file with no values, just with symbols and metadata columns. This generates symbols with no values. By default, they can be searched for with use of the symbol search endpoint. However, if a client doesn't want to see such symbols, it can be achieved as well by setting the withValuesOnly query parameter to true. Additionally, pay attention that there is no Date property in this case.

Example of such NCSV:

Symbol1	Symbol2	Symbol3	Symbol4	Currency(MD-S)	Description(MD-S)
S1	S2	S3	S4	CUR1	Desc1
S11	S22	S33	S44	CUR2	Desc2

Examples

Python SDK

This document describes the North Gravity Python SDK which enables external users to use the NG platform tools within their python scripts.

The Python SDK can be used within:

a single python script that is ran thanks to the Python Runner task within a pipeline in the NG application
a single Jupyter Notebook that is ran thanks to the Jupyter Runner task within a pipeline in the NG application
an ensemble of python scripts that are part of a container, for a Task created by the user, used in a pipeline in the NG application

Note that the SDK does not cover everything from API documentation but rather commonly used features.

The scope of the SDK:

Datalake Handler - downloading / uploading / reading files from the data lake
Status Handler - sending statuses about the task run
Task Handler - enables communication between tasks within a pipeline and reading/writing parameters
Time Series Handler - retrieves data directly from the time series database

How to install and set the package:

pip3 install northgravity==0.1.3

As the library is available from pip, it can be installed as a specific version within a Python Task from within requirements.txt just by adding:

northgravity==0.1.3

The package relies on the requests library so, in the project, the user must install this library in the requirements.txt file.

pip3 install requests==2.25.1

Environment Variables

The package uses information from the environment variables. They are automatically provided when running a script within a pipeline (as a Task or within the Python/Jupyter Runners). If running locally the script, users must set them in the project to be able to run the project locally.

Mandatory environment variables to set:

LOGIN → login received from NG
PASSWORD → password to log in. Credentials are used to generate the token so that each request is authenticated.
NG_API_ENDPOINT → the URL to the NG platform API (by default, the url is set to https://api.northgravity.com)

This allows to pass the authentication process and directs users' requests to the NG environment API.

Other variables may be useful when creating the tasks within the platform:

NG_STATUS_GROUP_NAME → the group on the data lake where the pipeline is located, and is used to display the statuses
JOBID → any value; when the pipeline is executed, this value is set by the NG platform
PIPELINE_ID → any value; when the pipeline is created, this value is set by the NG platform

northgravity.Authenticator.Authenticator

get_token()

import northgravity as ng
ah = ng.Authenticator()
ah.get_token()

Returns a dictionary with the Authorization header

Returns

dict with the Authorization header

northgravity.DatalakeHandler.DatalakeHandler

download_by_id(file_id, dest_file_name=None, save=False, unzip=False)

import northgravity as ng
dh = ng.DatalakeHandler()
dh.download_by_id(file_id='f4b5c6d7-e8f9-0a1b-2c3d-4e5f6g7h8i9j', dest_file_name='sample_csv.csv', save=True, unzip=True)

Download the file according to its file_id from the datalake.

If save == True, it saved the file locally to the path provided in dest_file_name, otherwise with the original name in the root folder.

If save == False, it returns a io.BytesIO object (that can be read for example as csv by pandas).

Parameters

file_id – hash ID of the file on the dalake
dest_file_name – file name as saved on the hard disk drive. Default is None (meaning the original name of the file)
save – if True, saves the file locally with dest_file_name, otherwise return a BytesIO object
unzip – if True, unzip the file (if saved as .tar or .zip on the lake) after saving it locally

Returns

none if file is saved locally, io.BytesIO object otherwise

download_by_name(file_name, group_name, file_type=None, dest_file_name=None, save=False, unzip=False)

import northgravity as ng
dh = ng.DatalakeHandler()
dh.download_by_name(file_name='sample_csv.csv', group_name='my_group', file_type='SOURCE', dest_file_name='sample_csv.csv', save=True, unzip=True)

Download a file from the data lake given its name & group. It returns by default the most recent occurency of the file.

If group is None, it returns the file according to its name only, the most recent one from any group. If file_type is SOURCE by default

If save == True, it saved the file locally to the path provided in dest_file_name, otherwise with the original name in the root folder. If save == False, it returns a io.BytesIO object (that can be read for example as csv by pandas).

Parameters

file_name – the name of file to download
group_name – the name of the datalake group. if None, it takes the file from any group
file_type – file type of the file on the DataLake - SOURCE, NCSV, GDP, etc. Default is SOURCE
dest_file_name – file name as saved on the hard disk drive. Default is None (meaning the original name of the file)
save – if True, saves the file locally with dest_file_name, otherwise return a BytesIO object
unzip – if True, unzip the file (if saved as .tar or .zip on the lake) after saving it locally

Returns

returns by default the most recent occurency of the file.

get_info_from_id(file_id)

import northgravity as ng
dh = ng.DatalakeHandler()
dh.get_info_from_id(file_id='f4b5c6d7-e8f9-0a1b-2c3d-4e5f6g7h8i9j')

Searching Method to find the metadata of the file with given id

Parameters

file_id – id of the file form datalake

Returns

the file metadata as dictionary

search_file(file_name, file_type=None, group_name=None, size=100, from_page=0)

import northgravity as ng
dh = ng.DatalakeHandler()
dh.search_file(file_name='sample_csv.csv', file_type='SOURCE', group_name='Tests')

Searching Method to find files on the datalake of the current stage for given file_name, and optionally group_name or type

Parameters

file_name – name of the file stored on the lake group
file_type – datalake file type: NCSV, SOURCE, JUPYTER, etc. If None, all types
group_name – group on datalake where to search; if None, in the entire datalake
size – size of the results to return, most recent first
from_page – iteration parameter

Returns

the file matches on the datalake and their attributes

upload_file(file, group_name, file_upload_name=None, file_type='SOURCE', partial_update=False)

import northgravity as ng
dh = ng.DatalakeHandler()
dh.upload_file(file='sample_csv.csv', group_name='my_group', file_upload_name='sample_csv.csv', file_type='SOURCE')

Upload the file to the datalake group with the given type (SOURCE as default)

Parameters

file – either the path on the disk of the file to upload either the object directly
group_name – the name of the datalake group. if None, goes to the group where the pipeline is saved
file_upload_name – if not None, upload the file on the datalake with a different name
file_type – file type to save the file in the lake - SOURCE (default), NCSV (normalized csv), etc. Default is SOURCE.

Returns

file unique ID on the datalake & the name on the datalake

northgravity.DatalakeHandler.format_query(init_query)

Properly Format the query dictionary for the API Call

Parameters

init_query (dict) – the initial query dictionary

Returns

the formatted query string

northgravity.HTTPCalller.HTTPCaller

file_uploader(payload, file, headers=None)

import northgravity as ng
hc = ng.HTTPCaller()
hc.file_uploader(payload={'name': 'test'}, file='path/to/file')

Uploads a file from disk or an object from RAM to datalake with a PUT function

Parameters

file – python object to stream or path to a disk file to upload
payload – payload to be sent with the request
headers – headers to be sent with the request

Returns

response object

get(path, headers=None)

import northgravity as ng
hc = ng.HTTPCaller()
hc.get('/file')

Sends a GET request to the API

Parameters

path – path to the API endpoint
headers – headers to be sent with the request

Returns

response object

get_from_S3(S3path)

import northgravity as ng
hc = ng.HTTPCaller()
hc.get_from_S3('s3://bucket/path/to/file')

Returns a response object from a S3 path

Parameters

S3path – path to the S3 file

Returns

response object

post(path, payload=None, data=None, headers=None)

import northgravity as ng
hc = ng.HTTPCaller()
hc.post('/file', payload={'name': 'test'})

Sends a POST request to the API

Parameters

path – path to the API endpoint
payload – payload to be sent with the request
headers – headers to be sent with the request
data – data to be sent with the request

Returns

response object

set_headers(headers=None)

import northgravity as ng
hc = ng.HTTPCaller()
hc.set_headers(headers={'Content-Type': 'application/json'})

Sets the headers for the request

Parameters

headers – headers to be sent with the request. If None, the default headers will be used.

Returns

headers

northgravity.StatusHandler.StatusHandler

Allows to send statuses to the Status Page of the NorthGravity Application. Each status type has a color and a corresponding message. - INFO: Blue - ERROR: Red - WARNING: Orange

error(message)

info(message)

send_status(status, message)

warn(message)

northgravity.TaskHandler.TaskHandler

download_from_input_parameter(arg_name, dest_file_name=None, save=False)

import northgravity as ng
th = ng.TaskHandler()
th.download_from_input_parameter('input_file', 'test.txt', save=True)

Download the file using Parameter name and save it as dest_file_name

Parameters

output_name – name of the Output parameter of the TASK to write for the next task
dest_file_name – name of the saved file including the file extension. If None it saves with original name
save – if True it saves locally the file from the input, otherwise it returns the BytesIO object (streamed from the datalake)

Returns

none if the file is saved, BytesIO object of the file if save is False

get_storage_value(key)

import northgravity as ng
th = ng.TaskHandler()
th.get_storage_value('key')

Read a value from the Storage with a key

Parameters

key – the key to get the value from storage

Returns

the value stored in the storage

read_task_parameter_value(arg_name)

import northgravity as ng
th = ng.TaskHandler()
th.read_task_parameter_value('input_file')
{'id': '5f9b9b9b9b9b9b9b9b9b9b9b', 'name': 'test.txt', 'groupName': 'test'}

Read the input value of a TASK given its name, and return the corresponding file JSON that can contain its ID, name or groupName.

If the file was passed by a previous Task (dynamically) the value should contain its ID (at least), name and groupName If the file was selected using the File Picker with the latest version of the file, then no ID is passed

Parameters

arg_name – name of the TASK parameter to be read from env variables

Returns

returns a dictionary that can contain name, groupName and id of a file ti use as the Task input

set_storage_value(key, value)

import northgravity as ng
th = ng.TaskHandler()
th.set_storage_value('key', 'value')

Write a value in the storage with a corresponding key

Parameters

key – the key to get the value from storage
value – the value to be stored

upload_to_output_parameter(output_name, file, group_name, file_upload_name=None, file_type='SOURCE', partial_update=False)

import northgravity as ng
th = ng.TaskHandler()
th.upload_to_output_parameter('output_file', 'test.txt', 'test_group')

Upload the file to the datalake as the Output of the TASK and pass its ID in the Storage for the next TASK input

Parameters

output_name – name of the Output parameter of the TASK to write for the next task
file – either the object to stream to the datalake, either the path of the file to upload to the datalake
group_name – group where to upload the output file
file_upload_name – name of the file to upload on the datalake - MANDATORY if the file is a python object and not a path to a file saved on the disk
file_type – file type on the datalake among SOURCE, NCSV

Returns

none

write_task_parameter_value(output_name, value)

import northgravity as ng
th = ng.TaskHandler()
th.write_task_parameter_value('output_file', '5f9b9b9b9b9b9b9b9b9b9b9b')
{'output_file': ('5f9b9b9b9b9b9b9b9b9b9b9b', '5f9b9b9b9b9b9b9b9b9b9b9b')}

Pass the given value in the Storage for the next TASK input

Parameters

output_name – name of the Output parameter of the TASK to write for the next task
value – value to set with the corresponding key

Returns

returns a dictionary with the key and value of the output

northgravity.TaskHandler.TaskHandler

get_symbols(search_for=None, group_name=None, _size=1000, _from=0)

import northgravity as ng
ts = ng.Timeseries()
ts.get_symbols(search_for='AAPL')

The method returns a list of symbols available on a given group or symbols within search.

Parameters

search_for (Optional[str]) – given symbol. Default is None
group_name (Optional[str]) – symbol search. Default is None

Returns

a list of the symbols available on a given group or symbols within search

retrieve_data_as_csv(symbols, columns, group_name, file_name=None, start_date=None, end_date=None, timezone=None, metadata=False, allow_wildcard=False, output_format='NCSV', corrections='false', delta=False)

import northgravity as ng
ts = ng.Timeseries()
ts.retrieve_data_as_csv(symbols={"symbolName": "symbolValue"}, columns=["column1", "column2"], group_name="group_name", file_name="data.csv")

The method retrieves the data from NG Timeseries based on symbols and columns with streaming function. Optionally start and end dates can be specified. If no dates specified, all the available data are taken.

IMPORTANT! Currently in streaming mode NCSV output is available.

Parameters

file_name (Optional[str]) – the name of file locally to save data to, with the proper extension passed (for example data.csv)
symbols (dict) – symbols to identify data in Timeseries. Must dictionary {“symbolName”: “symbolValue”}
columns – name of column or list of columns to retrieve
group_name (str) – name of the group
start_date (Optional[str]) – start date of data in the format YYYY-MM-DD. If time is included, it must follow ISO format - YYYY-MM-DDTHH:mm:ss (note the ‘T’ letter separating the date and time part)
end_date (Optional[str]) – end date of the data in the format YYYY-MM-DD. If time is included, it must follow ISO format - YYYY-MM-DDTHH:mm:ss (note the ‘T’ letter separating the date and time part)
timezone (Optional[str]) – timezone as string used for the timestamps in the Date column. Continent/City, for example Europe/London if None, it returns the date with the default timezone of the user, set in the application
corrections (str) – how to handle corrections in time series. Must be either true, false, history or only. Default is false
delta (bool) – delta will filter timeseries by insertion date instead of the actual timestamp of data
metadata (bool) – boolean to return or not the metadata in the file, default as False
allow_wildcard (bool) – boolean to allow or not the use of wildcards ‘*’ in the keys or columns. Default as False
corrections – how to handle corrections in time series. Must be either true, false, history or only. Default is false
delta – delta will filter timeseries by insertion date instead of the actual timestamp of data
output_format (str) – the method from which “view” the data should be retrieved. Default is NCSV. The other option is JSON

Returns

saved file with data

retrieve_data_as_json(symbols, columns, group_name, file_name=None, start_date=None, end_date=None, timezone=None, metadata=False, allow_wildcard=False, output_format='NCSV', corrections='false', delta=False)

import northgravity as ng
ts = ng.Timeseries()
ts.retrieve_data_as_json(symbols={"symbolName": "symbolValue"}, columns="column1", group_name="group1", file_name="data.csv")

IMPORTANT! Currently NCSV output_format returns the same as for streaming functions. STANDARD, PANDAS, UI return json.

Parameters

file_name (Optional[str]) – the name of file locally to save data to, with the proper extension passed (for example data.csv)
symbols (dict) – symbols to identify data in Timeseries. Must dictionary {“symbolName”: “symbolValue”}
columns – name of column or list of columns to retrieve
group_name (str) – name of the group
start_date (Optional[str]) – start date of data in the format YYYY-MM-DD. If time is included, it must follow ISO format - YYYY-MM-DDTHH:mm:ss (note the ‘T’ letter separating the date and time part)
end_date (Optional[str]) – end date of the data in the format YYYY-MM-DD. If time is included, it must follow ISO format - YYYY-MM-DDTHH:mm:ss (note the ‘T’ letter separating the date and time part)
timezone (Optional[str]) – timezone as string used for the timestamps in the Date column. Continent/City, for example Europe/London if None, it returns the date with the default timezone of the user, set in the application
corrections (str) – how to handle corrections in time series. Must be either true, false, history or only. Default as ``false
delta (bool) – delta will filter timeseries by insertion date instead of the actual timestamp of data
metadata (bool) – boolean to return or not the metadata in the file, default as False
allow_wildcard (bool) – boolean to allow or not the use of wildcards ‘*’ in the keys or columns. Default as False
corrections – how to handle corrections in time series. Must be either true, false, history or only. Default as false
delta – delta will filter timeseries by insertion date instead of the actual timestamp of data
output_format (str) – the method from which “view” the data should be retrieved. Default NCSV. Other options are STANDARD, PANDAS, UI

Returns

saved file with data

upload_data(file_name, symbols_columns, date_column, group_name)

import northgravity as ng
ts = ng.Timeseries()
ts.upload_data(file_name='data.csv', symbols_columns=['Country', 'Product'], date_column='Date', group_name='MyGroup')

The methods uploads data to Timeseries by re-arranging the columns order and uploading the new file as NCSV.

Parameters

file_name – csv file to be upload to Timeseries
symbols_columns – columns to be used as symbols
date_column – date column in the file; is renamed to DateTime as expected by NCSV
group_name – group name for the NCSV file to upload

Returns

id of the NCSV file uploaded

Subscription Notification Webhook API

This API allows clients to register webhooks to receive notifications for events related to file arrivals in the datalake and timeseries processing completion.

Clients can manage their subscriptions via a set of CRUD endpoints. The notifications include an HMAC signature (if a secret is provided) so that the client can verify the integrity and authenticity of the payload.

Note:
You must be a valid NG user. When making requests, include your NG token in the Authorization header. For each subscription, the client supplies a callback URL (i.e., the webhook endpoint) and optionally a secret. This secret is later used to compute an HMAC SHA-256 signature of the notification payload.

Endpoints Overview

POST https://api.northgravity.com/notification/subscription – Create a new subscription
PUT https://api.northgravity.com/notification/subscription – Update an existing subscription
DELETE https://api.northgravity.com/notification/subscription/{id} – Delete a subscription
GET https://api.northgravity.com/notification/subscription/{id} – Retrieve a subscription by ID
GET https://api.northgravity.com/notification/subscription – List all subscriptions for a user

Create Subscription

HTTP Request

curl -X POST "https://api.northgravity.com/notification/subscription" \
  -H "Authorization: Bearer {yourNgToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://your-callback-url.com/webhook",
    "secret": "optionalSecret",
    "groupEvents": [
      {
        "groupName": "DatalakeGroup1",
        "eventType": "FILE_ARRIVAL",
        "fileType": "SOURCE"
      },
      {
        "groupName": "DatalakeGroup2",
        "eventType": "TS_COMPLETE",
        "fileType": ""
      }
    ]
  }'

Request Body Parameters

Parameter	Type	Description
callbackUrl	String, required	The URL to which notifications will be sent.
secret	String, optional	A client-provided secret used to compute an HMAC signature for outgoing notifications. If omitted, no signature header is included.
groupEvents	Array, required	A list of group events for which notifications are desired. Each event object must include the following fields:

Each Group Event Object

Parameter	Type	Description
groupName	String, required	The name of the group.
eventType	String, required	The event type. Valid values are: - `FILE_ARRIVAL` – Indicates that a file has arrived in the datalake. - `TS_COMPLETE` – Indicates that timeseries processing has finished. Note: For `TS_COMPLETE` events, the `fileType` field is ignorable.
fileType	String, optional	The type of file that triggers the event. This field is required for `FILE_ARRIVAL` events. Valid file types are defined in the FileType enumeration below.

FileType Enumeration

The valid file types are: - SOURCE - NCSV - D_NCSV - SYM_NCSV - COMMAND_JSON - DATA_PREP - GDP - PY_SCRIPT - PY_EXEC - DOWNLOADER - BASKET - SM_GDP - INSIGHT - OBJECTIVE - PIPELINE - TASK - BLV - EMAIL - MARKDOWN - CONFIG - UICONFIG

Response

Code	Description
200	Success
400	Bad Request. "Group with name=GroupName doesn't exist." - you try to create event for group that doesn't exist.
400	Bad Request. "Invalid eventType: FILE_ARRIVAL2. Valid values are: [FILE_ARRIVAL, TS_COMPLETE]" - provide valid eventType.
400	Bad Request. "Invalid fileType: fileType" - provide valid fileType.

Update Subscription

This endpoint updates an existing subscription.

You can activate and deactivate subscription using active flag.

HTTP Request

curl -X PUT "https://api.northgravity.com/notification/subscription" \
  -H "Authorization: Bearer {yourNgToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 10,
    "callbackUrl": "https://your-callback-url.com/webhook",
    "secret": "optionalSecret",
    "active": true,
    "groupEvents": [
      {
        "groupName": "DatalakeGroup1",
        "eventType": "FILE_ARRIVAL",
        "fileType": "NCSV"
      },
      {
        "groupName": "DatalakeGroup2",
        "eventType": "TS_COMPLETE",
        "fileType": ""
      }
    ]
  }'

Request Body Parameters

Parameter	Type	Description
callbackUrl	String, required	The URL to which notifications will be sent.
secret	String, optional	A client-provided secret used to compute an HMAC signature for outgoing notifications. If omitted, no signature header is included.
active	Boolean, required	The active status of the subscription.
groupEvents	Array, required	A list of group events for which notifications are desired. Each event object must include the following fields:

Each Group Event Object

Parameter	Type	Description
groupName	String, required	The name of the group.
eventType	String, required	The event type. Valid values are: - `FILE_ARRIVAL` – Indicates that a file has arrived in the datalake. - `TS_COMPLETE` – Indicates that timeseries processing has finished. Note: For `TS_COMPLETE` events, the `fileType` field is ignorable.
fileType	String, optional	The type of file that triggers the event. This field is required for `FILE_ARRIVAL` events. Valid file types are defined in the FileType enumeration below.

Response

Code	Description
200	Success
400	Bad Request. "Group with name=GroupName doesn't exist." - you try to create event for group that doesn't exist.
400	Bad Request. "Invalid eventType: FILE_ARRIVAL2. Valid values are: [FILE_ARRIVAL, TS_COMPLETE]" - provide valid eventType.
400	Bad Request. "Invalid fileType: fileType" - provide valid fileType.

Delete Subscription

This endpoint deletes an existing subscription.

HTTP Request

curl -X DELETE "https://api.northgravity.com/notification/subscription/{id}" \
  -H "Authorization: Bearer {yourNgToken}"

Request Path Parameters

Parameter	Type	Description
id	Number, required	The unique ID of the subscription to delete, provided in the URL.

Response

Code	Description
200	Success

Get Subscription

This endpoint get an existing subscription.

HTTP Request

curl -X GET "https://api.northgravity.com/notification/subscription/{id}" \
  -H "Authorization: Bearer {yourNgToken}"

Request Path Parameters

Parameter	Type	Description
id	Number, required	The unique ID of the subscription to get, provided in the URL.

Response

Code	Description
200	Success
404	Subscription not found

Get List of Subscriptions For User

This endpoint get list of existing subscriptions for user who requests.

HTTP Request

curl -X GET "https://api.northgravity.com/notification/subscription" \
  -H "Authorization: Bearer {yourNgToken}"

Response

Code	Description
200	Success

HMAC Signature Authentication

When sending webhook notifications, the server computes an HMAC SHA-256 signature of the payload using a secret provided by the client during subscription creation. This signature is added to the HTTP request as the X-Signature header. The client can then verify the authenticity and integrity of the payload by re-computing the HMAC with its own copy of the secret.

Client-Side Verification

On the client side, to verify the webhook notification:

Extract the Payload and Signature

Retrieve the JSON payload and the value of the X-Signature header from the incoming request.

Recompute the HMAC

Using the same algorithm and the secret (which the client stored when creating the subscription), compute the HMAC for the received payload.

Compare Signatures

Compare the recomputed HMAC with the X-Signature value.

Introduction

Authorization

Create a Company

HTTP Request

Request Body

Company Information

HTTP Request

Response Body

Edit Company

HTTP Request

Response Body

Important Notes

Create a User

HTTP Request

Request Body

Get User

HTTP Request

Response Body

Update User

HTTP Request

Response Body

Important Notes

Hard Delete A User

HTTP Request

Important Notes

Transfer User's Ownership

HTTP Request

Important Notes

Activate A User

HTTP Request

Change password

HTTP Request

Request Body

Log in

HTTP Request

Request Body

Refresh Access Token

HTTP Request

Request Body

Log out

HTTP Request

Share some group, file or symbol

HTTP Request

Request Body

Delete access rights for sharing group, file or symbol

HTTP Request

Request Body

List of users who share some group, file or symbol

HTTP Request

Request Parameters

List of users emails which are in the same company as user

HTTP Request

Request Parameters

HTTP Response

List of users

HTTP Request

Request Parameters

HTTP Response

List roles

HTTP Request

HTTP Response

Query Parameters

Create role

HTTP Request

Request Body

HTTP Response

Update role

HTTP Request

Request Body

HTTP Response

URL Parameters

Delete role

HTTP Request

URL Parameters

HTTP Response

Describe role

HTTP Request

HTTP Response

URL Parameters

Api entitlements for role