ServerDocumentationApiGetting started

Getting started

The REST API exposes every Jspreadsheet Server document as an HTTP resource, usable from any language. Writes go through the same pipeline as real-time edits: applied to the live document, persisted through your adapter and broadcast to connected clients.

Base URL and authentication

Base URL

All routes live under /api:

https://your-server.example.com/api

Bearer token

Requests are authenticated with a Bearer token in the Authorization header. The token is passed to your authentication hooks as auth.token; the server itself does not interpret it.

Authorization: Bearer <token>

URL shape, body encoding and responses are described in HTTP conventions.

Create a spreadsheet

POST /api/create creates a document. The config field is a single JSON-encoded string:

With curl

curl -X POST https://your-server.example.com/api/create \
  -H "Authorization: Bearer $TOKEN" \
  -F "guid=aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0001" \
  -F 'config={"worksheets":[{"worksheetName":"firstWorksheet","minDimensions":[10,10]}]}'

With fetch

const body = new FormData();
body.append('guid', 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0001');
body.append('config', JSON.stringify({
    worksheets: [
        {
            worksheetName: 'firstWorksheet',
            minDimensions: [10, 10],
        }
    ]
}));

const response = await fetch('https://your-server.example.com/api/create', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body,
});

See Create for the configuration options.

Read and write

The worksheet index follows the guid in the URL and can be omitted for worksheet 0:

Read the data matrix

const baseUrl = 'https://your-server.example.com/api';
const guid = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0001';
const headers = { 'Authorization': `Bearer ${token}` };

// Read the data matrix of worksheet 0
const data = await (await fetch(`${baseUrl}/${guid}/0/data`, { headers })).json();

Set a cell value

// Set the value of cell A1 (x: 0, y: 0)
await fetch(`${baseUrl}/${guid}/0/value`, {
    method: 'POST',
    headers,
    body: new URLSearchParams({
        'data[0][x]': '0',
        'data[0][y]': '0',
        'data[0][value]': 'hello',
    }),
});

Successful writes return the new document revision: {"message": "Done", "rev": <n>}. Connected clients receive the same operation over their sockets tagged with that revision.

What is next?