# Custom fonts

Upload and manage custom fonts for branding or aesthetic purposes. Once added, fonts can be applied to your spaces or sites to achieve a unique look.

## The CustomizationFontDefinition object

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"CustomizationFontDefinition":{"allOf":[{"$ref":"#/components/schemas/CustomizationFontDefinitionInput"},{"type":"object","properties":{"permissions":{"type":"object","description":"The set of permissions for the font definition","properties":{"edit":{"type":"boolean","description":"Can the user edit the font definition"}},"required":["edit"]}},"required":["permissions"]}]},"CustomizationFontDefinitionInput":{"type":"object","description":"Defines a font family along with its various font-face declarations for use in CSS '@font-face' rules.","properties":{"id":{"type":"string","description":"A globally unique identifier for the font definition."},"custom":{"type":"boolean","description":"Whether the font is a custom font. If false, this font is provided by GitBook."},"fontFamily":{"$ref":"#/components/schemas/FontFamily"},"fontFaces":{"type":"array","description":"A list of font-face definitions, specifying variations such as weight and style.","items":{"$ref":"#/components/schemas/FontFace"},"minItems":1}},"required":["id","custom","fontFamily","fontFaces"]},"FontFamily":{"type":"string","description":"The human-readable font-family name used in CSS (e.g., \"Open Sans\", \"Playfair Display\").","minLength":1,"maxLength":50},"FontFace":{"type":"object","description":"A single font-face declaration specifying the weight and source files for a particular variation of the font.","properties":{"weight":{"$ref":"#/components/schemas/FontWeight"},"sources":{"type":"array","description":"Font source files provided in supported formats (e.g., woff2, woff).","items":{"$ref":"#/components/schemas/FontSource"},"minItems":1}},"required":["weight","sources"]},"FontWeight":{"type":"integer","description":"Numeric representation of the font weight (400=regular, 500=medium, 700=bold, 900=black).","minimum":1,"maximum":1000},"FontSource":{"type":"object","description":"A font file referenced within a font-face declaration, specifying the file's location and format.","properties":{"url":{"description":"The absolute or relative URL pointing to the font file.","$ref":"#/components/schemas/URL"},"format":{"type":"string","description":"The format of the font file. Prefer 'woff2' for modern browsers.","enum":["woff2","woff"]}},"required":["url"]},"URL":{"type":"string","format":"uri","maxLength":2048}}}}
```

## GET /orgs/{organizationId}/fonts

> List all custom fonts

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"custom-fonts","description":"Upload and manage custom fonts for branding or aesthetic purposes. Once added, fonts can be applied to your spaces or sites to achieve a unique look.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomizationFontDefinition\" grouped=\"false\" %}\n    The CustomizationFontDefinition object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user-internal":[]}],"components":{"securitySchemes":{"user-internal":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"CustomizationFontDefinition":{"allOf":[{"$ref":"#/components/schemas/CustomizationFontDefinitionInput"},{"type":"object","properties":{"permissions":{"type":"object","description":"The set of permissions for the font definition","properties":{"edit":{"type":"boolean","description":"Can the user edit the font definition"}},"required":["edit"]}},"required":["permissions"]}]},"CustomizationFontDefinitionInput":{"type":"object","description":"Defines a font family along with its various font-face declarations for use in CSS '@font-face' rules.","properties":{"id":{"type":"string","description":"A globally unique identifier for the font definition."},"custom":{"type":"boolean","description":"Whether the font is a custom font. If false, this font is provided by GitBook."},"fontFamily":{"$ref":"#/components/schemas/FontFamily"},"fontFaces":{"type":"array","description":"A list of font-face definitions, specifying variations such as weight and style.","items":{"$ref":"#/components/schemas/FontFace"},"minItems":1}},"required":["id","custom","fontFamily","fontFaces"]},"FontFamily":{"type":"string","description":"The human-readable font-family name used in CSS (e.g., \"Open Sans\", \"Playfair Display\").","minLength":1,"maxLength":50},"FontFace":{"type":"object","description":"A single font-face declaration specifying the weight and source files for a particular variation of the font.","properties":{"weight":{"$ref":"#/components/schemas/FontWeight"},"sources":{"type":"array","description":"Font source files provided in supported formats (e.g., woff2, woff).","items":{"$ref":"#/components/schemas/FontSource"},"minItems":1}},"required":["weight","sources"]},"FontWeight":{"type":"integer","description":"Numeric representation of the font weight (400=regular, 500=medium, 700=bold, 900=black).","minimum":1,"maximum":1000},"FontSource":{"type":"object","description":"A font file referenced within a font-face declaration, specifying the file's location and format.","properties":{"url":{"description":"The absolute or relative URL pointing to the font file.","$ref":"#/components/schemas/URL"},"format":{"type":"string","description":"The format of the font file. Prefer 'woff2' for modern browsers.","enum":["woff2","woff"]}},"required":["url"]},"URL":{"type":"string","format":"uri","maxLength":2048}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/orgs/{organizationId}/fonts":{"get":{"operationId":"listCustomFonts","summary":"List all custom fonts","tags":["custom-fonts"],"parameters":[{"$ref":"#/components/parameters/organizationId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomizationFontDefinition"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```

## PUT /orgs/{organizationId}/fonts

> Create a custom font

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"custom-fonts","description":"Upload and manage custom fonts for branding or aesthetic purposes. Once added, fonts can be applied to your spaces or sites to achieve a unique look.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomizationFontDefinition\" grouped=\"false\" %}\n    The CustomizationFontDefinition object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user-internal":[]}],"components":{"securitySchemes":{"user-internal":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"FontFamily":{"type":"string","description":"The human-readable font-family name used in CSS (e.g., \"Open Sans\", \"Playfair Display\").","minLength":1,"maxLength":50},"FontWeight":{"type":"integer","description":"Numeric representation of the font weight (400=regular, 500=medium, 700=bold, 900=black).","minimum":1,"maximum":1000},"StorageFileKey":{"type":"string","description":"The path of the file in the storage bucket","minLength":1,"maxLength":512},"CustomizationFontDefinition":{"allOf":[{"$ref":"#/components/schemas/CustomizationFontDefinitionInput"},{"type":"object","properties":{"permissions":{"type":"object","description":"The set of permissions for the font definition","properties":{"edit":{"type":"boolean","description":"Can the user edit the font definition"}},"required":["edit"]}},"required":["permissions"]}]},"CustomizationFontDefinitionInput":{"type":"object","description":"Defines a font family along with its various font-face declarations for use in CSS '@font-face' rules.","properties":{"id":{"type":"string","description":"A globally unique identifier for the font definition."},"custom":{"type":"boolean","description":"Whether the font is a custom font. If false, this font is provided by GitBook."},"fontFamily":{"$ref":"#/components/schemas/FontFamily"},"fontFaces":{"type":"array","description":"A list of font-face definitions, specifying variations such as weight and style.","items":{"$ref":"#/components/schemas/FontFace"},"minItems":1}},"required":["id","custom","fontFamily","fontFaces"]},"FontFace":{"type":"object","description":"A single font-face declaration specifying the weight and source files for a particular variation of the font.","properties":{"weight":{"$ref":"#/components/schemas/FontWeight"},"sources":{"type":"array","description":"Font source files provided in supported formats (e.g., woff2, woff).","items":{"$ref":"#/components/schemas/FontSource"},"minItems":1}},"required":["weight","sources"]},"FontSource":{"type":"object","description":"A font file referenced within a font-face declaration, specifying the file's location and format.","properties":{"url":{"description":"The absolute or relative URL pointing to the font file.","$ref":"#/components/schemas/URL"},"format":{"type":"string","description":"The format of the font file. Prefer 'woff2' for modern browsers.","enum":["woff2","woff"]}},"required":["url"]},"URL":{"type":"string","format":"uri","maxLength":2048}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}},"PreconditionFailedError":{"description":"PreconditionFailed","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[412]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/orgs/{organizationId}/fonts":{"put":{"operationId":"createCustomFont","summary":"Create a custom font","tags":["custom-fonts"],"parameters":[{"$ref":"#/components/parameters/organizationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Defines a custom font and associated font faces with storage references.","properties":{"fontFamily":{"$ref":"#/components/schemas/FontFamily"},"fontFaces":{"type":"array","description":"Array of font faces specifying weights and their corresponding storage keys.\nAt least one font face with weight 400 (regular) must be provided.\n","items":{"type":"object","properties":{"weight":{"$ref":"#/components/schemas/FontWeight"},"storageKey":{"$ref":"#/components/schemas/StorageFileKey"}},"required":["weight","storageKey"]},"minItems":1}},"required":["fontFamily","fontFaces"]}}}},"responses":{"201":{"description":"Custom font created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomizationFontDefinition"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"412":{"description":"Invalid request data, such as missing required font weights.","$ref":"#/components/responses/PreconditionFailedError"}}}}}}
```

## GET /orgs/{organizationId}/fonts/{fontId}

> Get a custom font by its ID

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"custom-fonts","description":"Upload and manage custom fonts for branding or aesthetic purposes. Once added, fonts can be applied to your spaces or sites to achieve a unique look.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomizationFontDefinition\" grouped=\"false\" %}\n    The CustomizationFontDefinition object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user-internal":[]}],"components":{"securitySchemes":{"user-internal":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"fontId":{"name":"fontId","in":"path","required":true,"description":"The unique ID of a font","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"CustomizationFontDefinition":{"allOf":[{"$ref":"#/components/schemas/CustomizationFontDefinitionInput"},{"type":"object","properties":{"permissions":{"type":"object","description":"The set of permissions for the font definition","properties":{"edit":{"type":"boolean","description":"Can the user edit the font definition"}},"required":["edit"]}},"required":["permissions"]}]},"CustomizationFontDefinitionInput":{"type":"object","description":"Defines a font family along with its various font-face declarations for use in CSS '@font-face' rules.","properties":{"id":{"type":"string","description":"A globally unique identifier for the font definition."},"custom":{"type":"boolean","description":"Whether the font is a custom font. If false, this font is provided by GitBook."},"fontFamily":{"$ref":"#/components/schemas/FontFamily"},"fontFaces":{"type":"array","description":"A list of font-face definitions, specifying variations such as weight and style.","items":{"$ref":"#/components/schemas/FontFace"},"minItems":1}},"required":["id","custom","fontFamily","fontFaces"]},"FontFamily":{"type":"string","description":"The human-readable font-family name used in CSS (e.g., \"Open Sans\", \"Playfair Display\").","minLength":1,"maxLength":50},"FontFace":{"type":"object","description":"A single font-face declaration specifying the weight and source files for a particular variation of the font.","properties":{"weight":{"$ref":"#/components/schemas/FontWeight"},"sources":{"type":"array","description":"Font source files provided in supported formats (e.g., woff2, woff).","items":{"$ref":"#/components/schemas/FontSource"},"minItems":1}},"required":["weight","sources"]},"FontWeight":{"type":"integer","description":"Numeric representation of the font weight (400=regular, 500=medium, 700=bold, 900=black).","minimum":1,"maximum":1000},"FontSource":{"type":"object","description":"A font file referenced within a font-face declaration, specifying the file's location and format.","properties":{"url":{"description":"The absolute or relative URL pointing to the font file.","$ref":"#/components/schemas/URL"},"format":{"type":"string","description":"The format of the font file. Prefer 'woff2' for modern browsers.","enum":["woff2","woff"]}},"required":["url"]},"URL":{"type":"string","format":"uri","maxLength":2048}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/orgs/{organizationId}/fonts/{fontId}":{"get":{"operationId":"getCustomFont","summary":"Get a custom font by its ID","tags":["custom-fonts"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/fontId"}],"responses":{"200":{"description":"Custom font.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomizationFontDefinition"}}}},"404":{"description":"Organization or font not found.","$ref":"#/components/responses/NotFoundError"}}}}}}
```

## POST /orgs/{organizationId}/fonts/{fontId}

> Update a custom font

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"custom-fonts","description":"Upload and manage custom fonts for branding or aesthetic purposes. Once added, fonts can be applied to your spaces or sites to achieve a unique look.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomizationFontDefinition\" grouped=\"false\" %}\n    The CustomizationFontDefinition object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user-internal":[]}],"components":{"securitySchemes":{"user-internal":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"fontId":{"name":"fontId","in":"path","required":true,"description":"The unique ID of a font","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"FontFamily":{"type":"string","description":"The human-readable font-family name used in CSS (e.g., \"Open Sans\", \"Playfair Display\").","minLength":1,"maxLength":50},"FontWeight":{"type":"integer","description":"Numeric representation of the font weight (400=regular, 500=medium, 700=bold, 900=black).","minimum":1,"maximum":1000},"StorageFileKey":{"type":"string","description":"The path of the file in the storage bucket","minLength":1,"maxLength":512},"CustomizationFontDefinition":{"allOf":[{"$ref":"#/components/schemas/CustomizationFontDefinitionInput"},{"type":"object","properties":{"permissions":{"type":"object","description":"The set of permissions for the font definition","properties":{"edit":{"type":"boolean","description":"Can the user edit the font definition"}},"required":["edit"]}},"required":["permissions"]}]},"CustomizationFontDefinitionInput":{"type":"object","description":"Defines a font family along with its various font-face declarations for use in CSS '@font-face' rules.","properties":{"id":{"type":"string","description":"A globally unique identifier for the font definition."},"custom":{"type":"boolean","description":"Whether the font is a custom font. If false, this font is provided by GitBook."},"fontFamily":{"$ref":"#/components/schemas/FontFamily"},"fontFaces":{"type":"array","description":"A list of font-face definitions, specifying variations such as weight and style.","items":{"$ref":"#/components/schemas/FontFace"},"minItems":1}},"required":["id","custom","fontFamily","fontFaces"]},"FontFace":{"type":"object","description":"A single font-face declaration specifying the weight and source files for a particular variation of the font.","properties":{"weight":{"$ref":"#/components/schemas/FontWeight"},"sources":{"type":"array","description":"Font source files provided in supported formats (e.g., woff2, woff).","items":{"$ref":"#/components/schemas/FontSource"},"minItems":1}},"required":["weight","sources"]},"FontSource":{"type":"object","description":"A font file referenced within a font-face declaration, specifying the file's location and format.","properties":{"url":{"description":"The absolute or relative URL pointing to the font file.","$ref":"#/components/schemas/URL"},"format":{"type":"string","description":"The format of the font file. Prefer 'woff2' for modern browsers.","enum":["woff2","woff"]}},"required":["url"]},"URL":{"type":"string","format":"uri","maxLength":2048}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}},"PreconditionFailedError":{"description":"PreconditionFailed","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[412]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/orgs/{organizationId}/fonts/{fontId}":{"post":{"operationId":"updateCustomFont","summary":"Update a custom font","tags":["custom-fonts"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/fontId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Defines a custom font and associated font faces with storage references.","properties":{"fontFamily":{"$ref":"#/components/schemas/FontFamily"},"fontFaces":{"type":"array","description":"Array of font faces specifying weights and their corresponding storage keys. Passing null as the storage key will remove that weight.\n","items":{"type":"object","properties":{"weight":{"$ref":"#/components/schemas/FontWeight"},"storageKey":{"oneOf":[{"$ref":"#/components/schemas/StorageFileKey"},{"type":"null"}]}},"required":["weight","storageKey"]}}}}}}},"responses":{"201":{"description":"Custom font created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomizationFontDefinition"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"412":{"description":"Invalid request data, such as missing required font weights.","$ref":"#/components/responses/PreconditionFailedError"}}}}}}
```

## DELETE /orgs/{organizationId}/fonts/{fontId}

> Delete a custom font

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"custom-fonts","description":"Upload and manage custom fonts for branding or aesthetic purposes. Once added, fonts can be applied to your spaces or sites to achieve a unique look.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomizationFontDefinition\" grouped=\"false\" %}\n    The CustomizationFontDefinition object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user-internal":[]}],"components":{"securitySchemes":{"user-internal":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"fontId":{"name":"fontId","in":"path","required":true,"description":"The unique ID of a font","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"}}},"paths":{"/orgs/{organizationId}/fonts/{fontId}":{"delete":{"operationId":"deleteCustomFont","summary":"Delete a custom font","tags":["custom-fonts"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/fontId"}],"responses":{"204":{"description":"Organization or font not found."},"205":{"description":"Custom font deleted successfully."}}}}}}
```