NAV
curl

Introduction

Welcome to Gridly API document. You can use our API endpoints to access your data in Gridly

Gridly API is organized around REST, accepts raw-data request bodies, returns standard HTTP response codes, authentication, and verbs.

We have language bindings in Curl, you can view code examples in the area to the right.

Authentication

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/{VIEW_ID}/records' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

Gridly API uses API key to authenticate requests. All API requests must be made over HTTPS and authenticated by having the API key included in the HTTP request header that looks like the following:

Authorization: ApiKey {YOUR_API_KEY}

To quickly get your API key, access your Gridly Dashboard, then select a Grid View and you can find the key in API quick start right panel.

Note: Owner and Administrators can go to Settings/API keys to create company-level API keys with scoped privileges and accesses.

Make sure to replace {YOUR_API_KEY} and {VIEW_ID} with yours.

Errors

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/xpzyv44ym2v49f' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
    "timestamp": "2021-05-31T14:25:13.293065+07:00",
    "status": 404,
    "code": "viewIsNotFound",
    "message": "View \"xpzyv44ym2v49f\" could not be found.",
    "path": "/v1/views/xpzyv44ym2v49f/records"
}

Gridly API uses conventional HTTP response codes to indicate the success or failure of a request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate user errors that failed given the information provided. Codes in the 5xx range indicate errors from Gridly’s servers.

An error response will return a JSON body that contains code and message fields. Those will provide specific error conditions and human-readable message to identify what caused the error.

The following table explains the REST error response elements.

Name Description
status The http-status of the error. Please check user error codes below for more details.
code The unique readable code explains why the request is failed.
message The detailed message of single error.
messages The detailed messages of multiple errors.
path The requested path has caused the error.
timestamp The time that the error is occurred.

Http statuses

Status Description
200 Ok Request executed successfully.
201 Created Resource created successfully.
202 Accepted Request accepted.
204 Deleted Resource deleted successfully.
400 Bad Request The request was unacceptable, often due to missing a required parameter or JSON request body fails to be parsed.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
403 Forbidden The API key doesn’t have permissions to perform the request.
404 Not Found The requested resource doesn’t exist.
405 Method Not Allowed The request method was received and recognized by the server, but the server has rejected that particular method for the requested resource.
409 Conflict The request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.
422 Unprocessable Entity The syntax of request is correct, but it was unable to process the contained instructions.
5xxx Server Errors Something went wrong with Gridly server. The server encountered an unexpected condition that prevented it from fulfilling the request. Please contact our support for assistance.

Gridly error codes

Code Description
unauthorized Unauthorized request.
accessDenied Access denied.
badRequest Request is invalid. Please check message fields for more details.
requestParameterMissing Request parameter is missing.
requestBodyMissing Request body is missing.
unsupportedMediaType Media type is not supported.
methodNotAllowed Method is not allowed.
internalServerError Something went wrong in Gridly server. Please contact our support for assistance.
gridIsNotFound Grid is not found.
viewIsNotFound View is not found.
columnNotFoundInView Column is not found in the requested view .
columnIsNotEditableInView Columns is not editable. This happens if the request tries to update non-editable column in view.
columnIsNotFilesType Upload a file to a column that is not a FILES column type.
invalidColumnId Column ID is not valid. Please check message fields for more details.
nullRecordId Record ID is null in the PATCH request.
invalidRecordId Record ID is not valid. Please check message fields for more details.
invalidLengthRecordId Maximum length of a record is 500 characters.
duplicateRecordId Record is duplicated with other IDs in the same request.
nonexistentRecordId Record is not existed.
requestRecordsExceedLimitation Maximum size of records is 1000 while adding or updating records.
referenceRecordNotFound Reference record is not found.
invalidFilterField Filter field is not valid. Please check message fields for more details.
invalidFilterOperator Filter operator is not valid. Please check message fields for more details.
invalidFilterValue Filter value is not valid. Please check message fields for more details.
missingFilterValue Filter value is missing.
filterColumnNotFound Filter column is not found.
invalidSortField Sort field is not valid. Please check message fields for more details.
invalidSortDirection Sort direction is not valid. Please check message fields for more details.
sortColumnNotFound Sort column is not found.
invalidPaging Paging is not valid. Please check message fields for more details.
metadataExceedMaximumKey Maximum keys of metadata is 50.

Changelog

2024-03-20

2023-10-04

Updated headers for default columns in export file:

2023-05-18

Added api for path

Project

Project resource

Project resource representation

{ "id": string, "name": string, "description": string }

This table explains each property in the project resource.

Property name Type Description Note
id string Project ID Read-only
name string Project name Read-only
description list Description Read-only

List projects

CODE

curl --location --request GET 'https://api.gridly.com/v1/projects' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
  {
    "id": 42,
    "name": "Foodie",
    "description": "I love food"
  }
]

To list projects of a company.

HTTP Request

GET /v1/projects

Response

Return a list of projects in an array if succeeded. Otherwise, return an error.

Retrieve a project

CODE

curl --location --request GET 'https://api.gridly.com/v1/projects/42' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
  "id": 42,
  "name": "Foodie",
  "description": "I love food"
}

To retrieve a project.

HTTP Request

GET /v1/projects/<id>

ID can be found in the URL of the web application: app.gridly.com/projects/<id>.

Response

Return project data in object if succeeded. Otherwise, return an error.

Database

Database resource

Database resource representation

{ "id": string, "name": string }

This table explains each property in the database resource.

Property name Type Description Note
id string Database ID Read-only
name string Database name Read-only

List databases

CODE

curl --location --request GET 'https://api.gridly.com/v1/databases?projectId=42' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
  {
    "id": "me8y2x4v5v3djy",
    "name": "Cuisine"
  }
]

To list databases of a project.

HTTP Request

GET /v1/databases

Parameter

projectId optional

ID of the project. The ID can be found in the URL of the web application: app.gridly.com/projects/<id>.

Response

Return a list of databases in an array if succeeded. Otherwise, return an error.

Retrieve a database

CODE

curl --location --request GET 'https://api.gridly.com/v1/databases/me8y2x4v5v3djy' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
  "id": "me8y2x4v5v3djy",
  "name": "Cuisine"
}

To retrieve a database.

HTTP Request

GET /v1/databases/<id>

Response

Return database data in an object if succeeded. Otherwise, return an error.

Grid

Grid resource

Grids are like sheets or a table within a database.

Grid resource representation

{ "id": string, "name": string, "columns": [ { "id": string, "name": string, "type": string, "languageCode": string, "isSource": boolean, "isTarget": boolean, "dependsOn": string, "reference": { "grid": { "name": string }, "column": { "name": string, "type": string } } } ] }

This table explains each property in the grid resource.

Property name Type Description Note
id String Grid ID Read-only
name String Grid name Read-only
status String Current status of the grid Read-only
columns List List of columns within a grid Read-only
columns[].id String Column ID Read-only
columns[].name String Column name Read-only
columns[].type String Column type Read-only
columns[].languageCode String Language code of “language” column Read-only
columns[].isSource Boolean Whether the column is source Read-only
columns[].isTarget Boolean Whether the column is target Read-only
columns[].dependsOn String Column ID of source target Read-only
columns[].reference Object Reference to other grid Read-only
columns[].reference.grid String Referenced grid Read-only
columns[].reference.grid.name String Name of referenced grid Read-only
columns[].reference.column String Referenced grid  Read-only
columns[].reference.column.name String Name of referenced column  Read-only
columns[].reference.column.type String Type of referenced column  Read-only
columns[].selectionOptions[] List List of selection options Read-only

List grids

CODE

curl --location --request GET 'https://api.gridly.com/v1/grids?dbId=3xep36emk4j1dq' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
  {
    "id": "v182ye104j8o33",
    "name": "Pizza"
  },
  {
    "id": "me6q2mvj4868l8",
    "name": "Burger"
  }
]

To list grids of a database.

GET /v1/grids

Parameters

dbId required

ID of the database you want to list of all the grids.

Response

Return a list of grids from a database if succeeded. Otherwise, return an error.

Retrieve a grid

CODE

curl --location --request GET 'https://api.gridly.com/v1/grids/em8vw50wzkl111' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
  "id": "em8vw50wzkl111",
  "name": "Food",
  "columns": [
    {
      "id": "ingredient",
      "name": "Ingredient",
      "type": "multipleLines"
    },
    {
      "id": "price",
      "name": "Price",
      "type": "number"
    }
  ]
}

To retrieve a grid.

HTTP Request

GET /v1/grids/<id>

Response

Return grid data in an object if succeeded. Otherwise, return an error.

Create grid

CODE

curl --location --request POST 'https://api.gridly.com/v1/grids?dbId=xk0d5xz8j4xj6v' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'' \
--header 'Content-type: application/json' \
--data-raw '{
   "name": "Food",
   "metadata": {
           "city": "Helsingborg",
           "cost": "42"
   }
}

OUTPUT

{
  "id": "410nzk2op1zedp",
  "defaultAccessViewId": "me35v9mqd0e93y",
  "name": "Food",
  "metadata": {
     "city": "Helsingborg",
     "cost": "42"
   }
}

To create a grid.

POST /v1/grids

Path parameters

Parameters Type Description
dbId string Database ID

Request body

Parameters Type Description Required
name String Grid name false
templateGridId string Template grid to create from false
metadata key-value map of string Metadata false

You can find templateGridId of each template by going ty “Templates”, then select corresponding template.

Response

Return database data in an object if succeeded. Otherwise, return an error.

Update a grid

CODE

curl --location --request PATCH 'https://api.gridly.com/v1/grids/410nzk2op1zedp' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-type: application/json' \
--data-raw '{
   "name": "Fast Food",
   "metadata": {
           "type": "Burger",
           "cost": "42"
   }
}'

OUTPUT

{
  "id": "410nzk2op1zedp",
  "defaultAccessViewId": "me35v9mqd0e93y",
  "name": "Fast Food",
  "metadata": {
     "type": "Burger",
     "cost": "42"
   }
}

To update a grid from a database.

HTTP Request

PATCH /v1/grids/<id>

Request body

Parameters Type Description Required
name string New grid’s name that you want to update FALSE
metadata object Metadata object containing properties of the grid. Passing null into value will remove that key-value property. FALSE

Response

Return grid ’s name and metadata in an object if succeeded. Otherwise, return an error.

Delete a grid

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/grids/410nzk2op1zedp' \
--header 'Authorization: ApiKey yourApiKey'

To delete a grid.

DELETE /v1/grids/<id>

Path parameters

Parameters Description Type
gridId Grid ID string

View

View resource

CODE

curl --location --request POST 'https://api.gridly.com/v1/grids?dbId=xk0d5xz8j4xj6v

Views represent a way to display all data or a subset of data.

View resource representation

{ "id": string, "name": string, "columns": [ { "id": string, "name": string, "type": string, "languageCode": string, "isSource": boolean, "isTarget": boolean, "dependsOn": string, "reference": { "grid": { "name": string }, "column": { "name": string, "type": string } } } ], "records": [ <recordRepresentation>, ... ] }

This table explains each property in the view resource.

Property name Type Description Note
id String View ID Read-only
name String View name Read-only
gridId String The grid id that view belongs to Read-only
gridStatus String The current grid status that view belongs to Read-only
columns List List of columns within a view Read-only
columns[].id String Column ID Read-only
columns[].name String Column name Read-only
columns[].type String Column type Read-only
columns[].languageCode String Language code of “language” column Read-only
columns[].isSource Boolean Whether the column is source Read-only
columns[].isTarget Boolean Whether the column is target Read-only
columns[].dependsOn String Column ID of source target Read-only
columns[].reference Object Reference to other grid Read-only
columns[].reference.grid String Referenced grid Read-only
columns[].reference.grid.name String Name of referenced grid Read-only
columns[].reference.column String Referenced grid  Read-only
columns[].reference.column.name String Name of referenced column  Read-only
columns[].reference.column.type String Type of referenced column  Read-only
columns[].selectionOptions[] List List of selection options Read-only
records List List of records within a view Read-only

List views

CODE

curl --location --request GET 
'https://api.gridly.com/v1/views?gridId=v1jqdkj24j1nkz' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
  {
    "id": "41wk9m9q0w8mnn",
    "name": "Default View"
  },
  {
    "id": "emv2qozw1jn5vo",
    "name": "Default view"
  },
  {
    "id": "me2jk8me5225l8",
    "name": "Pizza"
  },
  {
    "id": "emv2qjxv3pjo11",
    "name": "Burger"
  }
]

To list views of a grid or branch.

HTTP Request

GET /v1/views

Parameters

gridId conditionally required.

ID of a grid. This is required if branchId is not specify

branchId conditionally required.

ID of a branch. This is required if gridId is not specify

Response

Return a list of view in an array if succeeded. Otherwise, return an error.

Retrieve a view

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
  "id": "v1v9jwwk1lwnkz",
  "name": "Food",
  "columns": [
    {
      "id": "ingredient",
      "name": "Ingredient",
      "type": "multipleLines"
    },
    {
      "id": "price",
      "name": "Price",
      "type": "number"
    }
  ]
}

To retrieve an existing view.

The API returns a view data in object, we can get all the columns of the view via columns field of this object.

HTTP Request

GET /v1/views/<id>

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

Response

Return view data in an object if succeeded. Otherwise, return an error.

Make sure to replace {YOUR_API_KEY} and {VIEW_ID} with yours.

Create view

CODE

curl --location --request POST 'https://api.gridly.com/v1/views' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'' \
--header 'Content-type: application/json' \
--data-raw '{
   "name": "Food",
   "gridId": "410nzk2op1zedp",
   "columns": [
    {
      "id": "ingredient",
      "editable": "true"
    },
    {
      "id": "price",
      "editable": "true"
    }
  ]
}

OUTPUT

{
  "id": "v1v9jwwk1lwnkz",
  "name": "Food",
  "columns": [
    {
      "id": "ingredient",
      "name": "Ingredient",
      "type": "multipleLines"
    },
    {
      "id": "price",
      "name": "Price",
      "type": "number"
    }
  ]
}

To create a collaborative view.

POST /v1/views

Request body

Parameters Type Description Required
name String View name true
gridId String Grid Id that view belongs to true
columns Arrays List view columns false

columns

Parameters Type Description Required
id String Existing column Id that needs adding to the view true
editable Boolean Enable editable for this column. Default is true false

Response

Return view data in an object if succeeded. Otherwise, return an error.

Import

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/import' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}' \
--form 'file=@"/Users/tri/Desktop/fastlane.csv"' \
--form 'importRequest="{ 
 "firstDataRow": 1,
 "columnMappings":[{
   "columnId": "column1",
   "fileColumnIndex": 1
   }]
  }"'

To import a file (.csv) into a view.

Import API use multipart request

HTTP Request

POST /v1/views/<id>/import

Request body

Parameters Type Description Required
file .csv The spreadsheet file that contains data you want to import into Gridly. By default, columns will be mapped automatically between the file’s header names and the View’s column names. True
importRequest json JSON object to instruct how to read the file. Note: if you have the column with header’s name _recordId, Gridly will automatically map this with its Record ID column. False

importRequest

{ "withHeader": true, "backup": true, "columnMappings": [ { "columnId": "column1", "fileColumnIndex": 0 } ] }

Parameters Type Description
withHeader boolean Indicate the file has a header or not
backup boolean Instruct to backup the grid before importing. This is to allow to revert the grid before the importing action. Default value is true.
columnMappings json To map between Gridly ’s column ID and index of the column in the file. This mapping is mandatory when importing files without a header.

Response

Returns status 202 to indicate the server has accepted the file.

Export

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/export' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

To export data from a view into a file (.csv).

HTTP Request

GET /v1/views/<id>/export

Request parameters

Parameters Type Description Required
fileHeader Enum List of valid values are columnName, columnId and none. Default column name is exported as file header, use columnId to export column id as header, set to none if you want to export data only. FALSE

Response

Return spreadsheet file (.csv) contains all columns and records of the View.

Merge a view

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/em8vw50wzkl111/merge?destinationViewId=xk0d5xz8j4xj6v&mergeRecordOptions=add,update,delete,override' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-type: application/json'

OUTPUT

{
  "id": "410nzk2op1zedp",
  "status": "running"
}

To merge a view of branch to other view of other branch

HTTP Request

POST /v1/views/<viewId>/merge

Request parameters

Parameters Type Description Required
destinationViewId String ID of the view to merge over TRUE
mergeRecordOptions Array A list of options to instruct how records are merged TRUE

mergeRecordOptions

Option Description
add Merge new records from view to destination view
delete Merge deleted records from view to destination view
update Merge updated record from view to destination view. If the same cell was updated on both views, the change of source view’s cell will be ignored if override option is not specified.
override Work with update option to instruct if the same cell was updated on both views, the change of source cell will be merged.

Response

Return asynchronous task of the request with id and status. To retrieve the latest status, check task api.

CODE

curl --location --request PUT 'https://api.gridly.com/v1/views/<viewId>/shares' 
--header 'Authorization: ApiKey {YOUR_API_KEY}' 
--header 'Content-Type: application/json' 
--data-raw '{
    "includeGridHistory": false
}'

OUTPUT

{
    "companyId": <companyId>,
    "link": "https://app.gridly.com/shared/<sharedId>",
    "active": true,
    "viewId": <viewId>,
    "includeGridHistory": false,
    "createdDate": "2023-07-06T03:12:02Z",
    "lastModifiedDate": "2023-08-02T04:59:04.848Z"
}

To create a shareable link from view

HTTP Request

PUT /v1/views/{viewId}/shares

Request body

Parameters Type Description Required
includeGridHistory Boolean Allow viewing grid history on shared link. FALSE

Response

Return shared link and metadata in an object if succeeded. Otherwise, return an error.

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/<viewId>/shares' 
--header 'Authorization: ApiKey {YOUR_API_KEY}' 
--header 'Content-Type: application/json'

OUTPUT

{
    "companyId": <companyId>,
    "link": "https://app.gridly.com/shared/<sharedId>",
    "active": true,
    "viewId": <viewId>,
    "includeGridHistory": false,
    "createdDate": "2023-07-06T03:12:02Z",
    "lastModifiedDate": "2023-08-02T04:59:04.848Z"
}

To get a shareable link from view.

HTTP Request

GET /v1/views/{viewId}/shares

Response

Return shared link and metadata in an object if succeeded. Otherwise, return an error.

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/views/<viewId>/shares' 
--header 'Authorization: ApiKey {YOUR_API_KEY}' 
--header 'Content-Type: application/json'

To disable a shareable link from view.

DELETE /v1/views/<viewId>/shares

Response

If successful, this method returns an empty response body.

Column

Column resource

Column resource representation

{
  "id": string,
  "isSource": boolean,
  "isTarget": boolean,
  "name": string,
  "numberFormat": {
    "type: string,
    "decimalPlaces": number,
    "currencySymbol": string,
    "use1000Separator": boolean
  }
  "selectionOptions": [
  	 string, ...
  ]
  "reference": {
    "column": {
      "id": string,
      "name": string
    },
    "grid": {
      "id": string,
      "name": string
    },
    "type": string
  },
  "type": string
}

This table explains each property in the column resource.

Property name Type Description Notes
id String Column ID
name String Column name
description String Column description
type String Column type Read-only
languageCode String Language code
isSource Boolean Whether the column is soure Read-only
isTarget Boolean Whether the column is target Read-only
dependsOn String Column ID of source target Read-only
reference Object Reference to other grid
reference.grid String Referenced grid
reference.grid.name String Name of referenced grid
reference.branch String Referenced branch
reference.branch.name String Name of referenced branch
reference.column String Referenced grid 
reference.column.name String Name of referenced column 
reference.column.type String Type of referenced column 
selectionOptions[] List List of selection options
numberFormat Object Number format
numberFormat.type String Reference column type. Possible values: decimal, integer
numberFormat.decimalPlaces String Decimal places of numbers
numberFormat.currencySymbol String Currency symbol
numberFormat.use1000Separator String Should put 1000 seperator
reference.gridId String Reference grid ID
reference.branchId String Reference branch ID
reference.columnId String Reference column ID
reference.type String Reference column type. Possible values: row, cell.
formula Object Formula
formula.formulaText String Formula text
formula.alwaysFormatResultValueAsList String Should always format result in list format
formula.detectResultValueType String Detect result type of formula value

Predefined columns

Predefined column representation

Predefined column IDs are denoted with _ . This table describes column Id for each column, which can be used on filtering and sorting record.

Column ID Description
_recordId Record ID
_path Record path
_lastModifiedTime Record last modified time
_lastModifiedBy Record last modified by

Retrieve a column

CODE

curl --location --request GET 'http://api.gridly.com/v1/views/ednq6m4m50pykl/columns/ingredient' \
--header 'Authorization: ApiKey yourApiKey'

OUTPUT

{
  "id": "ingredient",
  "isSource": false,
  "isTarget": false,
  "name": "Ingredient",
  "type": "singleLine"
}

To retrieve a column.

HTTP Request

GET /v1/views/<viewId>/columns/<id>

Path parameters

Parameters Description Type
viewId View ID String
id Column ID String

Create a column

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/ednq6m4m50pykl/columns' \
--header 'Authorization: ApiKey yourApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Ingredient",
    "type": "singleLine"
}'

OUTPUT

{
  "id": "column1",
  "isSource": false,
  "isTarget": false,
  "name": "Ingredient",
  "type": "singleLine"
}

To create a column.

POST /v1/views/<viewId>/columns

Path parameters

Parameters Description Type
viewId View ID String

Request body

Required parameters

Parameters Type Description
name String Column name
type string Column type. See the list below.

Column types include singleLine, multipleLines, richText , markdown, singleSelection, multipleSelections, boolean, number, datetime, files, reference, language, formula, json and yaml.

Optional parameters

Parameters Type Description Format/Possible values
id String Column ID Alphanumeric
languageCode String Language code Alphanumeric
numberFormat Object Number format
numberFormat.type String Reference column type decimal, integer
numberFormat.decimalPlaces String Decimal places of numbers Decimal places
numberFormat.currencySymbol String Currency symbol
selectionOptions List Selection options
reference.gridId String Reference grid ID Alphanumeric
reference.branchId String Reference branch ID Alphanumeric
reference.columnId String Reference column ID Alphanumeric
reference.type String Reference column type row, cell
formula Object Formula info
formula.formulaText String Formula text expression (ex: len(col_val_column1) / 10)
formula.alwaysFormatResultValueAsList Boolean Result value format

Update a column

CODE

curl --location --request PATCH 'https://api.gridly.com/v1/views/mqnl0vej02l5l8/columns/recipe' \
--header 'Authorization: ApiKey yourApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Best-selling recipe"
    "languageCode": "frFR"
}'

OUTPUT

{
  "id": "recipe",
  "isSource": false,
  "isTarget": false,
  "languageCode": "frFR",
  "name": "Best-selling recipe",
  "type": "language"
}

To update a column.

PATCH /v1/views/<viewId>/columns/<id>

Path parameters

Parameters Description Type
viewId View ID String
id Column ID String

Request body

Optional parameters

Parameters Type Description Format/Possible values
id String Column ID Alphanumeric
name String Column name Alphanumeric
languageCode String Language code Alphanumeric
numberFormat Object Number format
numberFormat.type String Reference column type decimal, integer
numberFormat.decimalPlaces String Decimal places of numbers Decimal places
numberFormat.currencySymbol String Currency symbol
selectionOptions List Selection options
reference.gridId String Reference grid ID Alphanumeric
reference.branchId String Reference branch ID Alphanumeric
reference.columnId String Reference column ID Alphanumeric
reference.type String Reference column type row, cell
formula Object Formula info
formula.formulaText String Formula text expression
formula.alwaysFormatResultValueAsList Boolean Result value format

Delete a column

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/views/mqnl0vej02l5l8/columns/ingredient' \
--header 'Authorization: ApiKey yourApiKey'

To delete a column.

DELETE /v1/views/<viewId>/columns/<id>

Path parameters

Parameters Description Type
viewId View ID string
id Column ID string

Add a column to a view

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/mqnl0vej02l5l8/columns/ingredient/add' \
--header 'Authorization: ApiKey yourApiKey'

OUTPUT

{
  "id": "ingredient",
  "isSource": false,
  "isTarget": false,
  "name": "Ingredient",
  "type": "singleLine"
}

To add an existing grid column to a view.

POST /v1/views/<viewId>/columns/<id>/add

Path parameters

Parameters Description Type
viewId View ID String
id Column ID String

Remove a column from a view

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/mqnl0vej02l5l8/columns/ingredient/remove' \
--header 'Authorization: ApiKey yourApiKey'

To remove a column from a view.

POST /v1/views/<viewId>/columns/<id>/remove

Path parameters

Parameters Description Type
viewId View ID String
id Column ID String

Dependency

Dependency resource

Dependency resource representation

{
  "id": string,
  "sourceColumnId": string,
  "targetColumnId": string
}

This table explains each property in the dependency resource.

Property name Type Description Notes
id String Dependency ID
sourceColumnId String Source column ID
targetColumnId String Target column ID

List dependencies

CODE

curl --location --request GET 'http://api.gridly.com/v1/views/ednq6m4m50pykl/dependencies' \
--header 'Authorization: ApiKey yourApiKey'

OUTPUT

[
  {
    "id": "mddn9jyedd43q6y",
    "sourceColumnId": "enUS",
    "targetColumnId": "viVN"
  },
  {
    "id": "ewwn4xv502y5ykl",
    "sourceColumnId": "enUS",
    "targetColumnId": "frFR"
  }
]

To list dependencies.

HTTP Request

GET /v1/views/<viewId>/dependencies

Path parameters

Parameters Description Type
viewId View ID String

Retrieve a dependency

CODE

curl --location --request GET 'http://api.gridly.com/v1/views/ednq6m4m50pykl/dependencies/mddn9jyedd43q6y' \
--header 'Authorization: ApiKey yourApiKey'

OUTPUT

{
  "id": "mddn9jyedd43q6y",
  "sourceColumnId": "enUS",
  "targetColumnId": "viVN"
}

To retrieve a dependency.

HTTP Request

GET /v1/views/<viewId>/dependencies/<id>

Path parameters

Parameters Description Type
viewId View ID String
id Dependency ID String

Create a dependency

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/ednq6m4m50pykl/dependencies' \
--header 'Authorization: ApiKey yourApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sourceColumnId": "enUS",
    "targetColumnId": "viVN"
}'

OUTPUT

{
  "id": "mddn9jyedd43q6y",
  "sourceColumnId": "enUS",
  "targetColumnId": "viVN"
}

To create a dependency.

POST /v1/views/<viewId>/dependencies

Path parameters

Parameters Description Type
viewId View ID String

Request body

Required parameters

Parameters Type Description
sourceColumnId String Source column ID
targetColumnId string Target column ID

Update a dependency

CODE

curl --location --request PUT 'https://api.gridly.com/v1/views/mqnl0vej02l5l8/dependencies/mddn9jyedd43q6y' \
--header 'Authorization: ApiKey yourApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sourceColumnId": "enUS",
    "targetColumnId": "frFR"
}'

OUTPUT

{
  "id": "mddn9jyedd43q6y",
  "sourceColumnId": "enUS",
  "targetColumnId": "frFR"
}

To update a dependency.

PUT /v1/views/<viewId>/dependencies/<id>

Path parameters

Parameters Description Type
viewId View ID String
id Dependency ID String

Request body

Optional parameters

Parameters Type Description
sourceColumnId String Source column ID
targetColumnId String Target column ID

Delete a dependency

CODE

curl --location --request DELETE 'http://api.gridly.com/v1/views/mqnl0vej02l5l8/dependencies/mddn9jyedd43q6y' \
--header 'Authorization: ApiKey yourApiKey'

To delete a dependency.

DELETE /v1/views/<viewId>/dependencies/<id>

Path parameters

Parameters Description Type
viewId View ID string
id Dependency ID string

Record

Pagination

CODE

# Use `page={"offset": 5, "limit": 10}` to get 10 records from the sixth  
curl --location --request GET 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/records?page=%7B%22offset%22%3A+5%2C+%22limit%22%3A+10%7D' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

The list API method uses a page object in the query parameter for the bulk fetching. By default, maximun 100 resources will be returned on each request, if this page object isn’t specified in the request, the first page of resources from 1 to 100 will be returned.

To get the full list of resources that more than 100 items, compares the field X-Total-Count in the response header of the first request, then calculate page param for the next requests.

Value of page has the following format { "offset": <offset>, "limit": <limit> }. Note that this value object need to be URL encoded.

offset

A number to indicate the starting index of the resource that we need to get. It is zero by default.

limit

A limit on the number of resources to be returned. Its default value is 100 and the max is 1000.

Filtering

CODE

# `query={"a3cb4a5dadf2e43ca9bafc437391a0dce": {"contains": "pizza" } }`
curl --location --request GET 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/records?query=%7B%22a3cb4a5dadf2e43ca9bafc437391a0dce%22%3A+%7B%22contains%22%3A+%22pizza%22+%7D+%7D' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

To filter on a API response, use query object in the query params of the HTTP request.

Value of query has the following format { "<columnId>": { "<operator>": <value> } }. Note that this value object need to be URL encoded.

columnId

The ID of the column to be filtered. To filter on predefined columns, details column ID here.

operator

Is one of the following values:

Operator Meaning Supported columns
“=” Equal All
“!=” Not equal All
“<” Less than Number, Date time, Last modified time
“<=” Less than or equal Number, Date time, Last modified time
“>” Greater than Number, Date time, Last modified time
“>=” Greater than or equal Number, Date time, Last modified time
“contains” Contains a string Localization, Single line, Multiple lines, Markdown, Rich text, Files, Reference, Json, Yaml, Html, Formula, Path, Record ID, Last modified by
“startsWith” Starts with a string Localization, Single line, Multiple lines, Markdown, Rich text, Files, Reference, Json, Yaml, Html, Formula, Path, Record ID, Last modified by
“endsWith” Ends with a string Localization, Single line, Multiple lines, Markdown, Rich text, Files, Reference, Json, Yaml, Html, Formula, Path, Record ID, Last modified by
“regexp” Matches a Regular Expression Localization, Single line, Multiple lines, Markdown, Rich text, Files, Reference, Json, Yaml, Html, Formula, Record ID, Last modified by
“notRegexp” Does not match a Regular Expression Localization, Single line, Multiple lines, Markdown, Rich text, Files, Reference, Json, Yaml, Html, Formula, Record ID, Last modified by
“in” Is one of the given values All
“notIn” Is not one of the given values All
“between” Between two given values Number, Date time, Last modified time
“isEmpty” Is empty All
“isNotEmpty” Is not empty All

You can pass many key-value pairs of filters like this:

{ "ingredient": { "contains": "cheese" }, "price": { "<": 42 } }

Sorting

CODE

# `sort={"a3cb4a5dadf2e43ca9bafc437391a0dce": "desc"}`
curl --location --request GET 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/records?sort=%7B%22a3cb4a5dadf2e43ca9bafc437391a0dce%22%3A+%22desc%22%7D' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

To sort the response list, use the sort object in the query params.

Value of sort has the following format { "<columnId>": "<sortDirection>" }. Note that this value object need to be URL encoded.

columnId

The ID of the column to be sorted. To sort on predefined columns, details column ID here.

sortDirection

The direction to sort by. The value can be:

Sort direction Meaning
“asc” Ascending
“desc” Descending

We can pass many key-value pairs like this:

{ "ingredient": "asc", "price": "desc" }

Record resource

Record resource representation

{ "id": string, "cells": [ { "columnId": string, "value": various, "dependencyStatus": string, "sourceStatus": string }, ... ], "path": string }

This table explains each property in the record resource.

Property name Type Description Note
id String Record ID Read-only
cells List List of cells within a record
cells[].columnId String Column ID of a column in a view Read-only
cells[].value Various Value of a cell
cells[].dependencyStatus String Dependency status. Possible values: unset, outOfDate, upToDate
cells[].sourceStatus String Source status. Possible values: unset, doNotTranslate, notReadyForTranslation, readyForTranslation, locked
cells[].referencedIds[] List List of referenced record IDs Read-only
path String Path to folder where the record is stored

“Various” means any type depending on the column. For example: string, number, datetime, etc.

List records

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/records?columnIds=a3cb4a5dadf2e43ca9bafc437391a0dce,a3cb4a5dadf2e43ca9bafc437391a0dce' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
  {
    "id": "me6q2mvj4868l8",
    "cells": [
      {
        "columnId": "v182ye104j8o33",
        "value": "spaghetti"
      },
      {
        "columnId": "em8vw50wzkl111",
        "dependencyStatus": "upToDate",
        "sourceStatus": "readyForTranslation",
        "value": 99
      }
    ],
    "path": "Path Level 1"
  },
  {
    "id": "41wk9m9q0w8mnn",
    "cells": [
      {
        "columnId": "emv2qozw1jn5vo",
        "value": "pizza"
      },
      {
        "columnId": "emv2qjxv3pjo11",
        "dependencyStatus": "outOfDate",
        "sourceStatus": "readyForTranslation",
        "value": 60
      }
    ],
    "path": "Path Level 1/Path Level 2"
  }
]

To list records in a view.

The API returns one page of records at a time. Each page will contain a limit number of records, which is 100 by default. Use pagination to get next pages, use filtering or sorting to format the results.

HTTP Request

GET /v1/views/<viewId>/records?columnIds=<columnID_1>,<columnID_2>&fetchFileOption=<fetchFileOption>&page=<page>&query=<query>&sort=<sort>

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

columnIds optional

Specify data of what columns of view to include in response

fetchFileOption optional

Specify data of file cell in the response

Option Description
id return Gridly file Id. This is a default option.
name return original file name.
all return all file information: Gridly file id, original file name, size & content-type.

page optional

Starting index and number of records. More details pagination here

query optional

Criteria to filter records. More details filtering

sort optional

Order of records. More details sorting here

Response

Returns a list of records in ARRAY if the get succeeded, otherwise, returns an error object if something goes wrong.

Make sure to replace {YOUR_API_KEY} and {VIEW_ID} with yours.

Add records

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/records' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '[
  {
    "id": "Record1",
    "path": "Path Level 1",
    "cells": [
      {
        "columnId": "{COLUMN_ID}",
        "value": "Pasta"
      }
    ]
  }
]'

OUTPUT

[
  {
    "id": "Record1",
    "cells": [
      {
        "columnId": "main_course",
        "value": "Pasta"
      }
    ],
    "path": "Path Level 1"
  }
]

To add new records to a view.

HTTP Request

POST /v1/views/<viewId>/records

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

Request body

A request body has the format of a list and in raw-data. Every object in the list represents a single record resource and has the following format:

{ "id": <value>, "path": <value>, "cells": [ { "columnId": <value>, "value": <value> }, { "columnId": <value>, "value": <value> } ] }

Parameters Type Description
cells List List of cells within a record
cells[].columnId String ID of a column in a view. If a column isn’t specified in the list, an empty value will be added by default.
cells[].value Various Value of a cell. “various” means any type depending on the column’s type, for example: string, number, dateTime, etc.
cells[].dependencyStatus String Dependency status of a cell. Possible values: unset, outOfDate, upToDate. This is only required if you’d like to manually overwrite value set by Gridly.
cells[].sourceStatus String Source status of a cell. Possible values: unset, doNotTranslate, notReadyForTranslation, readyForTranslation, locked.
id String This parameter is optional. This parameter specify record Id of this record.
path String This parameter is optional. This parameter specify path (folder) of this record. Use character / to indicate folder level (e.g Path Level 1/Path Level 2)

Make sure to replace {YOUR_API_KEY}, {VIEW_ID} and {COLUMN_ID} with yours.

Response

Returns a list of added records in ARRAY if the adding succeeded, returns an error object if something goes wrong.

Update records

CODE

curl --location --request PATCH 'https://api.gridly.com/v1/views/{VIEW_ID}/records' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '[
  {
    "id": "{RECORD_ID}",
    "path": "Path Level 1"
    "cells": [
      {
        "columnId": "{COLUMN_ID}",
        "value": "Pasta"
      }
    ]
  }
]'

OUTPUT

[
  {
    "id": "v182ye104j8o33",
    "cells": [
      {
        "columnId": "main_course",
        "value": "Pasta"
      }
    ],
    "path": "Path Level 1"
  }
]

To update existing records of a view.

HTTP Request

PATCH /v1/views/<viewId>/records

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

Request body

A request body has the format of a list and in raw-data. Every object in the list represents a single record resource and has the following format:

{ "id": string, "path": <value>, "cells": [ { "columnId": <value>, "value": <value> } ] }

Parameters Type Description
id String ID of record to be updated
cells List List of cells within a record
cells[].columnId String ID of the column to be updated. If a column isn’t specified in the list, it will be left as they were.
cells[].value Various Value of a cell. “various” means any type depending on the column’s type, for example: string, number, dateTime, etc.
cells[].dependencyStatus String Dependency status of a cell. Possible values: unset, outOfDate, upToDate. This is only required if you’d like to manually overwrite value set by Gridly.
cells[].sourceStatus String Source status of a cell. Possible values: unset, doNotTranslate, notReadyForTranslation, readyForTranslation, locked.
path String This parameter is optional. This parameter specify path (folder) of this record. Use character / to indicate folder level (e.g Path Level 1/Path Level 2)

Make sure to replace {YOUR_API_KEY}, {VIEW_ID}, {RECORD_ID} and {COLUMN_ID} with yours.

Response

Returns a list of updated records in ARRAY if the updating succeeded, return an error object if something goes wrong.

Update a single record

CODE

curl --location --request PATCH '<https://api.gridly.com/v1/views/44e84z0odnl2qm/records/currentRecordId'> \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '{
    "id": "newRecordId"
}
'

OUTPUT

{
  "id": "newRecordId"
  "cells": [
    {
      "columnId": "ingredient",
      "value": "onion"
    }
  ]
}

To update s single record of a view.

HTTP Request

PATCH /v1/views/<viewId>/records/<id>

Path parameters

Parameters Type Description
viewId string View ID
id string Record ID

Request body

Parameters Type Description
id String New record ID
cells List List of cells within a record
cells[].columnId String Column ID of a column in a view
cells[].value Various Value of a cell
cells[].dependencyStatus String Dependency status of a cell. Possible values: unset, outOfDate, upToDate. This is only required if you’d like to manually overwrite value set by Gridly.
cells[].sourceStatus String Source status of a cell. Possible values: unset, doNotTranslate, notReadyForTranslation, readyForTranslation, locked.

Optional parameters

Parameters Type Description Format
path String Path to folder where the record is stored folder1/folder2

Response

Return database data in an object if succeeded. Otherwise, return an error.

Delete records

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/views/{VIEW_ID}/records' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '{
  "ids": [
    "{RECORD_ID_1}",
    "{RECORD_ID_2}"
  ]
}'

To delete existing records of a view.

HTTP Request

DELETE /v1/views/<viewId>/records

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

Request body

Parameters Type Description Required
ids List List of record IDs need to be deleted This is required for unique record grid.
identifiers List List of record Identifiers need to be deleted. Each identifier is combined of Record ID and Path This is required for non-unique record grid.

identifiers

[ { "id" : "string1-1", "path" : "path1" }, { "id" : "string1-2", "path" : "path1" } ]

Make sure to replace {YOUR_API_KEY}, {VIEW_ID} and {RECORD_ID} with yours.

Response

If successful, this method returns an empty response body.

Upload file

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/{VIEW_ID}/files' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--form 'file=@"/Users/john/Photos/pizza.jpg"' \
--form 'recordId="{RECORD_ID}"'
--form 'columnId="{COLUMN_ID}"'

OUTPUT

{
  "id": "v182ye104j8o33.jpg",
  "originalName": "pizza.jpg",
  "contentType": "image/jpeg",
  "size": 150516
}

To upload file to the cell of a view.

HTTP Request

POST /v1/views/<viewId>/files

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

Multipart parameters

file required

Absolute file path of local machine.

recordId required

Id of the record.

columnId required

Id of the column.

Make sure to replace {YOUR_API_KEY}, {VIEW_ID} and {RECORD_ID} and ‘{COLUMN_ID}’ with yours.

Response

If successful, this method returns details of file structure in json format.

Download file

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/{VIEW_ID}/files/541617d3413147b0b365c87aae2b5a47.jpg' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

To download a file from the cell of a view.

HTTP Request

GET /v1/views/<viewId>/files/<id>

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

id required

FileId which was returned by upload file API

Make sure to replace {YOUR_API_KEY}, {VIEW_ID} and {RECORD_ID} with yours.

Response

If successful, this method returns the binary content of the file.

Delete file

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/files?columnId=picture&recordId=v1lxdoj84e0v9o' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey yourApiKey' \
--data-raw '{
  "ids": [
    "xkd13v2wpmo19d.png",
    "1jld6w4o290d85.jpg"
  ]
}'

To delete files to the cell of a view.

HTTP Request

POST /v1/views/<viewId>/files

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

Request parameters

recordId required

Id of the record.

columnId required

Id of the column.

Request body

Parameters Type Description Required
ids List List of file IDs need to be deleted True

Make sure to replace {YOUR_API_KEY}, {VIEW_ID} and {RECORD_ID} and ‘{COLUMN_ID}’ with yours.

Response

If successful, this method returns an empty response body.

Batch upload

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/{VIEW_ID}/files/zip' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--form 'file=@"/Users/john/Photos/pictures.zip"' \
--form 'columnId="{COLUMN_ID}"' \
--form 'fileMappings="{\"{RECORD_ID1}\":[\"rungtramtrasu.jpeg\",\"thotnot.jpeg\"],\"{RECORD_ID2}\":[\"chonoi.jpeg\"]}"'

OUTPUT

[
    {
        "id": "record1",
        "cells": [
            {
                "columnId": "file",
                "value": [
                    "3jjjljojy4q8q2q.jpeg",
                    "xnnn8nle5xldddd.jpeg"
                ]
            }
        ]
    },
    {
        "id": "record2",
        "cells": [
            {
                "columnId": "file",
                "value": [
                    "4555o5z59dv0p6p.jpeg"
                ]
            }
        ]
    }
]

To batch upload files to the cells of a view.

HTTP Request

POST /v1/views/<viewId>/files/zip

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

Multipart parameters

Parameters Type Description Required
file .zip The zip file that contains files you want to upload into Gridly.The maximum file size is 100MB. True
columnId String The column id you want to upload files. True
fileMappings json JSON object to instruct how to map each file with corresponding record. Note: You can map multiple files for the same record. True

fileMappings

{ "record1": [ "rungtramtrasu.jpeg", "thotnot.jpeg" ], "record2": [ "chonoi.jpeg" ] }

Make sure to replace {YOUR_API_KEY}, {VIEW_ID} and ‘{COLUMN_ID}’ with yours.

Response

Returns a list of updated records in ARRAY if the updating succeeded, return an error object if something goes wrong.

Get record history

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/records/3zmv578sj6mq6/histories' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
    {
        "lastModifiedBy": "sample@gridly.com",
        "lastModifiedTime": "2023-05-25T03:27:16Z",
        "path": "Path Level 1",
        "cells":
        [
            {
                "columnId": "v182ye104j8o33",
                "value": "spaghetti"
            },
            {
                "columnId": "em8vw50wzkl111",
                "dependencyStatus": "upToDate",
                "sourceStatus": "readyForTranslation",
                "value": 99
            }
        ]
    },
    {
        "lastModifiedBy": "sample@gridly.com",
        "lastModifiedTime": "2023-05-25T02:15:55Z",
        "path": "Path Level 1/Path Level 2",
        "cells":
        [
            {
                "columnId": "v182ye104j8o33",
                "value": "pizza"
            },
            {
                "columnId": "em8vw50wzkl111",
                "dependencyStatus": "outOfDate",
                "sourceStatus": "readyForTranslation",
                "value": 60
            }
        ]
    }
]

To get record histories of a record in a view.

The API returns one page of record histories at a time. Each page will contain a limit number of record histories, which is 100 by default. Use pagination to get next pages.

HTTP Request

GET /v1/views/<viewId>/records/<recordId>/histories?page=<page>

Parameters

viewId required

ID of the view. It can be found in the API quick start right panel of your Gridly Dashboard.

recordId required

Id of the record to getting history

page optional

Starting index and number of record histories. More details pagination here

Response

Returns a list of record histories in ARRAY if the get succeeded, otherwise, returns an error object if something goes wrong.

Make sure to replace {YOUR_API_KEY}, {VIEW_ID} and {RECORD_ID} with yours.

Branch

List branches

CODE

curl --location --request GET 'https://api.gridly.com/v1/branches?gridId=3xep36emk4j1dq' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
  {
    "id": "v182ye104j8o33",
    "name": "Pizza"
  },
  {
    "id": "me6q2mvj4868l8",
    "name": "Burger"
  }
]

To list branches of a grid.

GET /v1/branches

Parameters

gridId required

ID of a grid.

Response

Return a list of branches in an array if succeeded. Otherwise, return an error.

Retrieve a branch

CODE

curl --location --request GET 'https://api.gridly.com/v1/branches/em8vw50wzkl111' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
  "id": "em8vw50wzkl111",
  "columns": [
    {
      "id": "ingredient",
      "name": "Ingredient",
      "type": "multipleLines"
    },
    {
      "id": "price",
      "name": "Price",
      "type": "number"
    }
  ]
}

To retrieve a branch.

HTTP Request

GET /v1/branches/<id>

Response

Return branch data in an object if succeeded. Otherwise, return an error.

Create a branch

CODE

curl --location --request POST 'https://api.gridly.com/v1/branches?branchId=xk0d5xz8j4xj6v' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-type: application/json' \
--data-raw '{
   "name": "Food"
}'

OUTPUT

{
  "id": "410nzk2op1zedp",
  "defaultAccessViewId": "me35v9mqd0e93y",
  "name": "Food"
}

To create a branch in a grid.

HTTP Request

POST /v1/branches

Parameters

branchId required

ID of a source branch.

Request body

Parameters Type Description Required
name String Name of the branch that you want to create TRUE

Response

Return branch data in an object if succeeded. Otherwise, return an error.

Delete a branch

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/branches/410nzk2op1zedp' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

To delete a branch.

HTTP Request

DELETE /v1/branches/<id>

Response

If successful, this method returns an empty response body.

Merge a branch

CODE

curl --location --request POST 'https://api.gridly.com/v1/branches/em8vw50wzkl111/merge?destinationBranchId=xk0d5xz8j4xj6v&mergeRecordOptions=add,update,delete,override' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-type: application/json'

OUTPUT

{
  "id": "410nzk2op1zedp",
  "status": "running"
}

To merge a branch to the branch.

HTTP Request

POST /v1/branches/<branchId>/merge

Request parameters

Parameters Type Description Required
destinationBranchId String ID of the branch to merge over TRUE

Request body

Parameters Type Description Required
mergeRecordOptions Array List of options to instruct how records are merged TRUE
mergeRecordConflicts Array List of instructions to indicate how conflicted cell will be handled FALSE
query JSON Object Criteria to filter records FALSE
useLastMergeResolve Boolean Instruct to incorporate with last merge conflict resolve if applicable FALSE

mergeRecordOptions

Option Description
add Merge new records from branch to destination branch
delete Merge deleted records from branch to destination branch
update Merge updated record from branch to destination branch. If the same cell was updated on both branches, the change of source branch’s cell will be ignored if override option is not specified.
override Work with update option to instruct if the same cell was updated on both branch and grid, the change of source branch cell will be merged.

mergeRecordConflicts (optional)

[ { "recordId": "string1", "path": "folder 1", "cells": [ { "columnId": "column1", "option": "source" }, { "columnId": "column2", "option": "source" } ] } ]

Parameters Type Description
recordId String Record ID
path String Path of Record. This is required if Grid is non-unique record type
cells List List of cells in record
cells[].columnId String Column ID
cells[].option String Instruction to pick value to merge if status of cell is conflicted. Valid values: source: pick value from source branch, destination: pick value from destination branch

query (optional). More details filtering

{ "_recordId": { "in": [ "string1", "string2" ] }, "column1": { "=": "filter value" } }

Response

Return asynchronous task of the request with id and status. To retrieve the latest status, check task api.

Generate diffcheck

CODE

curl --location --request POST 'https://api.gridly.com/v1/branches/diffcheck?sourceViewId=2s871u1pnnoi7&destinationViewId=2s871nsbi225m' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-type: application/json'

OUTPUT

{
  "id": "8mrsubmmsi5so",
  "status": "running"
}

To generate diffcheck snapshot between two branches.

HTTP Request

POST /v1/branches/diffcheck

Request parameters

Parameters Type Description Required
sourceViewId String View of source branch TRUE
destinationViewId String View of destination branch TRUE

Response

Return asynchronous task of the request with id and status. This task ID is used to retrieve diffcheck record once the operation is completed. Refer to task api and get-diffcheck-record api for more.

Get diffcheck record

CODE

curl --location --request GET 'https://api.gridly.com/v1/tasks/6ott27mj1plub' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
    {
        "id": "STRING_1",
        "status": "updated",
        "cells": [
            {
                "status": "unchanged",
                "columnId": "_recordId",
                "sourceValue": "STRING_1",
                "destinationValue": "STRING_1"
            },
            {
                "sourceSourceStatus": "readyForTranslation",
                "destinationSourceStatus": "readyForTranslation",
                "status": "ahead",
                "columnId": "enUS",
                "sourceValue": "He went back to the video to see what had been recorded and was shocked",
                "destinationValue": "He went back to the video to see what had been recorded and was shocked at what he saw"
            },
            {
                "sourceDependencyStatus": "outOfDate",
                "destinationDependencyStatus": "outOfDate",
                "status": "unchanged",
                "columnId": "vi",
                "sourceValue": "Anh ấy quay lại video để xem những gì đã được ghi lại và bị sốc trước những gì anh ấy thấy.",
                "destinationValue": "Anh ấy quay lại video để xem những gì đã được ghi lại và bị sốc trước những gì anh ấy thấy."
            }
        ],
        "lastModifiedBy": "tn@localizedirect.com",
        "lastModifiedTime": "2024-03-20T04:55:46Z"
    }
]

To get diffcheck records

HTTP Request

GET /v1/branches/diffcheck/{taskId}

Path parameters

Parameters Type Description
taskId String Task ID from generating diffcheck

Request parameters (optional)

Parameters Type Description
mergeRecordOptions List List of record option. Default add, update, delete, override
query JSON Object Criteria to filter records. More details filtering here
page JSON Object Starting index and number of records. More details sorting here

Response

List of diffcheck records. This table explains each property in the record resource.

Field Type Description
id String Record ID
path String Path to folder where record is stored
status String Status of diffcheck record. It has either of the following values: added indicates record will be added to destination branch, updated indicates record will be updated to existing records in destination branch, deleted indicates record will be deleted from destination branch
cells List List of cell within a record
cells[].columnId String Column ID
cells[].status String Status of diffcheck cell. It has either of the following values: ahead indicates cell is updated on source branch, conflicted indicates cell is updated in both source and destination branch, behind indicates cell is updated on destination branch, unchanged indicates cell is not changed
cells[].sourceValue Various Value of cell in source branch
cells[].destinationValue Various Value of cell in destination branch
cells[].sourceDependencyStatus String Dependency status of cell in source branch
cells[].destinationDependencyStatus String Dependency status of cell in destination branch
cells[].sourceSourceStatus String Source status of cell in source branch
cells[].destinationSourceStatus String Source status of cell in destination branch

Task

Retrieve a task

CODE

curl --location --request GET 'https://api.gridly.com/v1/tasks/em8vw50wzkl111' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
  "id": "em8vw50wzkl111",
  "status": "successful"
}

To retrieve an existing task

HTTP Request

GET /v1/tasks/<id>

Response

Return task data of a task if succeeded. Otherwise, return an error.

Path

Create paths

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/paths' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '{
    "parentPath": "Movies",
    "paths": [
      "2022/Black Adam",
      "2023/Guardians of galaxy V3"
    ]
  }'

OUTPUT

{
  "paths": [
    "Movies/2022/Black Adam",
    "Movies/2023/Guardians of galaxy V3"
  ]
}

To create paths

HTTP Request

POST /v1/views/<viewId>/paths

Path parameters

Parameters Description Type
viewId View ID String

Request body

Required parameters

Parameters Type Description
paths List List of paths

Optional parameters

Parameters Type Description
parentPath String Parent path

Update the leaf folder in the path

CODE

curl --location --request PUT 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/paths/Movies%2F2022%2FBlack%20Adam' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '{
  "newName": "White Adam"
}'

OUTPUT

{
  "path": "Movies/2022/White Adam"
}

To update the leaf folder in the path

HTTP Request

PUT /v1/views/<viewId>/paths/<path>

Path parameters

Parameters Description Type
viewId View ID String
path Path String

Request body

Required parameters

Parameters Type Description
newName String New folder name

Move paths

CODE

curl --location --request POST 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/paths/moves' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '{
  "fromParentPath": "Movies",
  "toParentPath": "Games",
  "names": ["2022", "2023"]
}'

OUTPUT

{
    "paths": [
        "Games/2022",
        "Games/2023"
    ]
}

To move paths

HTTP Request

POST /v1/views/<viewId>/paths/moves

Path parameters

Parameters Description Type
viewId View ID String

Request body

Required parameters

Parameters Type Description
fromParentPath String New folder name
toParentPath String New folder name
names List of string Child folders to move

Delete paths

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/paths' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '{
    "parentPath": "Movies",
    "paths": [
      "2022/Black Adam",
      "2023/Guardians of galaxy V3"
    ]
  }'

To delete paths

HTTP Request

DELETE /v1/views/<viewId>/paths

Path parameters

Parameters Description Type
viewId View ID String

Request body

Required parameters

Parameters Type Description
paths List List of paths

Get path tree

CODE

curl --location --request GET 'https://api.gridly.com/v1/views/v1v9jwwk1lwnkz/paths/tree?rootPath=Movies' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
    {
        "parentPath": "Movies",
        "name": "2022",
        "children": [
            {
                "parentPath": "2022", 
                "name": "Black Adam"
            }
        ]
    },
    {
        "parentPath": "Movies",
        "name": "2023",
        "children": [
            {
                "parentPath": "2023",
                "name": "Guardians of galaxy V3"
            }
        ]
    }
]

To get path in tree structure

HTTP Request

GET /v1/views/<viewId>/paths/tree?rootPath=

Path parameters

Parameters Description Type
viewId View ID String

Query parameters

Parameters Description Type
rootPath Root path String

Glossary

Glossary resource

Glossary resource representation

{ "id": string, "name": string, "description": string, "langs": list of string, "projects": [ { "projectId": 123 }, { "projectId": 456, "databaseIds": ["abc", "def"] } ] }

This table explains each property in the glossary resource.

Property name Type Description Note
id string Glossary ID Read-only
name string Glossary name
description string Description
langs list List of language codes
projects list Projects/databases which are applied to the glossary

List glossaries

CODE

curl --location --request GET 'https://api.gridly.com/v1/glossaries' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
    {
        "id": "123",
        "name": "Glossary 1",
        "description": "Use for game 1",
        "langs": ["enUS", "frFR"]
        "projects": [
           {
               "projectId": 123,
               "databaseIds": [] // all database
           },
           {
               "projectId": 567,
               "databaseIds": ["qwerty", "yuiop"]
           }
        ]
    },
    {
        "id": "456",
        "name": "Glossary 2",
        "description": "Use for movie 1",
        "langs": ["enUS", "frFR"]
        "projects": [
           {
               "projectId": 123,
               "databaseIds": ["yhnbtt", "pokmjui"]
           }
        ]
    }
]

To list glossary of a company.

HTTP Request

GET /v1/glossaries

Response

Return a list of glossaries in an array if succeeded. Otherwise, return an error.

Retrieve a glossary

CODE

curl --location --request GET 'https://api.gridly.com/v1/glossaries/123' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
   "id": "123",
   "name": "Glossary 1",
   "description": "Use for game 1",
   "langs": ["enUS", "frFR"]
   "projects": [
      {
          "projectId": 123
      }
    ]
}

To retrieve a glossary.

HTTP Request

GET /v1/glossaries/<id>

Path parameters

Parameters Description Type
id Glossary ID string

Response

Return glossary data in object if succeeded. Otherwise, return an error.

Create glossary

CODE

curl --location --request POST 'https://api.gridly.com/v1/glossaries' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Glossary 1",
    "description": "Sample Glossary",
    "langs": ["viVN", "enUS", "frFR"]
    "projects": [{
        "projectId": 123
    }]
}'

OUTPUT

{
    "id": "ej4kYLW2QC",
    "name": "Glossary 1",
    "description": "Sample Glossary",
    "langs": ["viVN", "enUS", "frFR"]
    "projects": [{
        "projectId": 123
    }]
}

To create a glossray.

POST /v1/glossaries

Request body

Parameters Type Description Required
name string Project name true
description string Description false
langs list List of language codes true
projects list Projects/databases which are applied to the glossary false

Response

Return glossary data in an object if succeeded. Otherwise, return an error.

Update a glossary

CODE

curl --location --request PUT 'https://api.gridly.com/v1/glossaries/123' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Glossary 1",
    "description": "Sample Glossary",
    "langs": ["enUS", "frFR", "jpJP"]
    "projects": [{
        "projectId": 123
    }]
}'

OUTPUT

{
    "id": "ej4kYLW2QC",
    "name": "Glossary 1",
    "description": "Sample Glossary",
    "langs": ["enUS", "frFR", "jpJP"]
    "projects": [{
        "projectId": 123
    }]
}

To update a glossray.

PUT /v1/glossaries/<id>

Path parameters

Parameters Description Type
id Glossary ID string

Request body

Parameters Type Description Require
name string Project name true
description string Description false
langs list List of language codes true
projects list Projects/databases which are applied to the glossary false

Response

Return glossary data in an object if succeeded. Otherwise, return an error.

Delete a glossary

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/glossaries/123' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

To delete a glossray.

DELETE /v1/glossaries/<id>

Path parameters

Parameters Description Type
id Glossary ID string

Import glossary

CODE

curl --location --request POST 'https://api.gridly.com/v1/glossaries/123/import' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--form 'file=@"/Users/john/game1.csv"'

To import file.

POST /v1/glossaries/<id>/import

Path parameters

Parameters Description Type
id Glossary ID string

Request body

Parameters Type Description Require
file file Updating csv file or tbx file (File Binary) true

Response

204 No content

Export glossary

CODE

curl --location --request GET 'https://api.gridly.com/v1/glossaries/123/export?format=csv&langs=enUS,viVN&fields=conceptId&fields=termId' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \

OUTPUT

File content

To export data from a glossary.

HTTP Request

GET /v1/glossaries/<id>/export

Request parameters

Parameters Type Description Required
format string Export format: tbx, csv false
langs List of string Language codes to export true
fields List of string Additional fields to export, use for csv format only. available fields: conceptId, termId, partOfSpeech, grammaticalGender, grammaticalNumber, forbidden, preferred, exactMatch, status, caseSensitive, createdBy, createdAt, lastModifiedBy, lastModifiedAt, termType. false

Response

File data

Translation Memory

Translation Memory (TM) resource

Translation memory (TM) resource representation

{ "id": "q6zmv4GLPl", "projectIds": [1,3], "isDisabled": false, "name": "Sample TM", "description": "Sample TM", "fuzzyMatch": true, "isPausedConsuming": true, "populateTranslationStatus": "unset", }

This table explains each property in the TM resource.

Property name Type Description Note
id string TM ID Read-only
name string TM name
description string Description
projectIds list Projects which are applied to the TM
isDisabled boolean Whether the TM is disabled or not
fuzzyMatch boolean Whether fuzzy matching is applied
isPausedConsuming boolean If switched off, content from new imports or updated target cell content will not be added to the TM.
populateTranslationStatus string When a TM match is found and inserted into the target cell, this status will be applied. Possible value is: upToDate, outOfDate, unset

List TMs

CODE

curl --location --request GET 'https://api.gridly.com/v1/transmems' \ 
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

[
    {
        "id": "wGYbdl8SRq",
        "projectIds": [],
        "isDisabled": false,
        "name": "DefaultTM",
        "description": "Default TM, created on demand",
        "fuzzyMatch": true,
        "isPausedConsuming": true,
        "populateTranslationStatus": "outOfDate",
    },
    {
        "id": "k3orn8VbEF",
        "projectIds": [1],
        "isDisabled": false,
        "name": "Sample TM",
        "description": "Sample TM",
        "fuzzyMatch": false,
        "isPausedConsuming": false,
        "populateTranslationStatus": "upToDate",
    },
    {
        "id": "q6zmv4GLPl",
        "projectIds": [2,3],
        "isDisabled": false,
        "name": "New TM",
        "fuzzyMatch": true,
        "isPausedConsuming": true,
        "populateTranslationStatus": "unset",
    }
]

To list translation memories of a company.

HTTP Request

GET /v1/transmems

Request parameters

Parameters Type Description Required
projectId number Project Id false

Response

Return a list of translation memories in an array if succeeded. Otherwise, return an error.

Retrieve a TM

CODE

curl --location --request GET 'https://api.gridly.com/v1/transmems/q6zmv4GLPl' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

OUTPUT

{
    "id": "ej4kYLW2QC",
    "projectIds": [
        123
    ],
    "isDisabled": false,
    "name": "Sample TM",
    "description": "Sample TM",
    "fuzzyMatch": false,
    "isPausedConsuming": false,
    "populateTranslationStatus": "upToDate",
}

To retrieve a translation memory.

HTTP Request

GET /v1/transmems/<id>

Path parameters

Parameters Description Type
id TM ID string

Response

Return TM data in object if succeeded. Otherwise, return an error.

Create TM

CODE

curl --location --request POST 'https://api.gridly.com/v1/transmems' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Sample TM",
    "description": "Sample TM",
    "projectIds": [123],
    "fuzzyMatch": true,
    "isDisabled": false
}'

OUTPUT

{
    "id": "ej4kYLW2QC",
    "projectIds": [
        123
    ],
    "isDisabled": false,
    "name": "Sample TM",
    "description": "Sample TM",
    "fuzzyMatch": false,
    "isPausedConsuming": false,
    "populateTranslationStatus": "upToDate",
}

To create a TM.

POST /v1/transmems

Request body

Property Parameters Type Description Note
name string TM name
description string Description
projectIds list Projects which are applied to the TM
isDisabled boolean Whether the TM is disabled or not
fuzzyMatch boolean Whether fuzzy matching is applied
isPausedConsuming boolean Whether the TM is paused consuming data
populateTranslationStatus string Possible value is: upToDate, outOfDate, unset

Response

Return TM data in an object if succeeded. Otherwise, return an error.

Update a TM

CODE

curl --location --request PUT 'https://api.gridly.com/v1/transmems/j4OmmEo7x9' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "projectIds": [],
    "isDisabled": true,
    "name": "Update TM",
    "fuzzyMatch": true,
    "isPausedConsuming": false,
    "populateTranslationStatus": "outOfDate",
}'

OUTPUT

{
    "id": "j4OmmEo7x9",
    "projectIds": [],
    "isDisabled": true,
    "name": "Update TM",
    "fuzzyMatch": true,
    "isPausedConsuming": false,
    "populateTranslationStatus": "outOfDate",
}

To update a TM.

PUT /v1/transmems/<id>

Path parameters

Parameters Description Type
id TM ID string

Request body

Property Parameters Type Description Note
name string TM name
description string Description
projectIds list Projects which are applied to the TM
isDisabled boolean Whether the TM is disabled or not
fuzzyMatch boolean Whether fuzzy matching is applied
isPausedConsuming boolean Whether the TM is paused consuming data
populateTranslationStatus string Possible value is: upToDate, outOfDate, unset

Response

Return TM data in an object if succeeded. Otherwise, return an error.

Delete a TM

CODE

curl --location --request DELETE 'https://api.gridly.com/v1/transmems/j4OmmEo7x9' \
--header 'Authorization: ApiKey {YOUR_API_KEY}'

To delete a TM.

DELETE /v1/transmems/<id>

Path parameters

Parameters Description Type
id TM ID string

Import TM

CODE

curl --location --request POST 'https://api.gridly.com/v1/transmems/cpX3HLwKqX/import' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--form 'file=@"/Users/john/UpdateTM.tmx"'

To import file.

POST /v1/transmems/<id>/import

Path parameters

Parameters Description Type
id TM ID string

Request body

Parameters Type Description Require
file file tmx file (File Binary) true

Upload TM

CODE

curl --location --request POST 'https://api.gridly.com/v1/transmems/upload' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--form 'file=@"/Users/john/WS/Starter_TM.tmx"'

OUTPUT

{
    "id": "PDLiivNyF3",
    "projectIds": [],
    "isDisabled": false,
    "name": "Starter_TM",
    "fuzzyMatch": false,
    "isPausedConsuming": false,
    "populateTranslationStatus": "upToDate",
}

To create a TM from file.

POST /v1/transmems/<id>/upload

Path parameters

Parameters Description Type
id TM ID string

Request body

Parameters Type Description Require
file file tmx file (File Binary) true

Export TM

CODE

curl --location --request GET 'https://api.gridly.com/v1/transmems/DRcdU094yI/export?format=csv&sourceLang=viVN&targetLangs=enUS&targetLangs=esES' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \

OUTPUT

File content

To export data from a TM.

HTTP Request

GET /v1/transmems/<id>/export

Request parameters

Parameters Type Description Required
format string Export format: tmx, csv, xlsx false
targetLangs List of string Target language codes to export true
sourceLang string Target languages to export false

Response

File data

curl