API

All notable changes to the REST API will be documented in this page.

2023-11-16

Breaking: changing feedback score computation logic

We have changed the way we compute the feedback score based on user ratings which is affecting the following endpoint: /v1/spaces/:id/insights/content

  • [Updated] score is now calculated this wayscore=positives−0.5∗intermediates−2∗negativesscore = positives - 0.5 * intermediates - 2*negatives. This is done to reinforce negative ratings and help surfacing content that may require updates.

  • [Updated] rating is now computed this way

    • 'good' whenever the score is > 0

    • 'ok' whenever the score is 0

    • 'bad' whenever the score is < 0

  • [Added] ponderedScore is computed by multiplying the score by the total amount of ratings given by visitors.

Note: The GitBook app is displaying ponderedScore inside of the Insights section.

2022-09-16

API for users management

We are introducing a collection of API endpoints to automate the management of members and teams in an organization:

2022-06-30

Breaking: removing /v1/owners/:id endpoints

Endpoint /v1/owners/:id/spaces has been removed and replaced by:

  • /v1/orgs/:id/spaces for an organization

  • /v1/users/:id/spaces for a user

Breaking: path and slug properties in pages

Page previously had only one path property representing the page slug in its direct page parent. Pages will now include 2 properties:

  • slug: representing the page's slug in its direct parent

  • path: representing the complete page's path in the revision

Breaking: url path parameter for page lookup by path

Requests on page using a URL will now require a URL encoded page's path. For example the previous request:

GET /v1/spaces/u23h2u4hi24/content/url/a/b/c

should now be:

GET /v1/spaces/u23h2u4hi24/content/path/a%2Fb%2Fc

createChangeRequest returns entire change-request

Previously POST /v1/spaces/:space/change-requests was only returning the ID of the newly created change-request.

The response will now contain the entire change-request object. A property changeRequest is appended for compatibility, but marked as deprecated and will be removed in the near future.

Last updated