Docs sites

Manage your published docs sites.

The Docs Sites API lets you programmatically manage published documentation sites within your organization. You can list and update all sites created under a specific organization, making it easy to audit or interact with site metadata at scale.

The Site object

Attributes

objectstring · enumrequiredAvailable options:

idstringrequired

Unique identifier of the site

typestring · enumrequired

The type of the site

Available options:

titlestring · min: 2 · max: 128required

Title of the site

hostnamestring · max: 512optional

Custom hostname for the site, for e.g. docs.mycompany.com

Pattern: ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?[.]){2,}[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$

basenamestring · min: 1 · max: 100optional

Basename for the site. For e.g. api

proxyobjectoptional

visibilitystring · enumrequired

The visibility setting of the site determines the audience of the site.

public: Anyone can access the site, and the site is indexed by search engines.
unlisted: Anyone can access the site, and the site is not indexed by search engines
share-link: Anyone with a secret token in the url can access the site.
visitor-auth: Anyone authenticated through a JWT token can access the site.

Available options:

publishedbooleanrequired

Whether the site is live or not. If true, the site is accessible to the audience defined by the visibility setting.

siteSpacesnumberrequired

createdAtstring · date-timerequired

adaptiveContentobjectoptional

adsone ofoptional

featuresone of[]required

A list of all premium features enabled on this site. For each feature we list the plan they belong to and whether the feature is frozen. A frozen feature is still enabled but cannot be changed or modified.

urlsobjectrequired

URLs associated with the object

The Site object

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-16T23:15:52.326Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

List all sites

get

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

spacestringoptional

Identifier of the space to filter the sites by

titlestringoptional

Filter sites by their title

publishedbooleanoptional

Filter sites by their published status

typestring · enum[]optional

Filter by site type

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site",
      "id": "text",
      "type": "basic",
      "title": "text",
      "hostname": "text",
      "basename": "text",
      "proxy": {
        "origin": "text",
        "target": "text"
      },
      "visibility": "public",
      "published": true,
      "siteSpaces": 1,
      "createdAt": "2025-04-16T23:15:52.326Z",
      "adaptiveContent": {
        "enabled": true
      },
      "ads": {
        "status": "pending",
        "submittable": true
      },
      "features": [
        {
          "id": "sites-sections",
          "plan": "basic",
          "frozen": true
        }
      ],
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "published": "https://example.com"
      }
    }
  ]
}

Create a site

post

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

typestring · enumoptional

The type of the site, defaults to Basic

Available options:

titlestring · min: 2 · max: 128optional

Title of the site

visibilitystring · enumoptional

The visibility setting of the site determines the audience of the site.

public: Anyone can access the site, and the site is indexed by search engines.
unlisted: Anyone can access the site, and the site is not indexed by search engines
share-link: Anyone with a secret token in the url can access the site.
visitor-auth: Anyone authenticated through a JWT token can access the site.

Available options:

spacesone ofoptional

ID of spaces to be added to the site

Create a new space associated to the site

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "basic",
    "title": "text",
    "visibility": "public",
    "spaces": [
      "text"
    ]
  }'

201

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-16T23:15:52.326Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site created

Get a site by its ID

get

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-16T23:15:52.326Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Delete a site

delete

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

205

No Content

Site has been deleted

Update a site

patch

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

titlestring · min: 2 · max: 128optional

Title of the site

visibilitystring · enumoptional

The visibility setting of the site determines the audience of the site.

public: Anyone can access the site, and the site is indexed by search engines.
unlisted: Anyone can access the site, and the site is not indexed by search engines
share-link: Anyone with a secret token in the url can access the site.
visitor-auth: Anyone authenticated through a JWT token can access the site.

Available options:

basenamestring · min: 1 · max: 100optional

Basename for the site. For e.g. api

adaptiveContentobjectoptional

defaultSiteSpacestringoptional

ID of the site-space to be used as the default at the root level. If site has sections, this will mark the default site space in the site's default section.

defaultSiteSectionstringoptional

ID of the site-section to be used as the default.

proxyone ofoptional

Configure a proxy URL for a site. For example, you can use it to host the site on a subdirectory of your domain like https://company.com/docs. Use null to remove the proxy.

Proxy URL for the site, for e.g. company.com/docs or www.company.com/developer/docs etc.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "visibility": "public",
    "basename": "text",
    "adaptiveContent": {
      "enabled": true
    },
    "defaultSiteSpace": "text",
    "defaultSiteSection": "text",
    "proxy": "text"
  }'

200

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-16T23:15:52.326Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Get the JSON schema describing the attributes expected for an Adaptive content site visitor.

get

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/adaptive-schema' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

{
  "object": "site-adaptive-schema",
  "jsonSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "text",
    "type": "object",
    "properties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "type": "boolean",
        "description": "text"
      }
    },
    "additionalProperties": false
  },
  "updatedAt": "2025-04-16T23:15:52.326Z"
}

The JSON schema that defines the attributes expected from a visitor of the Adaptive content site.

Create or update the JSON schema of the attributes expected for an Adaptive content site visitor.

put

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

jsonSchemaobjectrequired

The JSON schema to set on the site.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/adaptive-schema' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "$id": "text",
      "type": "object",
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "boolean",
          "description": "text"
        }
      },
      "additionalProperties": false
    }
  }'

200

201

400

default

{
  "object": "site-adaptive-schema",
  "jsonSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "text",
    "type": "object",
    "properties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "type": "boolean",
        "description": "text"
      }
    },
    "additionalProperties": false
  },
  "updatedAt": "2025-04-16T23:15:52.326Z"
}

The site adaptive schema has been updated.

Get a published site

get

Get the complete profile of a site in an organization to provide the published experience. It includes site, customization, structure, integration scripts etc.

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

shareKeystringoptional

For sites published via share-links, the share key is useful to resolve published URLs.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/published' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

{
  "object": "published-content-site",
  "site": {
    "object": "site",
    "id": "text",
    "type": "basic",
    "title": "text",
    "hostname": "text",
    "basename": "text",
    "proxy": {
      "origin": "text",
      "target": "text"
    },
    "visibility": "public",
    "published": true,
    "siteSpaces": 1,
    "createdAt": "2025-04-16T23:15:52.326Z",
    "adaptiveContent": {
      "enabled": true
    },
    "ads": {
      "status": "pending",
      "submittable": true
    },
    "features": [
      {
        "id": "sites-sections",
        "plan": "basic",
        "frozen": true
      }
    ],
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com"
    }
  },
  "structure": {
    "type": "sections",
    "structure": [
      {
        "object": "site-section",
        "id": "text",
        "title": "text",
        "description": "text",
        "default": true,
        "path": "text",
        "condition": "text",
        "sectionGroup": "text",
        "siteSpaces": [
          {
            "object": "site-space",
            "id": "text",
            "path": "text",
            "section": "text",
            "space": {
              "object": "space",
              "id": "text",
              "title": "text",
              "emoji": "🎉",
              "visibility": "public",
              "createdAt": "2025-04-16T23:15:52.326Z",
              "updatedAt": "2025-04-16T23:15:52.326Z",
              "deletedAt": "2025-04-16T23:15:52.326Z",
              "editMode": "live",
              "urls": {
                "location": "https://example.com",
                "app": "https://example.com",
                "published": "https://example.com",
                "public": "https://example.com",
                "icon": "https://example.com"
              },
              "organization": "text",
              "parent": "text",
              "gitSync": {
                "repoName": "text",
                "installationProvider": "github",
                "integration": "text",
                "url": "text",
                "updatedAt": "2025-04-16T23:15:52.326Z"
              },
              "visitorAuth": {
                "backend": "custom"
              },
              "revision": "text",
              "defaultLevel": "admin",
              "comments": 1,
              "changeRequests": 1,
              "changeRequestsOpen": 1,
              "changeRequestsDraft": 1,
              "permissions": {
                "access": true,
                "admin": true,
                "edit": true,
                "comment": true,
                "merge": true,
                "review": true
              }
            },
            "title": "text",
            "default": true,
            "condition": "text",
            "hasAdvancedCustomizationFeature": true,
            "urls": {
              "published": "https://example.com"
            }
          }
        ],
        "urls": {
          "published": "https://example.com"
        },
        "icon": "gear"
      }
    ]
  },
  "customizations": {
    "site": {
      "title": "text",
      "styling": {
        "theme": "clean",
        "primaryColor": {
          "light": "text",
          "dark": "text"
        },
        "tint": {
          "color": {
            "light": "text",
            "dark": "text"
          }
        },
        "infoColor": {
          "light": "text",
          "dark": "text"
        },
        "successColor": {
          "light": "text",
          "dark": "text"
        },
        "warningColor": {
          "light": "text",
          "dark": "text"
        },
        "dangerColor": {
          "light": "text",
          "dark": "text"
        },
        "corners": "straight",
        "links": "default",
        "font": "ABCFavorit",
        "icons": "regular",
        "sidebar": {
          "background": "default",
          "list": "default"
        },
        "search": "prominent"
      },
      "internationalization": {
        "locale": "en"
      },
      "favicon": {
        "icon": {
          "light": "https://example.com",
          "dark": "https://example.com"
        }
      },
      "header": {
        "logo": {
          "light": "https://example.com",
          "dark": "https://example.com"
        },
        "links": [
          {
            "title": "text",
            "style": "link",
            "to": {
              "kind": "file",
              "file": "text"
            },
            "links": [
              {
                "title": "text",
                "to": {
                  "kind": "file",
                  "file": "text"
                }
              }
            ]
          }
        ]
      },
      "footer": {
        "logo": {
          "light": "https://example.com",
          "dark": "https://example.com"
        },
        "groups": [
          {
            "title": "text",
            "links": [
              {
                "title": "text",
                "to": {
                  "kind": "file",
                  "file": "text"
                }
              }
            ]
          }
        ],
        "copyright": "text"
      },
      "announcement": {
        "enabled": true,
        "message": "text",
        "link": {
          "title": "text",
          "to": {
            "kind": "file",
            "file": "text"
          }
        },
        "style": "info"
      },
      "themes": {
        "default": "light",
        "toggeable": true
      },
      "pdf": {
        "enabled": true
      },
      "feedback": {
        "enabled": true
      },
      "aiSearch": {
        "enabled": true
      },
      "ai": {
        "pageLinkSummaries": {
          "enabled": true
        }
      },
      "advancedCustomization": {
        "enabled": true
      },
      "git": {
        "showEditLink": true
      },
      "pagination": {
        "enabled": true
      },
      "trademark": {
        "enabled": true
      },
      "privacyPolicy": {
        "url": "https://example.com"
      },
      "socialPreview": {
        "url": "https://example.com"
      },
      "insights": {
        "trackingCookie": true
      }
    },
    "siteSpaces": {
      "ANY_ADDITIONAL_PROPERTY": {
        "title": "text",
        "styling": {
          "theme": "clean",
          "primaryColor": {
            "light": "text",
            "dark": "text"
          },
          "tint": {
            "color": {
              "light": "text",
              "dark": "text"
            }
          },
          "infoColor": {
            "light": "text",
            "dark": "text"
          },
          "successColor": {
            "light": "text",
            "dark": "text"
          },
          "warningColor": {
            "light": "text",
            "dark": "text"
          },
          "dangerColor": {
            "light": "text",
            "dark": "text"
          },
          "corners": "straight",
          "links": "default",
          "font": "ABCFavorit",
          "icons": "regular",
          "sidebar": {
            "background": "default",
            "list": "default"
          },
          "search": "prominent"
        },
        "internationalization": {
          "locale": "en"
        },
        "favicon": {
          "icon": {
            "light": "https://example.com",
            "dark": "https://example.com"
          }
        },
        "header": {
          "logo": {
            "light": "https://example.com",
            "dark": "https://example.com"
          },
          "links": [
            {
              "title": "text",
              "style": "link",
              "to": {
                "kind": "file",
                "file": "text"
              },
              "links": [
                {
                  "title": "text",
                  "to": {
                    "kind": "file",
                    "file": "text"
                  }
                }
              ]
            }
          ]
        },
        "footer": {
          "logo": {
            "light": "https://example.com",
            "dark": "https://example.com"
          },
          "groups": [
            {
              "title": "text",
              "links": [
                {
                  "title": "text",
                  "to": {
                    "kind": "file",
                    "file": "text"
                  }
                }
              ]
            }
          ],
          "copyright": "text"
        },
        "announcement": {
          "enabled": true,
          "message": "text",
          "link": {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          },
          "style": "info"
        },
        "themes": {
          "default": "light",
          "toggeable": true
        },
        "pdf": {
          "enabled": true
        },
        "feedback": {
          "enabled": true
        },
        "aiSearch": {
          "enabled": true
        },
        "ai": {
          "pageLinkSummaries": {
            "enabled": true
          }
        },
        "advancedCustomization": {
          "enabled": true
        },
        "git": {
          "showEditLink": true
        },
        "pagination": {
          "enabled": true
        },
        "trademark": {
          "enabled": true
        },
        "privacyPolicy": {
          "url": "https://example.com"
        },
        "socialPreview": {
          "url": "https://example.com"
        },
        "insights": {
          "trackingCookie": true
        }
      }
    }
  },
  "scripts": [
    {
      "script": "https://example.com",
      "contentSecurityPolicy": "text",
      "cookies": true
    }
  ]
}

Publish a site

post

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/publish' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-16T23:15:52.326Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site published successfully

Unpublish a site

post

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/unpublish' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-16T23:15:52.326Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site unpublished successfully

Search in a site

post

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Body

all ofoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/search' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "text",
    "scope": {
      "mode": "default",
      "includedSiteSpaces": [
        "text"
      ]
    }
  }'

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "title": "text",
      "pages": [
        {
          "id": "text",
          "title": "text",
          "path": "text",
          "sections": [
            {
              "id": "text",
              "title": "text",
              "path": "text",
              "body": "text",
              "urls": {
                "app": "https://example.com"
              }
            }
          ],
          "urls": {
            "app": "https://example.com"
          }
        }
      ]
    }
  ]
}

Was this helpful?

The Site object

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show available items

Show child attributes

The Site object

List all sites

Show child attributes

Create a site

Show string

Show child attributes

Get a site by its ID

Delete a site

Update a site

Show child attributes

Show child attributes

Show child attributes

Get the JSON schema describing the attributes expected for an Adaptive content site visitor.

Create or update the JSON schema of the attributes expected for an Adaptive content site visitor.

Show child attributes

Get a published site

Publish a site

Unpublish a site

Search in a site

Show child attributes

Show child attributes