# Collections

Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.

## The Collection object

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"Collection":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"collection\"","enum":["collection"]},"id":{"type":"string","description":"Unique identifier for the collection"},"title":{"$ref":"#/components/schemas/CollectionTitle"},"description":{"$ref":"#/components/schemas/CollectionDescription"},"organization":{"type":"string","description":"ID of the organization owning this collection"},"parent":{"type":"string","description":"ID of the parent collection, if any"},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the collection in the API","format":"uri"},"app":{"type":"string","description":"URL of the collection in the application","format":"uri"}},"required":["app","location"]},"permissions":{"type":"object","description":"The set of permissions for the collection","properties":{"view":{"type":"boolean","description":"Can the user view the collection."},"admin":{"type":"boolean","description":"Can the user edit the title/description."},"viewInviteLinks":{"type":"boolean","description":"Can the user view the invite links of the collection."},"create":{"type":"boolean","description":"Can the user create spaces/collections in this collection."}},"required":["view","admin","viewInviteLinks","create"]}},"required":["object","id","title","organization","urls","defaultLevel","permissions"]},"CollectionTitle":{"type":"string","description":"Title of the collection","maxLength":50},"CollectionDescription":{"type":"string","description":"Description of the collection","minLength":0,"maxLength":100},"DefaultLevel":{"description":"Default level for a piece of content","oneOf":[{"$ref":"#/components/schemas/MemberRoleOrGuest"},{"type":"string","enum":["inherit"]}]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}}}}
```

## GET /collections/{collectionId}

> Get a collection by its ID

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collections","description":"Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n    The Collection object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"Collection":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"collection\"","enum":["collection"]},"id":{"type":"string","description":"Unique identifier for the collection"},"title":{"$ref":"#/components/schemas/CollectionTitle"},"description":{"$ref":"#/components/schemas/CollectionDescription"},"organization":{"type":"string","description":"ID of the organization owning this collection"},"parent":{"type":"string","description":"ID of the parent collection, if any"},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the collection in the API","format":"uri"},"app":{"type":"string","description":"URL of the collection in the application","format":"uri"}},"required":["app","location"]},"permissions":{"type":"object","description":"The set of permissions for the collection","properties":{"view":{"type":"boolean","description":"Can the user view the collection."},"admin":{"type":"boolean","description":"Can the user edit the title/description."},"viewInviteLinks":{"type":"boolean","description":"Can the user view the invite links of the collection."},"create":{"type":"boolean","description":"Can the user create spaces/collections in this collection."}},"required":["view","admin","viewInviteLinks","create"]}},"required":["object","id","title","organization","urls","defaultLevel","permissions"]},"CollectionTitle":{"type":"string","description":"Title of the collection","maxLength":50},"CollectionDescription":{"type":"string","description":"Description of the collection","minLength":0,"maxLength":100},"DefaultLevel":{"description":"Default level for a piece of content","oneOf":[{"$ref":"#/components/schemas/MemberRoleOrGuest"},{"type":"string","enum":["inherit"]}]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}}},"paths":{"/collections/{collectionId}":{"get":{"operationId":"getCollectionById","summary":"Get a collection by its ID","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/collectionId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}}}}}}
```

## DELETE /collections/{collectionId}

> Delete a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collections","description":"Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n    The Collection object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"}}},"paths":{"/collections/{collectionId}":{"delete":{"operationId":"deleteCollectionById","summary":"Delete a collection","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/collectionId"}],"responses":{"204":{"description":"Collection did not exist"},"205":{"description":"Collection has been deleted"}}}}}}
```

## PATCH /collections/{collectionId}

> Update a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collections","description":"Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n    The Collection object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"CollectionTitle":{"type":"string","description":"Title of the collection","maxLength":50},"CollectionDescription":{"type":"string","description":"Description of the collection","minLength":0,"maxLength":100},"DefaultLevel":{"description":"Default level for a piece of content","oneOf":[{"$ref":"#/components/schemas/MemberRoleOrGuest"},{"type":"string","enum":["inherit"]}]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]},"Collection":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"collection\"","enum":["collection"]},"id":{"type":"string","description":"Unique identifier for the collection"},"title":{"$ref":"#/components/schemas/CollectionTitle"},"description":{"$ref":"#/components/schemas/CollectionDescription"},"organization":{"type":"string","description":"ID of the organization owning this collection"},"parent":{"type":"string","description":"ID of the parent collection, if any"},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the collection in the API","format":"uri"},"app":{"type":"string","description":"URL of the collection in the application","format":"uri"}},"required":["app","location"]},"permissions":{"type":"object","description":"The set of permissions for the collection","properties":{"view":{"type":"boolean","description":"Can the user view the collection."},"admin":{"type":"boolean","description":"Can the user edit the title/description."},"viewInviteLinks":{"type":"boolean","description":"Can the user view the invite links of the collection."},"create":{"type":"boolean","description":"Can the user create spaces/collections in this collection."}},"required":["view","admin","viewInviteLinks","create"]}},"required":["object","id","title","organization","urls","defaultLevel","permissions"]}}},"paths":{"/collections/{collectionId}":{"patch":{"operationId":"updateCollectionById","summary":"Update a collection","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/collectionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"$ref":"#/components/schemas/CollectionTitle"},"description":{"$ref":"#/components/schemas/CollectionDescription"},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"}}}}}},"responses":{"200":{"description":"The collection has been updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}}}}}}
```

## GET /collections/{collectionId}/spaces

> List all collection spaces

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collections","description":"Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n    The Collection object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"listPage":{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},"listLimit":{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"Space":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"space\"","enum":["space"]},"id":{"type":"string","description":"Unique identifier for the space"},"title":{"$ref":"#/components/schemas/SpaceTitle"},"emoji":{"description":"An emoji for this space. It'll match the emoji shown in the GitBook app.","$ref":"#/components/schemas/Emoji"},"visibility":{"$ref":"#/components/schemas/ContentVisibility"},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"updatedAt":{"$ref":"#/components/schemas/Timestamp"},"deletedAt":{"$ref":"#/components/schemas/Timestamp"},"editMode":{"$ref":"#/components/schemas/SpaceEditMode"},"mergeRules":{"$ref":"#/components/schemas/MergeRulesSpaceConfiguration"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the space in the API","format":"uri"},"app":{"type":"string","description":"URL of the space in the application","format":"uri"},"published":{"type":"string","description":"URL of the published version of the space. Only defined when visibility is not \"private.\"","format":"uri"},"public":{"type":"string","description":"URL of the public version of the space. Only defined when visibility is \"public\".","format":"uri"},"icon":{"description":"URL of the icon of this space, if defined.","$ref":"#/components/schemas/URL"}},"required":["app","location"]},"organization":{"type":"string","description":"ID of the organization owning this space"},"parent":{"type":"string","description":"ID of the parent collection."},"language":{"$ref":"#/components/schemas/TranslationLanguage"},"gitSync":{"$ref":"#/components/schemas/GitSyncState"},"visitorAuth":{"$ref":"#/components/schemas/VisitorAuth"},"revision":{"type":"string","description":"ID of the active revision in the space."},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"},"comments":{"type":"number","description":"Count of opened comments on the space."},"changeRequests":{"type":"number","description":"Total count of change requests on the space."},"changeRequestsOpen":{"type":"number","description":"Count of open change requests on the space."},"changeRequestsDraft":{"type":"number","description":"Count of draft change requests on the space."},"internal_poweredByV2":{"type":"boolean","description":"Whether the space is powered by V2 of the content system."},"internal_singleWebsocket":{"type":"boolean","description":"Whether the space uses a single websocket connection for all real-time communication."},"permissions":{"type":"object","description":"The set of permissions for the space","properties":{"view":{"type":"boolean","description":"Can the user view the space content."},"access":{"type":"boolean","description":"Can the user access the space in the application."},"admin":{"type":"boolean","description":"Can the user edit the title, install integrations, and manage the space."},"viewInviteLinks":{"type":"boolean","description":"Can the user view the invite links of the space."},"edit":{"type":"boolean","description":"Can the user edit the content of the space by creating a change request."},"triggerGitSync":{"type":"boolean","description":"Can the user trigger a git sync."},"comment":{"type":"boolean","description":"Can the user comment on the content."},"merge":{"type":"boolean","description":"Can the user merge change requests."},"review":{"type":"boolean","description":"Can the user review change requests."},"installIntegration":{"type":"boolean","description":"Can the user install integrations in the space."}},"required":["view","access","admin","viewInviteLinks","edit","triggerGitSync","comment","merge","review","installIntegration"]}},"required":["object","id","title","emoji","organization","visibility","revision","createdAt","updatedAt","comments","changeRequests","changeRequestsOpen","changeRequestsDraft","mergeRules","urls","defaultLevel","permissions"]},"SpaceTitle":{"type":"string","description":"Title of the space","maxLength":50},"Emoji":{"type":"string","maxLength":50,"format":"emoji","description":"Unicode codepoint or character of the emoji"},"ContentVisibility":{"type":"string","description":"* `public`: Anyone can access the content, and the content is indexed by search engines.\n* `unlisted`: Anyone can access the content, and the content is not indexed by search engines\n* `share-link`: Anyone with a secret token in the url can access the content.\n* `visitor-auth`: Anyone authenticated through a JWT token can access the content.\n* `in-collection`: Anyone who can access the parent collection can access the content.\n  Only available for spaces in a collection.\n* `private`: Authorized members can access the content.\n","enum":["public","unlisted","share-link","visitor-auth","in-collection","private"]},"Timestamp":{"type":"string","format":"date-time"},"SpaceEditMode":{"type":"string","description":"Determines how a Space can be edited.\n* `live`: Users can directly edit the space\n* `locked`: All edits are locked for this space.\n","enum":["live","locked"]},"MergeRulesSpaceConfiguration":{"oneOf":[{"$ref":"#/components/schemas/MergeRulesConfigurationInherit"},{"$ref":"#/components/schemas/MergeRulesStandaloneConfiguration"}]},"MergeRulesConfigurationInherit":{"type":"object","description":"The merge rules inherits from the organization configuration.","properties":{"type":{"type":"string","enum":["inherit"]}},"required":["type"]},"MergeRulesStandaloneConfiguration":{"oneOf":[{"$ref":"#/components/schemas/MergeRulesConfigurationRules"},{"$ref":"#/components/schemas/MergeRulesConfigurationNone"}]},"MergeRulesConfigurationRules":{"type":"object","description":"The merge rules are composed of individual rules that must all pass.","properties":{"type":{"type":"string","enum":["rules"]},"rules":{"type":"array","items":{"$ref":"#/components/schemas/MergeRule"}}},"required":["type","rules"]},"MergeRule":{"oneOf":[{"type":"object","properties":{"rule":{"type":"string","enum":["require_specific_reviewers"]},"users":{"type":"array","description":"List of user IDs.","items":{"type":"string"}}},"required":["rule","users"]},{"type":"object","properties":{"rule":{"type":"string","enum":["require_one_of_specific_reviewers"]},"users":{"type":"array","description":"List of user IDs.","items":{"type":"string"}}},"required":["rule","users"]},{"type":"object","properties":{"rule":{"type":"string","enum":["allow_bypass"]},"users":{"type":"array","description":"List of user IDs.","items":{"type":"string"}}},"required":["rule","users"]},{"type":"object","properties":{"rule":{"type":"string","enum":["require_at_least_one_review","require_at_least_one_approved_review","require_all_reviews_approved","require_agent_review","require_up_to_date_change_request","require_change_request_subject","require_change_request_description","require_author_to_merge"]}},"required":["rule"]},{"type":"object","description":"The merge rule is written in the advanced custom expression syntax.","properties":{"rule":{"type":"string","enum":["custom"]},"expression":{"$ref":"#/components/schemas/Expression"}},"required":["rule","expression"]}]},"Expression":{"type":"string","description":"Expression to evaluate","minLength":0,"maxLength":1024},"MergeRulesConfigurationNone":{"type":"object","description":"The merge rules are disabled, change requests can be merged without review.","properties":{"type":{"type":"string","enum":["none"]}},"required":["type"]},"URL":{"type":"string","format":"uri","maxLength":2048},"TranslationLanguage":{"type":"string","enum":["en","fr","de","es","it","pt","pt-br","ru","ja","zh","yue","ko","ar","hi","nl","pl","tr","sv","no","da","fi","el","cs","hu","ro","th","vi","id","ms","he","uk","sk","bg","hr","lt","lv","et","sl"]},"GitSyncState":{"type":"object","properties":{"repoName":{"type":"string","description":"Repository name."},"installationProvider":{"$ref":"#/components/schemas/GitSyncProvider"},"integration":{"type":"string","description":"The integration name providing the Git Sync."},"url":{"type":"string","description":"The URL to the repository tree, used when rendering public content."},"updatedAt":{"description":"When the Git provider details were last updated","$ref":"#/components/schemas/Timestamp"}}},"GitSyncProvider":{"type":"string","description":"The provider of the Git Sync installation.","enum":["github","gitlab","github-legacy"]},"VisitorAuth":{"oneOf":[{"$ref":"#/components/schemas/VisitorAuthCustomBackend"},{"allOf":[{"$ref":"#/components/schemas/VisitorAuthIntegrationBackend"},{"type":"object","properties":{"integration":{"type":"string","description":"Name of integration being used as the backend for authenticated access"}},"required":["integration"]}]}]},"VisitorAuthCustomBackend":{"type":"object","title":"Custom backend for authenticated access","properties":{"backend":{"type":"string","description":"Custom backend for authenticated access","enum":["custom"]}},"required":["backend"]},"VisitorAuthIntegrationBackend":{"type":"object","title":"Integration backend for authenticated access","properties":{"backend":{"type":"string","description":"Integration as backend for authenticated access","enum":["integration"]}},"required":["backend"]},"DefaultLevel":{"description":"Default level for a piece of content","oneOf":[{"$ref":"#/components/schemas/MemberRoleOrGuest"},{"type":"string","enum":["inherit"]}]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}}},"paths":{"/collections/{collectionId}/spaces":{"get":{"operationId":"listSpacesInCollectionById","summary":"List all collection spaces","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Space"}}}}]}}}}}}}}}
```

## POST /collections/{collectionId}/move

> Move a collection to a new position.

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collections","description":"Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n    The Collection object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"ContentPosition":{"type":"object","description":"Position at which to insert an item","properties":{"before":{"oneOf":[{"$ref":"#/components/schemas/SpacePointer"},{"$ref":"#/components/schemas/CollectionPointer"}]},"after":{"oneOf":[{"$ref":"#/components/schemas/SpacePointer"},{"$ref":"#/components/schemas/CollectionPointer"}]}}},"SpacePointer":{"type":"object","properties":{"type":{"type":"string","enum":["space"]},"space":{"type":"string","description":"Unique identifier for the space"}},"required":["type","space"]},"CollectionPointer":{"type":"object","properties":{"type":{"type":"string","enum":["collection"]},"collection":{"type":"string","description":"Unique identifier for the collection"}},"required":["type","collection"]},"Collection":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"collection\"","enum":["collection"]},"id":{"type":"string","description":"Unique identifier for the collection"},"title":{"$ref":"#/components/schemas/CollectionTitle"},"description":{"$ref":"#/components/schemas/CollectionDescription"},"organization":{"type":"string","description":"ID of the organization owning this collection"},"parent":{"type":"string","description":"ID of the parent collection, if any"},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the collection in the API","format":"uri"},"app":{"type":"string","description":"URL of the collection in the application","format":"uri"}},"required":["app","location"]},"permissions":{"type":"object","description":"The set of permissions for the collection","properties":{"view":{"type":"boolean","description":"Can the user view the collection."},"admin":{"type":"boolean","description":"Can the user edit the title/description."},"viewInviteLinks":{"type":"boolean","description":"Can the user view the invite links of the collection."},"create":{"type":"boolean","description":"Can the user create spaces/collections in this collection."}},"required":["view","admin","viewInviteLinks","create"]}},"required":["object","id","title","organization","urls","defaultLevel","permissions"]},"CollectionTitle":{"type":"string","description":"Title of the collection","maxLength":50},"CollectionDescription":{"type":"string","description":"Description of the collection","minLength":0,"maxLength":100},"DefaultLevel":{"description":"Default level for a piece of content","oneOf":[{"$ref":"#/components/schemas/MemberRoleOrGuest"},{"type":"string","enum":["inherit"]}]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[400]},"message":{"type":"string"}},"required":["code","message"]}}}}}},"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}},"ConflictError":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[409]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/move":{"post":{"operationId":"moveCollection","summary":"Move a collection to a new position.","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/collectionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"parent":{"description":"The unique id of the parent collection","type":["string","null"]},"position":{"description":"Where to move the collection. By default, it will be moved at the end.","$ref":"#/components/schemas/ContentPosition"}}}}}},"responses":{"200":{"description":"Collection moved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Invalid position space or collection provided","$ref":"#/components/responses/BadRequestError"},"404":{"description":"No matching Collection found for given ID","$ref":"#/components/responses/NotFoundError"},"409":{"description":"Operation would not result in any update","$ref":"#/components/responses/ConflictError"}}}}}}
```

## POST /collections/{collectionId}/transfer

> Transfer a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collections","description":"Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n    The Collection object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"Collection":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"collection\"","enum":["collection"]},"id":{"type":"string","description":"Unique identifier for the collection"},"title":{"$ref":"#/components/schemas/CollectionTitle"},"description":{"$ref":"#/components/schemas/CollectionDescription"},"organization":{"type":"string","description":"ID of the organization owning this collection"},"parent":{"type":"string","description":"ID of the parent collection, if any"},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the collection in the API","format":"uri"},"app":{"type":"string","description":"URL of the collection in the application","format":"uri"}},"required":["app","location"]},"permissions":{"type":"object","description":"The set of permissions for the collection","properties":{"view":{"type":"boolean","description":"Can the user view the collection."},"admin":{"type":"boolean","description":"Can the user edit the title/description."},"viewInviteLinks":{"type":"boolean","description":"Can the user view the invite links of the collection."},"create":{"type":"boolean","description":"Can the user create spaces/collections in this collection."}},"required":["view","admin","viewInviteLinks","create"]}},"required":["object","id","title","organization","urls","defaultLevel","permissions"]},"CollectionTitle":{"type":"string","description":"Title of the collection","maxLength":50},"CollectionDescription":{"type":"string","description":"Description of the collection","minLength":0,"maxLength":100},"DefaultLevel":{"description":"Default level for a piece of content","oneOf":[{"$ref":"#/components/schemas/MemberRoleOrGuest"},{"type":"string","enum":["inherit"]}]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}},"ConflictError":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[409]},"message":{"type":"string"}},"required":["code","message"]}}}}}},"PreconditionFailedError":{"description":"PreconditionFailed","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[412]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/transfer":{"post":{"operationId":"transferCollection","summary":"Transfer a collection","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/collectionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"string","description":"The unique id of the target organization"}},"required":["organization"]}}}},"responses":{"200":{"description":"Collection transferred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"No matching Collection found for given ID","$ref":"#/components/responses/NotFoundError"},"409":{"description":"Transfer would not result in any update","$ref":"#/components/responses/ConflictError"},"412":{"description":"The collection cannot be moved.","$ref":"#/components/responses/PreconditionFailedError"}}}}}}
```

## GET /orgs/{organizationId}/collections

> List all collections

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collections","description":"Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n    The Collection object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"listPage":{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},"listLimit":{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"Collection":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"collection\"","enum":["collection"]},"id":{"type":"string","description":"Unique identifier for the collection"},"title":{"$ref":"#/components/schemas/CollectionTitle"},"description":{"$ref":"#/components/schemas/CollectionDescription"},"organization":{"type":"string","description":"ID of the organization owning this collection"},"parent":{"type":"string","description":"ID of the parent collection, if any"},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the collection in the API","format":"uri"},"app":{"type":"string","description":"URL of the collection in the application","format":"uri"}},"required":["app","location"]},"permissions":{"type":"object","description":"The set of permissions for the collection","properties":{"view":{"type":"boolean","description":"Can the user view the collection."},"admin":{"type":"boolean","description":"Can the user edit the title/description."},"viewInviteLinks":{"type":"boolean","description":"Can the user view the invite links of the collection."},"create":{"type":"boolean","description":"Can the user create spaces/collections in this collection."}},"required":["view","admin","viewInviteLinks","create"]}},"required":["object","id","title","organization","urls","defaultLevel","permissions"]},"CollectionTitle":{"type":"string","description":"Title of the collection","maxLength":50},"CollectionDescription":{"type":"string","description":"Description of the collection","minLength":0,"maxLength":100},"DefaultLevel":{"description":"Default level for a piece of content","oneOf":[{"$ref":"#/components/schemas/MemberRoleOrGuest"},{"type":"string","enum":["inherit"]}]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}}},"paths":{"/orgs/{organizationId}/collections":{"get":{"operationId":"listCollectionsInOrganizationById","summary":"List all collections","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"},{"name":"nested","in":"query","description":"If true, all nested collections will be listed","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}}}}]}}}}}}}}}
```

## POST /orgs/{organizationId}/collections

> Create a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collections","description":"Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n    The Collection object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"Collection":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"collection\"","enum":["collection"]},"id":{"type":"string","description":"Unique identifier for the collection"},"title":{"$ref":"#/components/schemas/CollectionTitle"},"description":{"$ref":"#/components/schemas/CollectionDescription"},"organization":{"type":"string","description":"ID of the organization owning this collection"},"parent":{"type":"string","description":"ID of the parent collection, if any"},"defaultLevel":{"$ref":"#/components/schemas/DefaultLevel"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the collection in the API","format":"uri"},"app":{"type":"string","description":"URL of the collection in the application","format":"uri"}},"required":["app","location"]},"permissions":{"type":"object","description":"The set of permissions for the collection","properties":{"view":{"type":"boolean","description":"Can the user view the collection."},"admin":{"type":"boolean","description":"Can the user edit the title/description."},"viewInviteLinks":{"type":"boolean","description":"Can the user view the invite links of the collection."},"create":{"type":"boolean","description":"Can the user create spaces/collections in this collection."}},"required":["view","admin","viewInviteLinks","create"]}},"required":["object","id","title","organization","urls","defaultLevel","permissions"]},"CollectionTitle":{"type":"string","description":"Title of the collection","maxLength":50},"CollectionDescription":{"type":"string","description":"Description of the collection","minLength":0,"maxLength":100},"DefaultLevel":{"description":"Default level for a piece of content","oneOf":[{"$ref":"#/components/schemas/MemberRoleOrGuest"},{"type":"string","enum":["inherit"]}]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}}},"paths":{"/orgs/{organizationId}/collections":{"post":{"operationId":"createCollection","summary":"Create a collection","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/organizationId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":50},"parent":{"type":"string","description":"ID of a parent collection"}}}}}},"responses":{"201":{"description":"Collection created","headers":{"Location":{"description":"API URL for the newly created collection","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}}}}}}
```