# Site ads

Manage the advertisement strategy within your docs. You can specify ad placements, track usage, and adjust settings to best fit your organization's needs.

## POST /orgs/{organizationId}/sites/{siteId}/ads

> Update a site ads settings

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-ads","description":"Manage the advertisement strategy within your docs. You can specify ad placements, track usage, and adjust settings to best fit your organization's needs.\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"},"SiteAdsTopic":{"type":"string","description":"Topic of the content","enum":["webdev","crypto"]}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/ads":{"post":{"operationId":"updateSiteAdsById","summary":"Update a site ads settings","tags":["site-ads"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["in-review","disabled"]},"topic":{"$ref":"#/components/schemas/SiteAdsTopic"}}}}}},"responses":{"204":{"description":"OK"}}}}}}
```

## GET /ads/sites

> List all the sites with ads configured

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-ads","description":"Manage the advertisement strategy within your docs. You can specify ad placements, track usage, and adjust settings to best fit your organization's needs.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]},{"user-internal":[]},{"user-staff":[]},{"user-internal-or-staff":[]},{"integration":[]},{"integration-installation":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"},"user-internal":{"type":"http","scheme":"bearer"},"user-staff":{"type":"http","scheme":"bearer"},"user-internal-or-staff":{"type":"http","scheme":"bearer"},"integration":{"type":"http","scheme":"bearer"},"integration-installation":{"type":"http","scheme":"bearer"}},"parameters":{"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}},"xGitBookPartnerKey":{"in":"header","name":"X-GitBook-Partner-Key","schema":{"type":"string"},"required":true}},"schemas":{"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"}}},"SiteAdsTopic":{"type":"string","description":"Topic of the content","enum":["webdev","crypto"]}}},"paths":{"/ads/sites":{"get":{"operationId":"adsListSites","summary":"List all the sites with ads configured","tags":["site-ads"],"parameters":[{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"},{"$ref":"#/components/parameters/xGitBookPartnerKey"},{"name":"status","in":"query","description":"Filter sites by their ads review status","required":false,"schema":{"type":"string","default":"in-review","enum":["in-review","live","rejected"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"allOf":[{"type":"object","required":["id","url","email","topic"],"properties":{"id":{"type":"string"},"url":{"type":"string"},"email":{"type":"string"},"topic":{"$ref":"#/components/schemas/SiteAdsTopic"}}},{"oneOf":[{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["in-review"]}}},{"type":"object","required":["status","zoneId"],"properties":{"status":{"type":"string","enum":["live"]},"zoneId":{"type":"string","description":"The ad network zone ID"}}},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["rejected"]},"reason":{"type":"string","description":"Reason for the rejection"}}}]}]}}}}]}}}}}}}}}
```

## PATCH /ads/sites/{siteId}

> Update the Ads configuration for a site

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-ads","description":"Manage the advertisement strategy within your docs. You can specify ad placements, track usage, and adjust settings to best fit your organization's needs.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]},{"user-internal":[]},{"user-staff":[]},{"user-internal-or-staff":[]},{"integration":[]},{"integration-installation":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"},"user-internal":{"type":"http","scheme":"bearer"},"user-staff":{"type":"http","scheme":"bearer"},"user-internal-or-staff":{"type":"http","scheme":"bearer"},"integration":{"type":"http","scheme":"bearer"},"integration-installation":{"type":"http","scheme":"bearer"}},"parameters":{"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}},"xGitBookPartnerKey":{"in":"header","name":"X-GitBook-Partner-Key","schema":{"type":"string"},"required":true}}},"paths":{"/ads/sites/{siteId}":{"patch":{"operationId":"adsUpdateSite","summary":"Update the Ads configuration for a site","tags":["site-ads"],"parameters":[{"$ref":"#/components/parameters/siteId"},{"$ref":"#/components/parameters/xGitBookPartnerKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["status","zoneId","reportingId"],"properties":{"status":{"type":"string","enum":["live"]},"zoneId":{"type":"string","description":"ID of the zone"},"reportingId":{"type":"string","description":"ID to fetch reporting data"}}},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["rejected"]},"reason":{"type":"string","description":"Reason for the rejection","maxLength":512}}},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["pending"]}}}]}}}},"responses":{"204":{"description":"OK"}}}}}}
```