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

Site ads

Control and customize ad placements on your docs site.

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

Update a site ads settings

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
statusstring · enumoptionalAvailable options:
topicstring · enumoptional

Topic of the content

Available options:
Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/ads' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "in-review",
    "topic": "webdev"
  }'
No Content

OK

List all the sites with ads configured

get
Authorizations
Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

statusstring · enumoptional

Filter sites by their ads review status

Default: in-reviewAvailable options:
Header parameters
X-GitBook-Partner-Keystringrequired
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/ads/sites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-GitBook-Partner-Key: text'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "url": "text",
      "email": "text",
      "topic": "webdev",
      "status": "in-review"
    }
  ]
}

OK

Update the Ads configuration for a site

patch
Authorizations
Path parameters
siteIdstringrequired

The unique id of the site

Header parameters
X-GitBook-Partner-Keystringrequired
Body
one ofoptional

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/ads/sites/{siteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-GitBook-Partner-Key: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "live",
    "zoneId": "text",
    "reportingId": "text"
  }'
No Content

OK

Was this helpful?