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.

Query

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/{VIEW_ID}/records?page=%7B%22offset%22%3A+5%2C+%22limit%22%3A+10%7D' \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

All top-level API resources have support for bulk fetches via “list” API method. For instance, you can list records.

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/{VIEW_ID}/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.

operator

Is one of the following values:

Operator	Meaning
“=”	Equal
“!=”	Not equal
“<”	Less than
“<=”	Less than or equal
“>”	Greater than
“>=”	Greater than or equal
“contains”	Contains a string
“startsWith”	Starts with a string
“endsWith”	Ends with a string
“regex”	Matches a Regular Expression
“notRegex”	Does not match a Regular Expression
“in”	Is one of the given values
“between”	Between two given values
“isEmpty”	Is empty
“isNotEmpty”	Is not empty

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/{VIEW_ID}/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.

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" }

View

Retrieve a view

CODE

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

OUTPUT

{
  "columns": [
    {
      "id": "sc055f8cb6fcd4585942bee9b25756aa8",
      "type": "multipleLines"
    },
    {
      "id": "yf85efee708d2477eb063edce23cbcf08",
      "type": "multipleLines"
    },
    {
      "id": "44db1e25afe049b09ef1c3d13d06d81a",
      "type": "datetime"
    }
  ],
  "id": "NezkWk3VEL"
}

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/<viewId>

Path parameters

viewId required

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

Response

Returns a view data in OBJECT 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.

Import

CODE

curl --location --request POST '<https://api.gridly.com/v1/views/{VIEW_ID}/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/<viewId>/import

Parameter

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
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, "columnMappings": [ { "columnId": "column1", "fileColumnIndex": 0 } ] }

Parameters	Type	Description
withHeader	boolean	Indicate the file has a header or not
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/{VIEW_ID}/export'> \
  --header 'Authorization: ApiKey {YOUR_API_KEY}'

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

HTTP Request

GET /v1/views/<viewId>/export

Parameter

viewId required

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

Response

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

Record

List records

CODE

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

OUTPUT

[
  {
    "id": "60f074ebd99a4b2d84e4081b14117174",
    "cells": [
      {
        "columnId": "a3cb4a5dadf2e43ca9bafc437391a0dce",
        "value": "spaghetti"
      },
      {
        "columnId": "ec2e1839448e487ab825056fcc2bfbea",
        "dependencyStatus": "upToDate",
        "value": 99
      }
    ],
    "path": "Path Level 1"
  },
  {
    "id": "5c9390594f29416bbe278023ac7c89a2",
    "cells": [
      {
        "columnId": "a3cb4a5dadf2e43ca9bafc437391a0dce",
        "value": "pizza"
      }
      {
        "columnId": "ec2e1839448e487ab825056fcc2bfbea",
        "dependencyStatus": "outOfDate"
        "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>&page=<page>&query=<query>&sort=<sort>

Path 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

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/{VIEW_ID}/records' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--data-raw '[
  {
    "path": "Path Level 1",
    "cells": [
      {
        "columnId": "{COLUMN_ID}",
        "value": "Pasta"
      }
    ]
  }
]'

OUTPUT

[
  {
    "id": "444633bcc8ec47d18f251d89cda36bd9",
    "cells": [
      {
        "columnId": "a3cb4a5dadf2e43ca9bafc437391a0dce",
        "value": "Pasta"
      }
    ],
    "path": "Path Level 1"
  }
]

To add new records to a View

HTTP Request

POST /v1/views/<viewId>/records

Path 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:

{ "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.
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": "444633bcc8ec47d18f251d89cda36bd9",
    "cells": [
      {
        "columnId": "a3cb4a5dadf2e43ca9bafc437391a0dce",
        "value": "Pasta"
      }
    ],
    "path": "Path Level 1"
  }
]

To update existing records of a View

HTTP Request

PATCH /v1/views/<viewId>/records

Path 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.
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.

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

Path 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	True

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}/records/{RECORD_ID}/files' \
--header 'Authorization: ApiKey {YOUR_API_KEY}' \
--form 'file=@"/Users/john/Photos/pizza.jpg"' \
--form 'columnId="{COLUMN_ID}"'

OUTPUT

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

To upload file to the cell of a View

HTTP Request

POST /v1/views/<viewId>/records/<recordId>/files

Path 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.

Multipart parameters

file required

Absolute file path of local machine.

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 file from the cell of a View

HTTP Request

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

Path parameters

viewId required

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

fileId 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.