Content

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

Last updated 8 days ago

Was this helpful?

Get the current primary content revision for a space

get

/spaces/{spaceId}/content

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Query parameters

metadataboolean

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean

If false is passed, content will not be computed

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "id": "text",
  "createdAt": "2025-02-15T15:42:32.645Z",
  "git": {
    "oid": "text",
    "message": "text",
    "createdByGitBook": true,
    "url": "text",
    "ref": "text"
  },
  "object": "revision",
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-02-15T15:42:32.645Z",
      "updatedAt": "2025-02-15T15:42:32.645Z",
      "markdown": "text",
      "description": "text",
      "git": {
        "oid": "text",
        "path": "text"
      },
      "layout": {
        "coverSize": "hero",
        "cover": true,
        "title": true,
        "description": true,
        "tableOfContents": true,
        "outline": true,
        "pagination": true
      },
      "cover": {
        "ref": {
          "file": "text",
          "kind": "file"
        },
        "yPos": 1
      },
      "kind": "sheet",
      "type": "document",
      "slug": "text",
      "path": "text",
      "documentId": "text",
      "hidden": false,
      "noIndex": false,
      "noRobotsIndex": false,
      "computed": "[Circular Reference]",
      "urls": {
        "app": "https://example.com"
      },
      "pages": "[Circular Reference]"
    }
  ],
  "files": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 1,
      "git": {
        "oid": "text",
        "path": "text"
      },
      "dimensions": {
        "width": 1,
        "height": 1
      }
    }
  ],
  "reusableContents": [
    {
      "id": "text",
      "title": "text",
      "document": "text",
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "parents": [
    "text"
  ],
  "urls": {
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com"
  },
  "type": "edits"
}

List all files for the main revision content of a space

get

/spaces/{spaceId}/content/files

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber

The number of results per page

metadataboolean

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean

If false is passed, content will not be computed

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/files' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

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

Get a page by its ID in the primary content.

get

/spaces/{spaceId}/content/page/{pageId}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

pageIdstringrequired

The unique id of the page

Query parameters

formatenum

Output format for the content.

Options: document, markdown

metadataboolean

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean

If false is passed, content will not be computed

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/page/{pageId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-02-15T15:42:32.645Z",
  "updatedAt": "2025-02-15T15:42:32.645Z",
  "markdown": "text",
  "description": "text",
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "coverSize": "hero",
    "cover": true,
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "file": "text",
      "kind": "file"
    },
    "yPos": 1
  },
  "kind": "sheet",
  "type": "document",
  "slug": "text",
  "path": "text",
  "documentId": "text",
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": "[Circular Reference]",
  "urls": {
    "app": "https://example.com"
  },
  "pages": "[Circular Reference]"
}

Get a page by its path in the primary content.

get

/spaces/{spaceId}/content/path/{pagePath}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

pagePathstringrequired

The path of the page in the revision.

Query parameters

formatenum

Output format for the content.

Options: document, markdown

metadataboolean

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean

If false is passed, content will not be computed

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/path/{pagePath}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-02-15T15:42:32.645Z",
  "updatedAt": "2025-02-15T15:42:32.645Z",
  "markdown": "text",
  "description": "text",
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "coverSize": "hero",
    "cover": true,
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "file": "text",
      "kind": "file"
    },
    "yPos": 1
  },
  "kind": "sheet",
  "type": "document",
  "slug": "text",
  "path": "text",
  "documentId": "text",
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": "[Circular Reference]",
  "urls": {
    "app": "https://example.com"
  },
  "pages": "[Circular Reference]"
}

Import content in a space.

post

/spaces/{spaceId}/content/import

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Body

sourceenumrequired

Options: website, docx, markdown, html, zip, confluence, github-wiki, dropbox-paper, notion, quip, google-docs, open-api

urlstring urirequired

URL of the content to import.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/import' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"source":"website","url":"https://example.com"}'

201

default

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

Content imported in a new revision

Import external content into a page by its ID.

post

/spaces/{spaceId}/content/page/{pageId}/import

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

pageIdstringrequired

The unique id of the page

Body

sourceenumrequired

Options: website, docx, markdown, html, zip, confluence, github-wiki, dropbox-paper, notion, quip, google-docs, open-api

urlstring urirequired

URL of the content to import.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/page/{pageId}/import' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"source":"website","url":"https://example.com"}'

201

default

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

Content imported in a new revision

Import a Git repository

post

/spaces/{spaceId}/git/import

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Body

forceboolean

urlstringrequired

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

refstringrequired

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.

timestampstring date-time

The timestamp of the event that triggered this import. It ensures that Git sync import and export operations are executed in the same order on GitBook and on the remote repository.

standaloneboolean

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

gitInfoobject

Optional metadata to store on the space about the Git provider

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/git/import' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"url":"text","ref":"text","gitInfo":{"provider":"github"}}'

204

default

No body

Operation to import the repository has been started.