Use the REST API

The API reads and writes scribbles as Markdown, with the same permissions you have in the app, and its edits reach everyone’s screen live. The base URL is https://api.scribblespace.app. The API reference has every field, samples in cURL, Python and JavaScript, and a Try it button on each endpoint.

Authenticate

Send your API key as a Bearer token on every request, image downloads included: Authorization: Bearer ss_…. Keep it in an environment variable such as SCRIBBLESPACE_API_KEY rather than in your code.

Endpoints

What it does	Request	Key access
List notebooks	`GET /api/v1/notebooks`	Read only or read and write
List scribbles	`GET /api/v1/scribbles`	Read only or read and write
Retrieve a scribble	`GET /api/v1/scribbles/{id}`	Read only or read and write
Create a scribble	`POST /api/v1/notebooks/{notebook}/scribbles`	Read and write
Update a scribble	`PATCH /api/v1/scribbles/{id}`	Read and write
Download an image	`GET /api/v1/notebooks/{notebook}/images/{hash}`	Read only or read and write

A first request

Search titles and text with q: curl 'https://api.scribblespace.app/api/v1/scribbles?q=launch' -H "Authorization: Bearer $SCRIBBLESPACE_API_KEY". To read one scribble, use its ID, the last part of its link after /notes/, with /api/v1/scribbles/{id}. The answer holds its Markdown, the images it embeds and the scribbles it links to.

Edit safely

Every read returns a revision. When you update a scribble, send it back as ifMatch along with only the fields you’re changing. If someone changed the scribble since you read it, you get 409: read it again, merge your change and retry. Only the text that actually changed is replaced, so people typing in the scribble keep their place.

To move a scribble to Trash, update it with deleted set to true; false restores it. The API doesn’t delete scribbles permanently.

Limits

Titles up to 300 characters and bodies up to 1 MiB of Markdown.
Searches up to 200 characters.
Up to 200 results per page. Pass nextOffset as offset to get the next page, until it comes back null.
Images up to 12 MiB.
A request that runs longer than 30 seconds is cancelled.

Errors

Errors come with a JSON body whose error says what went wrong.

Status	Meaning
`400`	Something in the request is invalid: an ID, a field or a limit.
`401`	The key is missing, expired or revoked. Create a new one.
`402`	The workspace is read-only because its trial or plan ended. Reading still works.
`403`	The key or your role can’t do this, such as writing with a read-only key.
`404`	Nothing with that ID in the key’s workspace, or it’s private to someone else.
`409`	The scribble changed since you read it. Read it again and merge.
`413`	The request body is too large.
`429` / `503`	Busy. Wait and retry, honoring the `Retry-After` header.