---
updatedAt: 2026-04-08T10:21:31.000Z
agentTools:
  projectIndex: https://developer.goacoustic.com/acoustic-content/llms.txt
---

# Move a page.

Use this endpoint to move a page. The body of the request should be empty.
The query parameters should include the 'sourceId', 'sourceRev', 'targetPosition', the optional 'targetId' and 'targetRev'.
`sourceId` and `sourceRev` relate to the page to be moved.
`targetId` and `targetRev` relate to the destination parent page.  These are optional parameters, if not set it means the source page is to be moved to the site root.
The `targetPosition` field is required, it is an integer value starting at 0. It cannot exceed the number of child pages of the destination parent page.
If the move is successful, then the response body JSON object will contain the id and rev of the updated destination parent page (`targetId`), except in the case of moving to the site root then the response body is an empty JSON object.
A refresh of the page hierarchy is recommended after moving a page to a different parent page.
<br />User roles: admin, manager, editor

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.142",
    "x-ibm-name": "ibm-watson-content-hub-api",
    "title": "Acoustic Content API",
    "description": "Copyright © Acoustic, L.P. 2019"
  },
  "tags": [
    {
      "name": "Authoring sites",
      "description": "Use the Content authoring sites service Rest APIs to work with sites. Sites are comprised of a site metadata and a hierarchy of pages. You can retrieve or update site metadata and create, read, update, and delete site pages belonging to a site. The out-of-the-box site has an ID of 'default'.\n"
    }
  ],
  "paths": {
    "/authoring/v1/sites/{site-id}/pages/move": {
      "post": {
        "x-ibm-dx-security-user-roles": [
          "admin",
          "manager",
          "editor"
        ],
        "summary": "Move a page.",
        "description": "Use this endpoint to move a page. The body of the request should be empty.\nThe query parameters should include the 'sourceId', 'sourceRev', 'targetPosition', the optional 'targetId' and 'targetRev'.\n`sourceId` and `sourceRev` relate to the page to be moved.\n`targetId` and `targetRev` relate to the destination parent page.  These are optional parameters, if not set it means the source page is to be moved to the site root.\nThe `targetPosition` field is required, it is an integer value starting at 0. It cannot exceed the number of child pages of the destination parent page.\nIf the move is successful, then the response body JSON object will contain the id and rev of the updated destination parent page (`targetId`), except in the case of moving to the site root then the response body is an empty JSON object.\nA refresh of the page hierarchy is recommended after moving a page to a different parent page.\n<br />User roles: admin, manager, editor",
        "parameters": [
          {
            "name": "site-id",
            "in": "path",
            "description": "The ID of the site.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "sourceId",
            "in": "query",
            "description": "The ID of the source page to move.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "sourceRev",
            "in": "query",
            "description": "the 'rev' value for the page to be moved.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "targetId",
            "in": "query",
            "description": "The ID of the target page.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "targetRev",
            "in": "query",
            "description": "the 'rev' value for the target page.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "targetPosition",
            "in": "query",
            "description": "The new position on the  target page for the move.",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "succcess.",
            "content": {
              "application/json": {
                "schema": {
                  "title": "Target Parent After Move",
                  "description": "Target Parent Updated Values After Move",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "(optional) The ID of the parent page item."
                    },
                    "rev": {
                      "type": "string",
                      "description": "(optional) The latest revision of the parent page item document."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "title": "ErrorMessage",
                  "description": "ErrorMessage",
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string",
                      "description": "Service name."
                    },
                    "requestId": {
                      "type": "string",
                      "description": "Request ID."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "title": "Error",
                        "description": "Error",
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "integer"
                          },
                          "message": {
                            "type": "string"
                          },
                          "level": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "cause": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "integer"
                              },
                              "message": {
                                "type": "string"
                              }
                            }
                          },
                          "locale": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "value": {
                      "service": "prod-authoring-sites",
                      "requestId": "455478465455511",
                      "errors": [
                        {
                          "code": 2041,
                          "message": "A target position of 10 is not valid for the children of page with ID dummyPage, so no move occurred",
                          "level": "ERROR",
                          "description": "Unable to move the page. The target position supplied is invalid for the target page. Change the targetPosition and try again",
                          "locale": "en"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "title": "ErrorMessage",
                  "description": "ErrorMessage",
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string",
                      "description": "Service name."
                    },
                    "requestId": {
                      "type": "string",
                      "description": "Request ID."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "title": "Error",
                        "description": "Error",
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "integer"
                          },
                          "message": {
                            "type": "string"
                          },
                          "level": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "cause": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "integer"
                              },
                              "message": {
                                "type": "string"
                              }
                            }
                          },
                          "locale": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "value": {
                      "service": "prod-authoring-sites",
                      "requestId": "455478465455511",
                      "errors": [
                        {
                          "code": 1016,
                          "message": "Problem accessing database.",
                          "level": "ERROR",
                          "description": "Problem accessing database. Try again or contact Acoustic support if problem persists.",
                          "locale": "en"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "title": "ErrorMessage",
                  "description": "ErrorMessage",
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string",
                      "description": "Service name."
                    },
                    "requestId": {
                      "type": "string",
                      "description": "Request ID."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "title": "Error",
                        "description": "Error",
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "integer"
                          },
                          "message": {
                            "type": "string"
                          },
                          "level": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "cause": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "integer"
                              },
                              "message": {
                                "type": "string"
                              }
                            }
                          },
                          "locale": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "value": {
                      "service": "prod-authoring-sites",
                      "requestId": "455478465455511",
                      "errors": [
                        {
                          "code": 1016,
                          "message": "Problem accessing database.",
                          "level": "ERROR",
                          "description": "Problem accessing database. Try again or contact Acoustic support if problem persists.",
                          "locale": "en"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "title": "ErrorMessage",
                  "description": "ErrorMessage",
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string",
                      "description": "Service name."
                    },
                    "requestId": {
                      "type": "string",
                      "description": "Request ID."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "title": "Error",
                        "description": "Error",
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "integer"
                          },
                          "message": {
                            "type": "string"
                          },
                          "level": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "cause": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "integer"
                              },
                              "message": {
                                "type": "string"
                              }
                            }
                          },
                          "locale": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "value": {
                      "service": "prod-authoring-sites",
                      "requestId": "455478465455511",
                      "errors": [
                        {
                          "code": 2012,
                          "message": "Page not found for ID: dummyId",
                          "level": "ERROR",
                          "description": "A page with the specified ID was not found in the system. Provide a valid ID and try again.",
                          "locale": "en"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "title": "ErrorMessage",
                  "description": "ErrorMessage",
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string",
                      "description": "Service name."
                    },
                    "requestId": {
                      "type": "string",
                      "description": "Request ID."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "title": "Error",
                        "description": "Error",
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "integer"
                          },
                          "message": {
                            "type": "string"
                          },
                          "level": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "cause": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "integer"
                              },
                              "message": {
                                "type": "string"
                              }
                            }
                          },
                          "locale": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "value": {
                      "service": "prod-authoring-sites",
                      "requestId": "455478465455511",
                      "errors": [
                        {
                          "code": 1018,
                          "message": "Temporarily unable to access the database.",
                          "level": "ERROR",
                          "description": "Temporarily unable to access the database. Try again or contact Acoustic support if problem persists.",
                          "locale": "en"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "title": "ErrorMessage",
                  "description": "ErrorMessage",
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string",
                      "description": "Service name."
                    },
                    "requestId": {
                      "type": "string",
                      "description": "Request ID."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "title": "Error",
                        "description": "Error",
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "integer"
                          },
                          "message": {
                            "type": "string"
                          },
                          "level": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "cause": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "integer"
                              },
                              "message": {
                                "type": "string"
                              }
                            }
                          },
                          "locale": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "value": {
                      "service": "prod-authoring-sites",
                      "requestId": "455478465455511",
                      "errors": [
                        {
                          "code": 5004,
                          "message": "Unexpected error occurred.",
                          "level": "ERROR",
                          "description": "Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists.",
                          "locale": "en"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Authoring sites"
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```