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"

Available options:

idstringrequired

Unique identifier

createdAtstring · date-timeoptional

Date of creation

urlstring · uri · max: 2048required

URL where the specification is accessible.

urlsobjectrequired

URLs associated with the object

The OpenAPISpecVersion object

{
  "object": "openapi-spec-version",
  "id": "text",
  "createdAt": "2025-04-16T04:38:06.513Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

List all OpenAPI spec versions

get

Authorizations

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

application/json

all ofoptional

application/json

get

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-04-16T04:38:06.513Z",
      "url": "https://example.com",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      }
    }
  ]
}

Get the latest OpenAPI spec version

get

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Responses

application/json

objectoptional

application/json

get

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-04-16T04:38:06.513Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

Get the latest OpenAPI spec version content

get

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Responses

application/json

objectoptional

Content of the specification available through filesystem or public URL.

application/json

get

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

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

application/json

objectoptional

application/json

get

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-04-16T04:38:06.513Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

Get an OpenAPI spec version content by its ID

get

Authorizations

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

application/json

objectoptional

Content of the specification available through filesystem or public URL.

application/json

get

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"
}

Was this helpful?