# Site share links

Manage the lifecycle of share links for your published sites. This includes generating new links for external sharing and revoking or updating existing ones.

## The ShareLink object

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"ShareLink":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"share-link\"","enum":["share-link"]},"id":{"type":"string","description":"Unique identifier for the share-link"},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"name":{"$ref":"#/components/schemas/ShareLinkName"},"active":{"type":"boolean"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"published":{"type":"string","description":"URL of the published version of the share-link.","format":"uri"}}}},"required":["object","id","createdAt","urls"]},"Timestamp":{"type":"string","format":"date-time"},"ShareLinkName":{"type":"string","description":"Name of the share link","minLength":0,"maxLength":50}}}}
```

## GET /orgs/{organizationId}/sites/{siteId}/share-links

> List all share links

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-share-links","description":"Manage the lifecycle of share links for your published sites. This includes generating new links for external sharing and revoking or updating existing ones.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ShareLink\" grouped=\"false\" %}\n    The ShareLink object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}},"listPage":{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},"listLimit":{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}}},"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"}}},"ShareLink":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"share-link\"","enum":["share-link"]},"id":{"type":"string","description":"Unique identifier for the share-link"},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"name":{"$ref":"#/components/schemas/ShareLinkName"},"active":{"type":"boolean"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"published":{"type":"string","description":"URL of the published version of the share-link.","format":"uri"}}}},"required":["object","id","createdAt","urls"]},"Timestamp":{"type":"string","format":"date-time"},"ShareLinkName":{"type":"string","description":"Name of the share link","minLength":0,"maxLength":50}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/share-links":{"get":{"operationId":"listSiteShareLinks","summary":"List all share links","tags":["site-share-links"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"},{"name":"search","in":"query","description":"Search share links by name or key","schema":{"type":"string"}}],"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/ShareLink"}}}}]}}}}}}}}}
```

## POST /orgs/{organizationId}/sites/{siteId}/share-links

> Create a share link

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-share-links","description":"Manage the lifecycle of share links for your published sites. This includes generating new links for external sharing and revoking or updating existing ones.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ShareLink\" grouped=\"false\" %}\n    The ShareLink object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"ShareLinkName":{"type":"string","description":"Name of the share link","minLength":0,"maxLength":50},"ShareLink":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"share-link\"","enum":["share-link"]},"id":{"type":"string","description":"Unique identifier for the share-link"},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"name":{"$ref":"#/components/schemas/ShareLinkName"},"active":{"type":"boolean"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"published":{"type":"string","description":"URL of the published version of the share-link.","format":"uri"}}}},"required":["object","id","createdAt","urls"]},"Timestamp":{"type":"string","format":"date-time"}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/share-links":{"post":{"operationId":"createSiteShareLink","summary":"Create a share link","tags":["site-share-links"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/ShareLinkName"}},"required":["name"]}}}},"responses":{"201":{"description":"The share link has been created","headers":{"Location":{"description":"API URL for the newly created share link","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareLink"}}}}}}}}}
```

## DELETE /orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}

> Deletes a share link

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-share-links","description":"Manage the lifecycle of share links for your published sites. This includes generating new links for external sharing and revoking or updating existing ones.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ShareLink\" grouped=\"false\" %}\n    The ShareLink object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}},"shareLinkId":{"name":"shareLinkId","in":"path","required":true,"description":"The unique id of the share link","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}":{"delete":{"operationId":"deleteSiteShareLinkById","summary":"Deletes a share link","tags":["site-share-links"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"},{"$ref":"#/components/parameters/shareLinkId"}],"responses":{"204":{"description":"Site share link did not exist"},"205":{"description":"Site share link has been deleted"}}}}}}
```

## PATCH /orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}

> Update a share link

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-share-links","description":"Manage the lifecycle of share links for your published sites. This includes generating new links for external sharing and revoking or updating existing ones.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ShareLink\" grouped=\"false\" %}\n    The ShareLink object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}},"shareLinkId":{"name":"shareLinkId","in":"path","required":true,"description":"The unique id of the share link","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"ShareLinkName":{"type":"string","description":"Name of the share link","minLength":0,"maxLength":50},"ShareLink":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"share-link\"","enum":["share-link"]},"id":{"type":"string","description":"Unique identifier for the share-link"},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"name":{"$ref":"#/components/schemas/ShareLinkName"},"active":{"type":"boolean"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"published":{"type":"string","description":"URL of the published version of the share-link.","format":"uri"}}}},"required":["object","id","createdAt","urls"]},"Timestamp":{"type":"string","format":"date-time"}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}":{"patch":{"operationId":"updateSiteShareLinkById","summary":"Update a share link","tags":["site-share-links"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"},{"$ref":"#/components/parameters/shareLinkId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"active":{"type":"boolean"},"name":{"$ref":"#/components/schemas/ShareLinkName"}}}}}},"responses":{"200":{"description":"The site share link has been updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareLink"}}}}}}}}}
```