# 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.1.0","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.1.0","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":{"$ref":"#/components/schemas/EntityId"}},"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":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"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.1.0","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":{"$ref":"#/components/schemas/EntityId"}},"openapiSpecSlug":{"name":"specSlug","in":"path","required":true,"description":"Slug of the OpenAPI specification","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"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.1.0","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":{"$ref":"#/components/schemas/EntityId"}},"openapiSpecSlug":{"name":"specSlug","in":"path","required":true,"description":"Slug of the OpenAPI specification","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"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"]},"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.1.0","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":{"$ref":"#/components/schemas/EntityId"}},"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":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"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.1.0","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":{"$ref":"#/components/schemas/EntityId"}},"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":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"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"]},"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"}}}}}}
```