Go Scribi

The API

Building a tree in one call

Make a folder tree and the notes in it in one request, all or nothing. Name things with your own reference ids so a note can go in a folder the same call is about to make, try it without doing it, and send an idempotency key so a lost reply cannot build it twice.

Every call here carries Authorization: Bearer <key> and answers JSON. What is true of every call, and what every refusal means.

POST /api/v1/w/:workspace_id/batches

Make a folder tree and its notes in one request.

needs
create on the thing it touches
answers
**201**, and made, which maps each of your refs to the id it became. A replay answers **200** with replayed: true and the FIRST answer.
refusals
unauthorized, not_found, forbidden, read_only_key, workspace_locked, over_the_note_limit, invalid, too_many_requests
Parameters for POST /api/v1/w/:workspace_id/batches
Parameter In Type Description
plan required body object folders and notes, each an array. See the notes below.
idempotency_key body string Your own name for this attempt. Send one: it is what makes a lost reply safe to retry.

EACH THING CARRIES A ref — a name you invent. A parent or folder that is a NUMBER is a folder that already exists; anything else is one of your refs, which is how a note goes in a folder this same call is about to make.

A folder is {ref, name, parent}. A note is {ref, title, folder, kind, body}, where kind is markdown, checklist, board or map.

ALL OR NOTHING. If any part is refused, nothing at all is made — a half-built tree is worse than none, because your next call would refer to things that may or may not exist.

dry_run: true inside the plan says what it would do and does none of it. It answers with every ref and NO ids, because it made nothing to have one, and it is never remembered against an idempotency key.

SEND AN IDEMPOTENCY KEY. If the reply never reaches you, send the same plan with the same key and you get the first answer back rather than a second tree. The same key with a DIFFERENT plan is refused. Remembered for seven days.

It only MAKES things. Moving, renaming and deleting have their own calls, and a batch that could do everything is one nobody can review before running it.

At most 50 things in one plan, and the workspace's note allowance is counted across the whole plan rather than one note at a time.

An example 
curl -X POST https://goscribi.com/api/v1/w/141/batches \
  -H "Authorization: Bearer $GO_SCRIBI_KEY" \
  -H "Content-Type: application/json" \
  -d '"{\"plan\":{\"folders\":[{\"ref\":\"reference\",\"name\":\"Reference\"},{\"ref\":\"functions\",\"name\":\"Map Of Functions\",\"parent\":\"reference\"},{\"ref\":\"play\",\"name\":\"Play Book\",\"parent\":\"reference\"}],\"notes\":[{\"ref\":\"how\",\"title\":\"How this works\",\"folder\":\"functions\",\"body\":\"# How\\n\"},{\"ref\":\"first\",\"title\":\"First run\",\"folder\":\"play\"}]}}"'

Answers 201:

{
  "made": {
    "folders": {
      "reference": 151,
      "functions": 152,
      "play": 153
    },
    "notes": {
      "how": 133,
      "first": 134
    }
  },
  "dry_run": false,
  "replayed": false
}