Notebook Pages

Operations on individual pages within a notebook.

POST /api/notebooks/{username}/{notebook-slug}/

Create a new page in the notebook. Accepts a multipart form with:

If filename is not provided, the uploaded file's original name is used. Filenames must have a file extension. Filenames can include directories (e.g. heroes/Theron.md). Hidden files (names starting with .) are not allowed.

Response

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "/api/notebooks/norm/campaign-notes/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "html_url": "https://your5e.com/notebooks/norm/campaign-notes/new-page",
  "filename": "New Page.md",
  "mime_type": "text/markdown",
  "version": 1,
  "created_by": "norm",
  "updated_at": "2024-01-15T12:00:00Z",
  "content_hash": "a1b2c3..."
}

Returns 201 Created on success.

Returns 403 Forbidden if you don't have edit permission on the notebook.

Returns 404 Not Found if the notebook does not exist or you don't have access to it.

Returns 400 Bad Request if: - no file is provided - the filename has no file extension - the filename is a hidden file (starts with .)

Returns 409 Conflict if a page with the same path already exists, or the path would be nested under an existing file.

GET /api/notebooks/{username}/{notebook-slug}/{uuid}

Returns the current content of a page, with the appropriate Content-Type header.

Arguments:

Returns 404 Not Found if the notebook or page does not exist, you don't have access, the page has been deleted, or the specified version does not exist.

PATCH /api/notebooks/{username}/{notebook-slug}/{uuid}

Update a page's metadata. Rename a page, revert it to an older version, or restore a deleted page. A new version is created with the change.

Renaming a page

{
  "filename": "New Name.md"
}

The content is preserved. If the filename is unchanged, no new version is created. Filenames can include directories (e.g. heroes/Theron.md). Hidden files (names starting with .) are not allowed.

Reverting to an older version

{
  "revert_to": 2
}

Creates a new version with the content, filename, and mime type from the specified version number. If the page is already at that content and filename, no new version is created.

Restoring a deleted page

To restore to the original location:

{
  "restore": true
}

To restore to a different location (e.g. to resolve a conflict):

{
  "restore": true,
  "filename": "Restored Page.md"
}

If the target location is occupied by another page, returns 409 Conflict.

Returns 403 Forbidden if you don't have edit permission on the notebook.

Returns 404 Not Found if the notebook or page does not exist, or you don't have access.

Response

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "/api/notebooks/norm/campaign-notes/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "html_url": "https://your5e.com/notebooks/norm/campaign-notes/new-name",
  "filename": "New Name.md",
  "mime_type": "text/markdown",
  "version": 2,
  "created_by": "norm",
  "updated_at": "2024-01-15T12:00:00Z",
  "content_hash": "a1b2c3..."
}

Returns 400 Bad Request if: - neither filename, revert_to, nor restore is provided (for non-deleted pages) - restore is not provided (for deleted pages) - both filename and revert_to are provided - the filename contains forbidden characters - the filename is a hidden file (starts with .) - the version number does not exist - revert_to is used on a deleted page

Returns 409 Conflict if the target path is occupied by another page, or the path would be nested under an existing file.

PUT /api/notebooks/{username}/{notebook-slug}/{uuid}

Update the content of a page, creating a new version. The request body should be the raw content, with the appropriate Content-Type header. If the page has been soft-deleted, this will restore it.

The response structure is the same as PATCH, with an additional previous_hash field containing the content hash before this update, which can be used for client-side conflict detection.

Returns 403 Forbidden if you don't have edit permission on the notebook.

Returns 404 Not Found if the notebook or page does not exist, or you don't have access.

Returns 409 Conflict if the page is deleted and its path is now occupied by another page. Use PATCH with a new filename to restore with a different name.

DELETE /api/notebooks/{username}/{notebook-slug}/{uuid}

Soft-delete a page. The page can be restored using PATCH with restore, or by updating its content with PUT.

Returns 204 No Content on success.

Returns 403 Forbidden if you don't have edit permission on the notebook.

Returns 404 Not Found if the notebook or page does not exist, has already been deleted, or you don't have access.