> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/developers/gitbook-api/api-reference/spaces.md).

# Spaces

Create, maintain, and remove content spaces.

Spaces are containers for your documentation or knowledge base content. Use this API to create new spaces, manage existing ones, and delete or archive spaces you no longer need.

## The Space object

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"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"},"type":{"type":"string","description":"Kind of space. Only set to `styleguide` for spaces holding a team's writing style guide; omitted for regular spaces.","enum":["styleguide"]},"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"},"previousGitSync":{"$ref":"#/components/schemas/PreviousGitSyncState"},"imports":{"description":"Import runs targeting this space, still running or ended recently, most recent first. Only returned when fetching a single space.\n","type":"array","items":{"$ref":"#/components/schemas/ContentImportRun"}},"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"},"message":{"type":"string","description":"Optional message to display when the expression evaluates to false."}},"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","zh-tw","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","fr-ca","es-mx","es-419"]},"GitSyncState":{"type":"object","properties":{"repoName":{"type":"string","description":"Repository name."},"installationStatus":{"$ref":"#/components/schemas/GitSyncInstallationStatus"},"installationProvider":{"$ref":"#/components/schemas/GitSyncProvider"},"integration":{"type":"string","deprecated":true,"description":"The integration name providing the Git Sync."},"installationId":{"type":"string","description":"The ID of the Git Sync installation."},"parentInstallationId":{"type":"string","description":"The ID of the parent Git Sync installation, if any."},"url":{"type":"string","description":"The URL to the repository tree, used when rendering public content."},"installationProjectDirectory":{"type":"string","description":"Directory in the repository this content syncs from, resolved against the parent installation when the installation is managed by a site. Absent when the content syncs from the root of the repository."},"operation":{"type":"object","description":"The latest operation on the Git Sync installation.","properties":{"state":{"$ref":"#/components/schemas/GitSyncOperationState"},"direction":{"$ref":"#/components/schemas/GitSyncOperationDirection"},"startedAt":{"$ref":"#/components/schemas/Timestamp"},"endedAt":{"$ref":"#/components/schemas/Timestamp"},"error":{"type":"string","description":"Why the operation failed, when it did."},"errorAction":{"$ref":"#/components/schemas/GitSyncOperationErrorAction"}},"required":["state","direction","startedAt"]},"operationTimeout":{"type":"integer","description":"How long an operation is allowed to run before it is terminated (in milliseconds)."},"updatedAt":{"description":"When the Git provider details were last updated","$ref":"#/components/schemas/Timestamp"}},"required":["installationId","installationProvider","installationStatus"]},"GitSyncInstallationStatus":{"type":"string","enum":["unauthenticated","active","pending"]},"GitSyncProvider":{"type":"string","description":"The provider of the Git Sync installation.","enum":["github","gitlab","github-legacy"]},"GitSyncOperationState":{"type":"string","description":"* `running`: The operation is still running\n* `failure`: The operation failed\n* `success`: The operation was successful\n* `timeout`: The operation timed out\n","enum":["running","failure","success","timeout"]},"GitSyncOperationDirection":{"type":"string","enum":["export","import"]},"GitSyncOperationErrorAction":{"type":"object","description":"An action the user can take to resolve a failed Git Sync operation.","properties":{"label":{"type":"string","description":"Label for the action."},"url":{"type":"string","format":"uri","description":"URL where the user can resolve the failure."}},"required":["label","url"]},"PreviousGitSyncState":{"type":"object","description":"What is still known about a target's Git Sync after its installation was removed. Never returned alongside `gitSync`, which describes a live installation.","required":["url"],"properties":{"url":{"type":"string","description":"The URL to the directory of the repository tree the content synced with before its Git Sync installation was removed, at the branch it synced."}}},"ContentImportRun":{"type":"object","properties":{"object":{"description":"Type of Object, always equals to \"import-run\"","type":"string","enum":["import-run"]},"id":{"description":"Unique ID of the import","type":"string"},"startedAt":{"description":"Date when the import has started","$ref":"#/components/schemas/Timestamp"},"completedAt":{"description":"Filled when the imported is in status \"completed\"","$ref":"#/components/schemas/Timestamp"},"createdAt":{"description":"Date when the import was requested","$ref":"#/components/schemas/Timestamp"},"updatedAt":{"description":"Date when the import was last updated","$ref":"#/components/schemas/Timestamp"},"status":{"description":"Status of the import","type":"string","enum":["pending","in-progress","completed","failed","cancelled"]},"reason":{"description":"Reason for the import failure when `status` is `failed`.","type":"string"},"source":{"description":"Where the content is imported from.","$ref":"#/components/schemas/ContentImportSource"},"target":{"description":"Where the content is imported into.","$ref":"#/components/schemas/ContentImportTarget"},"site":{"description":"ID of the site the target space belongs to, when it belongs to exactly one.","type":"string"},"createdBy":{"description":"ID of the user who started the import.","type":"string"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"description":"URL of the import run in the API","type":"string","format":"uri"}},"required":["location"]},"pages":{"description":"Pages included in the import","type":"array","items":{"type":"object","properties":{"id":{"description":"ID of page","type":"string"},"sourceURL":{"description":"Source URL where the page has been imported from","type":"string"},"type":{"description":"Type of page","type":"string","enum":["page","folder"]},"status":{"description":"Status of the page","type":"string","enum":["complete","pending"]}},"required":["id","type","status"]}}},"required":["id","status"]},"ContentImportSource":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["website"]},"url":{"$ref":"#/components/schemas/URL"}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["file"]},"files":{"description":"Files to import","type":"array","maxItems":50,"items":{"description":"Key of file","type":"string"}}},"required":["type","files"]}]},"ContentImportTarget":{"type":"object","properties":{"space":{"type":"string","description":"ID of the space to import in"},"changeRequest":{"type":"string","description":"ID of the change request to import in"},"page":{"type":"string","description":"ID of the page to import in"}},"required":["space"]},"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"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/spaces.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.