Skip to main content

Move Block

POST 
/blocks/:block_id/move

Path Parameters​

ParameterTypeRequiredDescription
block_idUUIDYesThe unique identifier of the block to move

Request Body​

{
  "new_parent_id": "uuid",
  "new_chapter_id": "uuid | null",
  "after_id": "uuid | null"
}

Fields​

FieldTypeRequiredDescription
new_parent_idUUIDYesThe ID of the new parent block where this block will be moved to. This determines the hierarchical position in the document tree.
new_chapter_idUUID | nullNoThe ID of the chapter to associate this block with. If not provided, the block retains its current chapter association.
after_idUUID | nullNoThe ID of the sibling block after which this block should be positioned within the new parent. If null or omitted, the block is inserted at the beginning of the new parent's children.

Understanding the Move Operation​

Moving a block involves three key aspects:

1. Changing Parent (Hierarchical Position)​

The new_parent_id determines where in the document tree the block will reside.

Example Scenario - Moving within same level:

Before:
Page Block (page-001)
    Heading Block (heading-001)
    Paragraph A (para-001)        <- Block to move
    Table Block (table-001)
    Paragraph B (para-002)

After moving para-001 to table-001:
Page Block (page-001)
    Heading Block (heading-001)
    Table Block (table-001)
        Paragraph A (para-001)    <- Moved here as child of table
    Paragraph B (para-002)

2. Positioning Among Siblings​

The after_id controls the order within the new parent's children.

Example Scenario:

Target Parent: table-001
Current Children:
    Row A (row-aaa) [position: 1]
    Row B (row-bbb) [position: 2]
    Row C (row-ccc) [position: 3]

Moving "para-001" to table-001:
- after_id = null         -> para-001 inserted at position 1 (before Row A)
- after_id = "row-aaa"    -> para-001 inserted at position 2 (between A and B)
- after_id = "row-bbb"    -> para-001 inserted at position 3 (between B and C)
- after_id = "row-ccc"    -> para-001 inserted at position 4 (after Row C)

3. Chapter Reassignment (Optional)​

The new_chapter_id allows reassigning the block to a different chapter during the move.

Example Scenario:

Document: "Environmental Report"
  +-- Chapter: "Introduction" (chapter-intro-001)
  |   +-- Block: Overview paragraph (para-001)   <- Moving this
  +-- Chapter: "Methodology" (chapter-method-001)
  |   +-- Block: Data collection heading
  +-- Chapter: "Results" (chapter-results-001)
      +-- Block: Findings table

Moving para-001 to Results chapter:
Request body:
{
  "new_parent_id": "results-parent-block-id",
  "new_chapter_id": "chapter-results-001",
  "after_id": null
}

Complete Request Examples​

Example 1: Move block to different parent (same chapter)​

Scenario: Move a paragraph block to become a child of a callout block.

POST /blocks/para-123-uuid/move
{
  "new_parent_id": "callout-456-uuid",
  "after_id": null
}

Result: The paragraph is now nested inside the callout, at the first position.

Example 2: Move block with specific positioning​

Scenario: Move a list item to a specific position among siblings.

POST /blocks/list-item-789/move
{
  "new_parent_id": "page-block-001",
  "after_id": "existing-heading-block"
}

Result: The list item is moved under the page block, positioned immediately after the existing heading.

Example 3: Move block to different chapter​

Scenario: Relocate a block from "Introduction" chapter to "Conclusion" chapter.

POST /blocks/block-abc-123/move
{
  "new_parent_id": "conclusion-section-parent",
  "new_chapter_id": "chapter-conclusion-uuid",
  "after_id": "summary-paragraph-id"
}

Result: The block is moved to the Conclusion chapter, positioned after the summary paragraph.

Example 4: Reorder within same parent​

Scenario: Move a block to a different position under the same parent (reordering siblings).

POST /blocks/block-to-reorder/move
{
  "new_parent_id": "current-parent-id",
  "after_id": "target-sibling-id"
}

Result: The block stays under the same parent but is repositioned after the target sibling.

Response​

Success Response​

Status Code: 204 No Content

The move operation completed successfully. No response body is returned.

Error Responses​

400 Bad Request​

Invalid request parameters or validation error.

{
  "code": 400,
  "message": "Bad Request",
  "errors": [
    {
      "message": "new_parent_id is required"
    }
  ]
}

401 Unauthorized​

Missing or invalid authentication token.

{
  "code": 401,
  "message": "Unauthorized",
  "errors": [
    {
      "message": "Invalid or expired token"
    }
  ]
}

404 Not Found​

Block or target parent not found.

{
  "code": 404,
  "message": "Not Found",
  "errors": [
    {
      "message": "Block not found"
    }
  ]
}

500 Internal Server Error​

Server-side error.

{
  "code": 500,
  "message": "Internal Server Error",
  "errors": [
    {
      "message": "An unexpected error occurred"
    }
  ]
}

Best Practices​

  1. Validate parent compatibility: Ensure the new parent block type can logically contain the block being moved (e.g., table rows should only be moved to table blocks).

  2. Preserve chapter consistency: When moving blocks between parents in the same chapter, consider whether new_chapter_id needs to be explicitly set.

  3. Handle circular references: The system prevents moving a block to become its own descendant. Attempting this will result in an error.

  4. Batch operations: For complex reorganizations, consider the order of move operations to avoid temporary invalid states.

  5. Position preservation: If you don't care about specific positioning, omit after_id to place the block at the beginning of the new parent's children.

  6. Audit trail: All move operations are tracked in the audit log with user information and timestamps.

Request​

Responses​

No Content