The State of Docs Report 2025 is live! Dive in and see why docs matter more than ever:
Read the report
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 · enumOptionalPossible values:
topicstring · enumOptional

Topic of the content

Possible values:
Responses
204
OK
post
POST /v1/orgs/{organizationId}/sites/{siteId}/ads HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "status": "in-review",
  "topic": "webdev"
}
204

OK

No content

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-reviewPossible values:
Header parameters
X-GitBook-Partner-KeystringRequired
Responses
200
OK
application/json
Responseall of
get
GET /v1/ads/sites HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-GitBook-Partner-Key: text
Accept: */*
200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "url": "text",
      "email": "text",
      "topic": "webdev",
      "status": "in-review"
    }
  ]
}

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
or
or
Responses
204
OK
patch
PATCH /v1/ads/sites/{siteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-GitBook-Partner-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "status": "live",
  "zoneId": "text",
  "reportingId": "text"
}
204

OK

No content

Was this helpful?