Skip to content

URL

The URL to use to do API queries is https://api.spreadsheetdb.io

Authentication

The API uses HTTP basic authentication with your account email and your password. All API methods require an authentication.

Requests

Requests sending a body (POST and PATCH) are expected to send JSON. The `Content-Type` header must be set to `application/json`.

The maximum allowed size for the body is 1MB and the maximum number of cells for a spreadsheet is 500.

Responses

Unless specified otherwise, responses are in JSON, the `Content-Type` header is set to `application/json`.

On error (HTTP codes 4xx and 5xx), the response body will contain more information, including an error code. See the errors documentation for a complete list.

Cell JSON object

Cells are the main component of a spreadsheet. A cell is a JSON object with the following description:

Field Type Mandatory Description
value string yes The cell value. A value starting by '=' indicates a formula that will be computed. Otherwise it is just a static text.
filter string no The filter applied to the cell.

Example:

{
    "value": "=ROUND(SUM(deal.profit) / COUNT(deal.profit), 2)",
    "filter": "deal.type = \"subscription\""
}

Note: a cell can only be a simple string containing the value. The cell =1+1 is the same as {"value": "=1+1"}.

POST /spreadsheet

Creates a spreadsheet.

Request JSON object

Field Type Mandatory Description
name string yes The unique spreadsheet name, can contain only alphanumerical characters, hyphens and underscores.
cells object yes Cells that will compose the spreadsheet. Keys are cell coordinates (either x,y or A1 format) and values are cells.
rowFilters object no Filters to apply to rows. The key is the row number, the value is the filter.
columnFilters object no Filters to apply to columns. The key is the column number, the value is the filter.

Response JSON object

Field Type Always present Description
success boolean yes true if the spreadsheet has been added, false otherwise.
error string no Error code, only present if the request failed.
errorText string no Error text that can add explainations to the error code. Can be present if the request failed.
{ "name": "example", "cells": { "0,0": "Server average load", "0,1": { "value": "=ROUND(AVG(monitoring.cpu.load), 2)", "filter": "monitoring.server == \"ninja\"" } }, "rowFilters": { "0": "monitoring.production == true" } }
{ "succes": true }

GET /api/spreadsheet

List all the spreadsheets of the account.

Response JSON object

Field Type Always present Description
success boolean yes true if the spreadsheet has been added, false otherwise.
error string no Error code, only present if the request failed.
errorText string no Error text that can add explainations to the error code. Can be present if the request failed.
spreadsheets array of objects no The spreadsheet list, not present in error case.
{ "success": true, "spreadsheets": [ { "name": "billing", "key": "OIYgLVjChdGJHb4RUEyLXFbDHHR2j6FYEt4geeIlifVPhPx1kV", "creationDate": 1476868956505 }, { "name": "clients", "key": "2wHBAZdQ3GiRkzxXIZWDu0xOqo45CSBve9WEY0lRxuzHTWvsLh", "creationDate": 1476869971169 }, { "name": "stocks", "key": "V58jJoyEj0nKlrJ8WyZ8fmsETcrfu2ngYlpyAN3JDgkPyUOliD", "creationDate": 1476912458964 } ] }

GET /spreadsheet/:name

Computes a spreadsheet.

Query parameters

Field Description Default value
filter Filter to apply to the whole spreadsheet. none
notation Defines the notation used to display cell coordinates in the spreadsheet. Possible values are `A1` or `x,y`. x,y
key Spreadsheet key. HTTP authentication is not needed when this parameter is specified. none

Response JSON object

Field Type Always present Description
success boolean yes true if the spreadsheet has been added, false otherwise.
error string no Error code, only present if the request failed.
errorText string no Error text that can add explainations to the error code. Can be present if the request failed.
spreadsheet object no The spreadsheet content and results. On error case, this field may be present but containing only the cells content and missing the computed results.
{ "success": true, "spreadsheet": { "creationDate": 1476868956505, "key": "xJqpaviTRqtfUvD4hXS7ck0cEImjvOpSoG8o1g7IwrNgMgbU4T", "name": "example", "cells": { "A1": { "value": "=1+1", "result": 2 } } } }

GET /spreadsheet/:name.csv

Computes a spreadsheet and exports it in CSV. Like GET /spreadsheet/:name but with ".csv" appened to the URL, the parameters stay the same. The response Content-Type is text/csv.

GET /spreadsheet/:name/:cell

Computes a spreadsheet cell. The cell coordinates can be in A1 or x,y format.

Query parameters

Field Description Default value
filter Filter to apply to the cell. none

Response JSON object

Field Type Always present Description
success boolean yes true if the spreadsheet has been added, false otherwise.
error string no Error code, only present if the request failed.
errorText string no Error text that can add explainations to the error code. Can be present if the request failed.
cell object no The cell content and result. On error case, this field may be present but containing only the cell content and missing the computed result.
{ "success": true, "cell": { "value": "=1+1", "result": 2 } }

PATCH /api/spreadsheet/:name

Updates a spreadsheet. Each new cell will be added to the spreadsheet, or replace the previous one if it existed. Setting a cell value to an empty string will delete said cell.

Request JSON object

Field Type Mandatory Description
name string no The unique spreadsheet name, can contain only alphanumerical characters, hyphens and underscores.
cells object no Cells to add or update.
rowFilters object no Filters to apply to rows. The key is the row number, the value is the filter.
columnFilters object no Filters to apply to columns. The key is the column number, the value is the filter.

Response JSON object

Field Type Always present Description
success boolean yes true if the spreadsheet has been updated, false otherwise.
error string no Error code, only present if the request failed.
errorText string no Error text that can add explainations to the error code. Can be present if the request failed.
{ "cells": { "0,1": "=2+2" } }
{ "success": true }

DELETE /spreadsheet/:name

Deletes a spreadsheet.

Response JSON object

Field Type Always present Description
success boolean yes true if the spreadsheet has been added, false otherwise.
error string no Error code, only present if the request failed.
errorText string no Error text that can add explainations to the error code. Can be present if the request failed.
{ "success": true }

POST /record

Adds one or several records.

Request JSON object

Field Type Mandatory Description
Field string yes The key that identifies the record.
data object yes The schema-free record data.

Note: you can use an array of objects to insert multiple records at once, as long as your body does not exceed the 1MB limit. This will count as one call to POST /record.

Response JSON object

Field Type Always present Description
success boolean yes true if the spreadsheet has been added, false otherwise.
error string no Error code, only present if the request failed.
errorText string no Error text that can add explainations to the error code. Can be present if the request failed.
{ "key": "song", "data": { "name": "Blowin in the wind", "artist": "Bob Dylan", "album": "The freewheelin Bob Dylan", "year": 1963, "duration": 168 } }
{ "succes": true }
[{ "key": "song", "data": { "name": "Blowin' in the wind", "artist": "Bob Dylan", "album": "The freewheelin Bob Dylan", "year": 1963, "duration": 168 } }, { "key": "song", "data": { "name": "Ace of wands", "artist": "Steeve Hackett", "album": "Voyage of the acolyte", "year": 1975, "duration": 326 } }, { "key": "song", "data": { "name": "Three little birds", "artist": "Bob Marley and the Wailers", "album": "Exodus", "year": 1977, "duration": 183 } }]
{ "succes": true }

DELETE /record/:key

Deletes all the records having a specific key.

Response JSON object

Field Type Always present Description
success boolean yes true if the spreadsheet has been deleted, false otherwise.
error string no Error code, only present if the request failed.
errorText string no Error text that can add explainations to the error code. Can be present if the request failed.
{ "success": true }