GitBook Openapi Versions API

openapi: 3.2.0
info:
  title: GitBook Openapi Versions API
  description: The GitBook API
  termsOfService: https://policies.gitbook.com
  contact:
    name: API Support
    url: https://gitbook.com/support
    email: support@gitbook.com
  version: 0.0.1-beta
servers:
- url: '{host}/v1'
  variables:
    host:
      default: https://api.gitbook.com
security:
- user: []
- user-internal: []
- user-staff: []
- integration: []
- integration-installation: []
tags:
- name: openapi-versions
  x-page-title: OpenAPI spec versions
  x-page-description: Track changes to your OpenAPI documents by versioning them.
  x-parent: openapi
  description: 'Keep a history of your OpenAPI specs, enabling you to compare different versions, revert, or maintain multiple concurrent versions for testing or documentation.


    {% openapi-schemas spec="gitbook" schemas="OpenAPISpecVersion" grouped="false" %}

    The OpenAPISpecVersion object

    {% endopenapi-schemas %}'
paths:
  /orgs/{organizationId}/openapi/{specSlug}/versions:
    get:
      operationId: listOpenAPISpecVersions
      summary: List all OpenAPI spec versions
      x-gitbook-mcp: true
      tags:
      - openapi-versions
      security:
      - user: []
      - oauth:
        - openapi:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/openapiSpecSlug'
      - $ref: '#/components/parameters/listPage'
      - $ref: '#/components/parameters/listLimit'
      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/OpenAPISpecVersion'
        '404':
          description: No matching OpenAPI specification found
          $ref: '#/components/responses/NotFoundError'
  /orgs/{organizationId}/openapi/{specSlug}/versions/latest:
    get:
      operationId: getLatestOpenAPISpecVersion
      summary: Get the latest OpenAPI spec version
      x-gitbook-mcp: true
      tags:
      - openapi-versions
      security:
      - user: []
      - oauth:
        - openapi:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/openapiSpecSlug'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAPISpecVersion'
        '404':
          description: No matching OpenAPI specification version found
          $ref: '#/components/responses/NotFoundError'
  /orgs/{organizationId}/openapi/{specSlug}/versions/latest/content:
    get:
      operationId: getLatestOpenAPISpecVersionContent
      summary: Get the latest OpenAPI spec version content
      x-gitbook-mcp: true
      tags:
      - openapi-versions
      security:
      - user: []
      - oauth:
        - openapi:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/openapiSpecSlug'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAPISpecContent'
        '404':
          description: No matching OpenAPI specification version found
          $ref: '#/components/responses/NotFoundError'
  /orgs/{organizationId}/openapi/{specSlug}/versions/latest/content/raw:
    get:
      operationId: getLatestOpenAPISpecVersionContentRaw
      summary: Get the raw content of the latest OpenAPI spec version
      tags:
      - openapi-versions
      security:
      - user: []
      - oauth:
        - openapi:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/openapiSpecSlug'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAPISpecRawContent'
        '404':
          description: No matching OpenAPI specification version, or no raw source available for it (e.g. legacy versions)
          $ref: '#/components/responses/NotFoundError'
  /orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}:
    get:
      operationId: getOpenAPISpecVersionById
      summary: Get an OpenAPI spec version by its ID
      x-gitbook-mcp: true
      tags:
      - openapi-versions
      security:
      - user: []
      - oauth:
        - openapi:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/openapiSpecSlug'
      - $ref: '#/components/parameters/openapiSpecVersionId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAPISpecVersion'
        '404':
          description: No matching OpenAPI specification version found
          $ref: '#/components/responses/NotFoundError'
  /orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content:
    get:
      operationId: getOpenAPISpecVersionContentById
      summary: Get an OpenAPI spec version content by its ID
      x-gitbook-mcp: true
      tags:
      - openapi-versions
      security:
      - user: []
      - oauth:
        - openapi:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/openapiSpecSlug'
      - $ref: '#/components/parameters/openapiSpecVersionId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAPISpecContent'
        '404':
          description: No matching OpenAPI specification version found
          $ref: '#/components/responses/NotFoundError'
components:
  responses:
    NotFoundError:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    enum:
                    - 404
                  message:
                    type: string
                required:
                - code
                - message
  schemas:
    OpenAPISpecRawContent:
      description: Raw original content of the specification entrypoint file.
      type: object
      properties:
        text:
          type: string
          description: Raw specification text, exactly as submitted.
        format:
          type: string
          enum:
          - json
          - yaml
          description: Format of the raw specification text.
      required:
      - text
      - format
    Timestamp:
      type: string
      format: date-time
    OpenAPISpecContent:
      description: Content of the specification available through filesystem or public URL.
      type: object
      properties:
        filesystem:
          description: Filesystem containing all specifications.
          type: object
        urls:
          description: URLs associated with the specification content.
          type: object
          properties:
            source:
              $ref: '#/components/schemas/URL'
            public:
              description: Publicly accessible URL for the specification. Available for public specs (proxy URL for stored specs, source URL for external specs). Null for private specs. Can be used for the "Try it" feature.
              oneOf:
              - type: 'null'
              - $ref: '#/components/schemas/URL'
          required:
          - source
          - public
      required:
      - filesystem
      - urls
    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
    EntityId:
      type: string
      pattern: ^[a-zA-Z0-9_-]+$
      description: A unique entity identifier
    URL:
      type: string
      format: uri
      maxLength: 2048
    OpenAPISpecVersion:
      type: object
      properties:
        object:
          description: The object type, which is always "openapi-spec-version"
          type: string
          enum:
          - openapi-spec-version
        id:
          description: Unique identifier
          type: string
        createdAt:
          description: Date of creation
          $ref: '#/components/schemas/Timestamp'
        url:
          description: URL where the specification is accessible.
          $ref: '#/components/schemas/URL'
        urls:
          type: object
          description: URLs associated with the object
          properties:
            location:
              description: URL of the OpenAPI specification version in the API
              $ref: '#/components/schemas/URL'
          required:
          - location
      required:
      - object
      - id
      - url
      - urls
  parameters:
    openapiSpecVersionId:
      name: versionId
      in: path
      required: true
      description: The unique ID of the OpenAPI specification version
      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
    openapiSpecSlug:
      name: specSlug
      in: path
      required: true
      description: Slug of the OpenAPI specification
      schema:
        type: string
    organizationId:
      name: organizationId
      in: path
      required: true
      description: The unique id of the organization
      schema:
        $ref: '#/components/schemas/EntityId'
  securitySchemes:
    user:
      type: http
      scheme: bearer
    user-internal:
      type: http
      scheme: bearer
    user-staff:
      type: http
      scheme: bearer
    integration:
      type: http
      scheme: bearer
    integration-installation:
      type: http
      scheme: bearer
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.gitbook.com/authorize
          tokenUrl: https://oauth.gitbook.com/token
          scopes:
            user:read: Read your GitBook user profile.
            organization:read: Read the organizations you belong to, their settings and metadata, and their AI agent conversations.
            organization:write: Create organizations, and update organization settings and AI agent conversations.
            organization:members:read: Read organization members, teams, invites and link invites.
            organization:members:write: Manage organization members, teams, invites and link invites.
            organization:ask: Ask AI questions across an organization's content.
            organization:search: Search across an organization's content.
            space:read: Read spaces and their content, including pages, change requests and their reviews, comments, files and revision history.
            space:write: Create, update and delete spaces and their content, including change requests (create, edit, review), comments, and content imports and exports. Merging a change request also requires change-request:merge.
            space:permissions:read: Read the users and teams who have access to spaces and collections.
            space:permissions:write: Manage who has access to spaces and collections, including inviting users and teams.
            change-request:merge: Merge change requests, publishing their changes to the space. Creating, editing and reviewing change requests only requires space:write.
            site:read: Read sites and their settings, including navigation structure, linked spaces, customization, redirects, topics, AI configuration and documentation issues.
            site:write: Create, update and delete sites and their settings, including navigation structure (sections, linked spaces, external links), customization, redirects, topics and AI configuration.
            site:publish: Publish and unpublish sites, controlling their public exposure.
            site:permissions:read: Read the users and teams who have access to sites.
            site:permissions:write: Manage who has access to sites, including inviting users and teams.
            site:auth:read: Read how visitors authenticate on a site and its security configuration, including private share links.
            site:auth:write: Manage how visitors authenticate on a site and its security configuration, including private share links.
            site:insights:read: Read site analytics and insights, including the questions visitors asked Ask AI and the answers they received.
            site:ask: Ask AI questions across a site's content.
            site:search: Search across a site's content.
            integration:read: Read integrations, their status and where they are installed.
            integration:installations:read: Read integration installations and their configuration, which can include credentials for third-party services.
            integration:installations:write: Install and configure integrations on an organization, its spaces and its sites.
            integration:publish: Publish integrations, which can request their own permissions on your content, and route their events to a development tunnel.
            integration:delete: Unpublish integrations, permanently deleting them and every installation of them.
            openapi:read: Read OpenAPI specifications.
            openapi:write: Create, update and delete OpenAPI specifications.
x-provenance:
  method: harvested
  publisher: GitBook
  source: https://api.gitbook.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)