OpenAPI spec versions

Track changes to your OpenAPI documents by versioning them.

Keep a history of your OpenAPI specs, enabling you to compare different versions, revert, or maintain multiple concurrent versions for testing or documentation.

The OpenAPISpecVersion object

Attributes

objectstring · enumRequired

The object type, which is always "openapi-spec-version"

Possible values:

idstringRequired

Unique identifier

createdAtstring · date-timeOptional

Date of creation

urlstring · uri · max: 2048Required

URL where the specification is accessible.

The OpenAPISpecVersion object

{
  "object": "openapi-spec-version",
  "id": "text",
  "createdAt": "2025-12-10T14:24:38.352Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com"
  }
}

List all OpenAPI spec versions

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

specSlugstringRequired

Slug of the OpenAPI specification

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

Responseall of

404

No matching OpenAPI specification found

application/json

get

/orgs/{organizationId}/openapi/{specSlug}/versions

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/openapi/{specSlug}/versions HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "openapi-spec-version",
      "id": "text",
      "createdAt": "2025-12-10T14:24:38.352Z",
      "url": "https://example.com",
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

Get the latest OpenAPI spec version

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

specSlugstringRequired

Slug of the OpenAPI specification

Responses

200

OK

application/json

404

No matching OpenAPI specification version found

application/json

get

/orgs/{organizationId}/openapi/{specSlug}/versions/latest

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/openapi/{specSlug}/versions/latest HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "openapi-spec-version",
  "id": "text",
  "createdAt": "2025-12-10T14:24:38.352Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com"
  }
}

Get the latest OpenAPI spec version content

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

specSlugstringRequired

Slug of the OpenAPI specification

Responses

200

OK

application/json

404

No matching OpenAPI specification version found

application/json

get

/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "filesystem": {},
  "url": "https://example.com"
}

Get an OpenAPI spec version by its ID

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

specSlugstringRequired

Slug of the OpenAPI specification

versionIdstringRequired

The unique ID of the OpenAPI specification version

Responses

200

OK

application/json

404

No matching OpenAPI specification version found

application/json

get

/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "openapi-spec-version",
  "id": "text",
  "createdAt": "2025-12-10T14:24:38.352Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com"
  }
}

Get an OpenAPI spec version content by its ID

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

specSlugstringRequired

Slug of the OpenAPI specification

versionIdstringRequired

The unique ID of the OpenAPI specification version

Responses

200

OK

application/json

404

No matching OpenAPI specification version found

application/json

get

/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "filesystem": {},
  "url": "https://example.com"
}