The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

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-22T17:36:02.423Z",
  "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
all ofoptional
get
GET /v1/orgs/{organizationId}/sites HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

{
  "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-22T17:36:02.423Z",
      "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
objectoptional
post
POST /v1/orgs/{organizationId}/sites HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "type": "basic",
  "title": "text",
  "visibility": "public",
  "spaces": [
    "text"
  ]
}
201

Site created

{
  "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-22T17:36:02.423Z",
  "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 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
objectoptional
get
GET /v1/orgs/{organizationId}/sites/{siteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "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-22T17:36:02.423Z",
  "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
delete
DELETE /v1/orgs/{organizationId}/sites/{siteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
205

Site has been deleted

No Content

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
objectoptional
patch
PATCH /v1/orgs/{organizationId}/sites/{siteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "title": "text",
  "visibility": "public",
  "basename": "text",
  "adaptiveContent": {
    "enabled": true
  },
  "defaultSiteSpace": "text",
  "defaultSiteSection": "text",
  "proxy": "text"
}
200

OK

{
  "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-22T17:36:02.423Z",
  "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
objectoptional
get
GET /v1/orgs/{organizationId}/sites/{siteId}/adaptive-schema HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "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-22T17:36:02.423Z"
}

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
objectoptional
put
PUT /v1/orgs/{organizationId}/sites/{siteId}/adaptive-schema HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 207

{
  "jsonSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "text",
    "type": "object",
    "properties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "type": "boolean",
        "description": "text"
      }
    },
    "additionalProperties": false
  }
}
{
  "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-22T17:36:02.423Z"
}

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
objectoptional
get
GET /v1/orgs/{organizationId}/sites/{siteId}/published HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "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-22T17:36:02.423Z",
    "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-22T17:36:02.423Z",
              "updatedAt": "2025-04-22T17:36:02.423Z",
              "deletedAt": "2025-04-22T17:36:02.423Z",
              "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-22T17:36:02.423Z"
              },
              "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
one ofoptional

User needs to checkout in order to publish the site.

post
POST /v1/orgs/{organizationId}/sites/{siteId}/publish HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Site published successfully

{
  "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-22T17:36:02.423Z",
  "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"
  }
}

Unpublish a site

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
application/json
objectoptional
post
POST /v1/orgs/{organizationId}/sites/{siteId}/unpublish HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Site unpublished successfully

{
  "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-22T17:36:02.423Z",
  "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"
  }
}

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
all ofoptional
post
POST /v1/orgs/{organizationId}/sites/{siteId}/search HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "query": "text",
  "scope": {
    "mode": "default",
    "includedSiteSpaces": [
      "text"
    ]
  }
}
200

OK

{
  "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?