# Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/openapi/openapi-spec-versions.md

# OpenAPI spec versions

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

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"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"]},"Timestamp":{"type":"string","format":"date-time"},"URL":{"type":"string","format":"uri","maxLength":2048}}}}
```

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

> List all OpenAPI spec versions

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi-versions","description":"Keep a history of your OpenAPI specs, enabling you to compare different versions, revert, or maintain multiple concurrent versions for testing or documentation.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpecVersion\" grouped=\"false\" %}\n    The OpenAPISpecVersion object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"type":"string"}},"openapiSpecSlug":{"name":"specSlug","in":"path","required":true,"description":"Slug of the OpenAPI specification","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}}},"schemas":{"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"}}},"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"]},"Timestamp":{"type":"string","format":"date-time"},"URL":{"type":"string","format":"uri","maxLength":2048}},"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"]}}}}}}}},"paths":{"/orgs/{organizationId}/openapi/{specSlug}/versions":{"get":{"operationId":"listOpenAPISpecVersions","summary":"List all OpenAPI spec versions","tags":["openapi-versions"],"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"}}}}}}
```

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

> Get the latest OpenAPI spec version

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi-versions","description":"Keep a history of your OpenAPI specs, enabling you to compare different versions, revert, or maintain multiple concurrent versions for testing or documentation.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpecVersion\" grouped=\"false\" %}\n    The OpenAPISpecVersion object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"type":"string"}},"openapiSpecSlug":{"name":"specSlug","in":"path","required":true,"description":"Slug of the OpenAPI specification","schema":{"type":"string"}}},"schemas":{"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"]},"Timestamp":{"type":"string","format":"date-time"},"URL":{"type":"string","format":"uri","maxLength":2048}},"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"]}}}}}}}},"paths":{"/orgs/{organizationId}/openapi/{specSlug}/versions/latest":{"get":{"operationId":"getLatestOpenAPISpecVersion","summary":"Get the latest OpenAPI spec version","tags":["openapi-versions"],"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"}}}}}}
```

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

> Get the latest OpenAPI spec version content

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi-versions","description":"Keep a history of your OpenAPI specs, enabling you to compare different versions, revert, or maintain multiple concurrent versions for testing or documentation.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpecVersion\" grouped=\"false\" %}\n    The OpenAPISpecVersion object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"type":"string"}},"openapiSpecSlug":{"name":"specSlug","in":"path","required":true,"description":"Slug of the OpenAPI specification","schema":{"type":"string"}}},"schemas":{"OpenAPISpecContent":{"description":"Content of the specification available through filesystem or public URL.","type":"object","properties":{"filesystem":{"description":"Filesystem containing all specifications.","type":"object"},"url":{"$ref":"#/components/schemas/URL"}},"required":["filesystem","url"]},"URL":{"type":"string","format":"uri","maxLength":2048}},"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"]}}}}}}}},"paths":{"/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content":{"get":{"operationId":"getLatestOpenAPISpecVersionContent","summary":"Get the latest OpenAPI spec version content","tags":["openapi-versions"],"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"}}}}}}
```

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

> Get an OpenAPI spec version by its ID

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi-versions","description":"Keep a history of your OpenAPI specs, enabling you to compare different versions, revert, or maintain multiple concurrent versions for testing or documentation.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpecVersion\" grouped=\"false\" %}\n    The OpenAPISpecVersion object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"type":"string"}},"openapiSpecSlug":{"name":"specSlug","in":"path","required":true,"description":"Slug of the OpenAPI specification","schema":{"type":"string"}},"openapiSpecVersionId":{"name":"versionId","in":"path","required":true,"description":"The unique ID of the OpenAPI specification version","schema":{"type":"string"}}},"schemas":{"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"]},"Timestamp":{"type":"string","format":"date-time"},"URL":{"type":"string","format":"uri","maxLength":2048}},"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"]}}}}}}}},"paths":{"/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}":{"get":{"operationId":"getOpenAPISpecVersionById","summary":"Get an OpenAPI spec version by its ID","tags":["openapi-versions"],"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"}}}}}}
```

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

> Get an OpenAPI spec version content by its ID

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi-versions","description":"Keep a history of your OpenAPI specs, enabling you to compare different versions, revert, or maintain multiple concurrent versions for testing or documentation.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpecVersion\" grouped=\"false\" %}\n    The OpenAPISpecVersion object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"type":"string"}},"openapiSpecSlug":{"name":"specSlug","in":"path","required":true,"description":"Slug of the OpenAPI specification","schema":{"type":"string"}},"openapiSpecVersionId":{"name":"versionId","in":"path","required":true,"description":"The unique ID of the OpenAPI specification version","schema":{"type":"string"}}},"schemas":{"OpenAPISpecContent":{"description":"Content of the specification available through filesystem or public URL.","type":"object","properties":{"filesystem":{"description":"Filesystem containing all specifications.","type":"object"},"url":{"$ref":"#/components/schemas/URL"}},"required":["filesystem","url"]},"URL":{"type":"string","format":"uri","maxLength":2048}},"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"]}}}}}}}},"paths":{"/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content":{"get":{"operationId":"getOpenAPISpecVersionContentById","summary":"Get an OpenAPI spec version content by its ID","tags":["openapi-versions"],"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"}}}}}}
```