Introduction
Welcome to the Gridly API Document. You can use our Gridly API endpoints to access your database.
The 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 dark 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}'
The Gridly API uses
Authorization: ApiKey {YOUR_API_KEY}
To get your API key, access your Gridly Dashboard, then select a Grid View and you can find the key in
Make sure to replace
{YOUR_API_KEY}
and{VIEW_ID}
with yours.
Errors
Gridly uses conventional HTTP response codes to indicate the success or failure of an API request.
In general: Codes in the 2xx
range indicate success. Codes in the 4xx
range indicate an user error that failed given the information provided. Codes in the 5xx
range indicate an error with Gridly’s servers.
An error response will return a JSON body that contains errors
and message
fields. Those will provide specific error condition and human-readable message to identify what caused the error.
Success code
200 OK
Request executed successfully
User error codes
400 Bad Request
The request was unacceptable, often due to missing a required parameter or JSON request body fails to be parsed.
Bad Request response example:
{
"errors": [
{
"code": "invalid",
"field": "pageRequest",
"message": "Unable to parse \"page\".",
"resource": "database"
}
],
"message": "Unable to parse \"page\"."
}
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
Not Found response example:
{
"message" : "Validation failed.",
"errors" : [ {
"resource" : "view",
"field" : "id",
"code" : "missing",
"message" : "View \"NezkWk3VEL\" could not be found."
} ]
}
405 Method Not Allowed
The method received in the request is known by the origin server but not supported by the target 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
This error shows up when validation fails on any field of request parameters or request body.
5xxx Server Errors
Something went wrong on Gridly server. The server encountered an unexpected condition that prevented it from fulfilling the request.
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 methods. For instance, you can list records.
These list API methods use a
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 { "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
Value of { "<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
Value of { "<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
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.
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
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
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 |
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
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 |
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
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
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
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.