Content

Content in GitBook is the entity for content on a page.

GET the primary content in a space

Get the current primary content revision for a space

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/content

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Query parameters

Response

200default

OK

Body

application/json

Revision (one of)

RevisionTypeEdits (all of)RevisionTypeMerge (all of)RevisionTypeRollback (all of)RevisionTypeUpdate (all of)RevisionTypeComputed (all of)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/content', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "object": "revision",
  "id": "text",
  "parents": [
    "text"
  ],
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-01-15T12:04:45.811Z",
      "updatedAt": "2025-01-15T12:04:45.811Z",
      "markdown": "text",
      "type": "document",
      "urls": {
        "app": "https://example.com"
      },
      "slug": "text",
      "path": "text",
      "description": "text",
      "documentId": "text",
      "pages": [],
      "git": {
        "oid": "text",
        "path": "text"
      },
      "layout": {
        "cover": false,
        "coverSize": "hero",
        "title": false,
        "description": false,
        "tableOfContents": false,
        "outline": false,
        "pagination": false
      },
      "cover": {
        "ref": {
          "kind": "file",
          "file": "text"
        },
        "yPos": 0
      },
      "hidden": false,
      "noIndex": false,
      "noRobotsIndex": false,
      "computed": {
        "integration": "text",
        "source": "text",
        "props": {},
        "dependsOn": [
          {
            "kind": "space",
            "space": "text"
          }
        ]
      }
    }
  ],
  "files": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 0,
      "dimensions": {
        "width": 0,
        "height": 0
      },
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "reusableContents": [
    {
      "id": "text",
      "title": "text",
      "document": "text",
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "createdAt": "2025-01-15T12:04:45.811Z",
  "git": {
    "oid": "text",
    "message": "text",
    "createdByGitBook": false,
    "url": "text",
    "ref": "text"
  },
  "urls": {
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com"
  },
  "type": "edits"
}

GET files for the primary content in a space

List all files for the main revision content of a space

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/content/files

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Query parameters

Response

200default

OK

Body

application/json

nextobject

countnumber

Total count of objects in the list

items*array of RevisionFile (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/content/files', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "next": {
    "page": "text"
  },
  "count": 0,
  "items": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 0,
      "dimensions": {
        "width": 0,
        "height": 0
      },
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ]
}

GET a page from the primary content in a space by ID

Get a page by its ID in the primary content.

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/content/page/{pageId}

Authorization

user

Path parameters

spaceId*string

The unique id of the space

pageId*string

The unique id of the page

Query parameters

Response

200default

OK

Body

application/json

RevisionPage (one of)

RevisionPageDocument (all of)RevisionPageGroup (all of)RevisionPageLink (all of)RevisionPageComputed (all of)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/content/page/{pageId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-01-15T12:04:45.811Z",
  "updatedAt": "2025-01-15T12:04:45.811Z",
  "markdown": "text",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "slug": "text",
  "path": "text",
  "description": "text",
  "documentId": "text",
  "pages": [],
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "cover": false,
    "coverSize": "hero",
    "title": false,
    "description": false,
    "tableOfContents": false,
    "outline": false,
    "pagination": false
  },
  "cover": {
    "ref": {
      "kind": "file",
      "file": "text"
    },
    "yPos": 0
  },
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": {
    "integration": "text",
    "source": "text",
    "props": {},
    "dependsOn": [
      {
        "kind": "space",
        "space": "text"
      }
    ]
  }
}

GET a page from the primary content in a space by path

Get a page by its path in the primary content.

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/content/path/{pagePath}

Authorization

user

Path parameters

spaceId*string

The unique id of the space

pagePath*string

The path of the page in the revision.

Query parameters

Response

200default

OK

Body

application/json

one of

RevisionPageDocument (all of)RevisionPageGroup (all of)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/content/path/{pagePath}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-01-15T12:04:45.811Z",
  "updatedAt": "2025-01-15T12:04:45.811Z",
  "markdown": "text",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "slug": "text",
  "path": "text",
  "description": "text",
  "documentId": "text",
  "pages": [],
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "cover": false,
    "coverSize": "hero",
    "title": false,
    "description": false,
    "tableOfContents": false,
    "outline": false,
    "pagination": false
  },
  "cover": {
    "ref": {
      "kind": "file",
      "file": "text"
    },
    "yPos": 0
  },
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": {
    "integration": "text",
    "source": "text",
    "props": {},
    "dependsOn": [
      {
        "kind": "space",
        "space": "text"
      }
    ]
  }
}

POST content to a space

Import content in a space.

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/content/import

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Body

application/json

url*string

URL of the content to import.

source*ImportContentSource (enum)

websitedocxmarkdownhtmlzipconfluencegithub-wikidropbox-papernotionquipgoogle-docsopen-api

Response

201default

Content imported in a new revision

Headers

Body

application/json

revision*string

ID of the newly created revision.

importedResources*number

How many resources were imported

totalResources*number

How many resources were processed

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/content/import', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "url": "text",
      "source": "website"
    }),
});
const data = await response.json();

Response

201default

{
  "revision": "text",
  "importedResources": 0,
  "totalResources": 0
}

POSTcontent to a page by ID

Import external content into a page by its ID.

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/content/page/{pageId}/import

Authorization

user

Path parameters

spaceId*string

The unique id of the space

pageId*string

The unique id of the page

Body

application/json

url*string

URL of the content to import.

source*ImportContentSource (enum)

websitedocxmarkdownhtmlzipconfluencegithub-wikidropbox-papernotionquipgoogle-docsopen-api

Response

201default

Content imported in a new revision

Headers

Body

application/json

revision*string

ID of the newly created revision.

importedResources*number

How many resources were imported

totalResources*number

How many resources were processed

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/content/page/{pageId}/import', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "url": "text",
      "source": "website"
    }),
});
const data = await response.json();

Response

201default

{
  "revision": "text",
  "importedResources": 0,
  "totalResources": 0
}

Git Repositories

GitBook provides support for importing from Git repositories. However, if you're using GitHub or GitLab, we recommend using our integrations instead.

Import a Git repository

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/git/import

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Body

application/json

url*string

URL of the Git repository to import. It can contain basic auth credentials.

ref*string

Git ref to import in the format "refs/heads/main"

repoCacheIDstring

Unique identifier to use to cache the Git repository across multiple operations.

repoTreeURLstring

URL to use as a prefix for external file references.

repoCommitURLstring

URL to use as a prefix for the commit URL.

repoProjectDirectorystring

Path to a root directory for the project in the repository.

timestampTimestamp (string (date-time))

forceboolean

standaloneboolean

If true, the import will generate a revision without updating the space primary content.

gitInfoUpdateSpaceGitInfo (object)

Update metadata about the Git provider on the space

Response

204default

Operation to import the repository has been started.

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/git/import', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "url": "text",
      "ref": "text"
    }),
});
const data = await response.json();

Response

default

{
  "error": {
    "code": 0,
    "message": "text"
  }
}