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-12T21:04:01.285Z",
  "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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "openapi-spec-version",
      "id": "text",
      "createdAt": "2025-04-12T21:04:01.285Z",
      "url": "https://example.com",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      }
    }
  ]
}

OK

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/latest' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

200

{
  "object": "openapi-spec-version",
  "id": "text",
  "createdAt": "2025-04-12T21:04:01.285Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OK

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

200

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

OK

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

200

{
  "object": "openapi-spec-version",
  "id": "text",
  "createdAt": "2025-04-12T21:04:01.285Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OK

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

200

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

OK