Transferring an Organization
Transfer one organization into another, moving all of the members, teams, and content and preserving public content URLs.
The GitBook API is currently in beta. This means you should not rely on it's availability, and that it may change without prior warning. If you wish to be one of our testers, please contact our team at [email protected].
This is an experimental endpoint and unsupervised use could result in loss of content and/or public URLs breaking. Contact us at [email protected] if you're interested in this functionality and we'll help you through the process.
The transfer operation is irreversible. Content is moved from one organization to another, it is not duplicated or copied. It is not possible to undo a transfer operation.

Terminology

The source organization is the organization you are transferring all content from. The source organization will be empty once the transfer is complete.
The target organization is the organization you are transferring all content to.

Usage

You must be an administrator of both organizations to perform the transfer.
This is an experimental endpoint that is not currently publicly accessible. Contact us if you are in need of this functionality and we'll help you get set up.

Advanced

Members & Teams

All members and teams from the target organization will be migrated into the source organization, unless they already exist in the target (members of both organizations will be unaffected).
The organization-level permission of the transferred member depends on the defaultOrgRole parameter:
  • If the defaultOrgRole is set to a valid GitBook permission (such as editor, commenter, etc.), that value will be used as the permission for new organization members.
  • If the defaultOrgRole is set to saml, then the role will be taken from the SAML provider of the target organization. If your target organization has SSO enabled, and adds new users as commenters in the organization, then the commenter role will be used.
  • If the defaultOrgRole is not set, new members will have read permissions in the target organization.
If a member already exists in the target organization (i.e. they were a member of both source and target organizations before the transfer), their org-level permission will not change.

Content

All of your content will be moved to a new top-level collection in the target organization. This collection will have the name and icon of the source organization.
For example if you wanted to transfer the source organization "iPhone" into the target organization "Apple", there'd be a new collection called "iPhone" in the Apple organization once the transfer was complete.
The content-level permissions of the source organization will be transferred to this new collection. A user who was an editor in the target organization will be an editor of the top-level collection once the transfer is complete. All other permissions will be respected.

GitBook URLs and Paths

GitBook URLs (those that start with https://app.gitbook.com) and paths (such as /product-documentation/guidelines) will continue to function as normally.

Hostnames

If your source organization has some public content, it will have been assigned a GitBook hostname of the format https://hostname.gitbook.io
We'll transfer this hostname over to the new organization, so the gitbook.io URL will continue to work.
The source organization will have a new hostname generated on its behalf, this will be a non-conflicting hostname based on the previous. Imagine you had the following setup:
source.gitbook.io => the source organization
target.gitbook.io => the target organization
Once the transfer was complete, the hostnames would be set up like so:
source.gitbook.io => the target organization
target.gitbook.io => the target organization
source-1.gitbook.io => the source organization (now empty)
It's possible that both your target and source organizations have content that use the same path (e.g. target.gitbook.io/welcome and source.gitbook.io/welcome)
This will cause a conflict when the transfer takes place and the path of the source organization will be reassigned.
Once the transfer is complete,
target.gitbook.io/welcome will point to the target organization's welcome space.
source.gitbook.io/welcome will also point to the target organization's welcome space.
source.gitbook.io/welcome-1 will point to the source organization's welcome space.
For any users that still hold the old source URL, they'll be redirected to a space they may have never seen before.
In order to prevent this, ensure that there are no conflicting paths for public content in your source and target organizations.

Custom Domains

Any custom domains you have set up on the source organization will now direct to the newly created top-level collection in the target organization.
This should ensure your custom domains continue to point to the correct content.