your5e.com

Notebook Pages

Operations on individual pages within a notebook.

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

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

  • file (required): the file content to upload
  • filename (optional): override the uploaded file's name

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": "/v1/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 /v1/notebooks/{username}/{notebook-slug}/{uuid}

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

Arguments:

  • version returns a specific version of the page instead of the latest
  • hash returns the version with the specified content hash

Only one of version or hash may be specified. Returns 400 Bad Request if both are provided.

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/hash does not exist.

PATCH /v1/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": "/v1/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 /v1/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.

Headers:

  • Previous-Hash (optional): the content hash of the version this update is based on, to attempt to merge local changes with server changes; omit if not known or complete replacement is desired. Only affects text/markdown pages.

Response

The response structure is the same as PATCH, with additional fields:

  • previous_hash: the content hash before this update, for client-side conflict detection
  • update: indicates how the update was applied:
  • applied: the Previous-Hash matched the current version, update applied directly
  • merged: the Previous-Hash was found in history, changes were merged with server changes
  • replaced: no Previous-Hash was provided, or it was not found in history, content was replaced
  • unchanged: the content was identical to the current version, no new version was created

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 /v1/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.