DocumentationServerApiGetting started

Getting started

The REST API exposes every document managed by Jspreadsheet Server as an HTTP resource. Any language or tool that can send HTTP requests can create spreadsheets, read data and apply changes. Writes go through the same pipeline as real-time edits: they are 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 on your server:

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>

The full request format, covering URL shape, body encoding and response semantics, is 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

The same request 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

With the document guid, the worksheet routes read and modify the spreadsheet. 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?