# OpenAPI

The OpenAPI endpoints let you integrate your existing or newly generated OpenAPI definitions into GitBook. This includes uploading, updating, and retrieving specs.

## The OpenAPISpec object

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"OpenAPISpec":{"type":"object","properties":{"object":{"description":"The object type, which is always \"openapi-spec\"","type":"string","enum":["openapi-spec"]},"id":{"description":"Unique identifier","type":"string"},"createdAt":{"description":"Date of creation","$ref":"#/components/schemas/Timestamp"},"updatedAt":{"description":"Date of the last update","$ref":"#/components/schemas/Timestamp"},"slug":{"$ref":"#/components/schemas/OpenAPISpecSlug"},"sourceURL":{"$ref":"#/components/schemas/URL"},"processingState":{"$ref":"#/components/schemas/OpenAPISpecProcessingState"},"visibility":{"$ref":"#/components/schemas/OpenAPISpecVisibility"},"lastVersion":{"type":"string","description":"ID of the latest version of the OpenAPI specification"},"lastProcessedAt":{"description":"Date of the last processing","$ref":"#/components/schemas/Timestamp"},"lastProcessErrorCode":{"$ref":"#/components/schemas/OpenAPISpecProcessingErrorCode"},"lastProcessedErrors":{"type":"array","items":{"$ref":"#/components/schemas/OpenAPIErrorObject"}},"lastProcessedErrorCount":{"type":"integer","minimum":0,"description":"Total number of processing errors before truncation of lastProcessedErrors."},"permissions":{"type":"object","description":"The set of permissions for the OpenAPI specification.","required":["view","edit"],"properties":{"view":{"type":"boolean","description":"Can the user view the specification."},"edit":{"type":"boolean","description":"Can the user edit the specification."}}},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"description":"URL of the OpenAPI specification in the API","$ref":"#/components/schemas/URL"},"app":{"description":"URL of the OpenAPI specification in the application","$ref":"#/components/schemas/URL"},"published":{"type":"string","description":"URL of the published spec. Only defined when visibility is \"published.\"","format":"uri"}},"required":["app","location"]}},"required":["object","id","createdAt","updatedAt","slug","processingState","lastProcessedErrorCount","permissions","urls"]},"Timestamp":{"type":"string","format":"date-time"},"OpenAPISpecSlug":{"description":"Slug used as reference","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$"},"URL":{"type":"string","format":"uri","maxLength":2048},"OpenAPISpecProcessingState":{"description":"Processing state","enum":["pending","progress","complete"]},"OpenAPISpecVisibility":{"type":"string","description":"The visibility setting of the OpenAPI spec.\n* `private`: The spec is not publicly available.\n* `public`: The spec is available to anyone with a public link.\n","enum":["private","public"]},"OpenAPISpecProcessingErrorCode":{"description":"OpenAPI processing error code","enum":["FETCH_TIMEOUT","FETCH_ERROR","PARSE_ERROR"]},"OpenAPIErrorObject":{"type":"object","description":"OpenAPI error object.","properties":{"message":{"type":"string","description":"Description of the error."},"code":{"type":"string","description":"Unique code of the error."}},"required":["message"]}}}}
```

## GET /orgs/{organizationId}/openapi

> List all OpenAPI spec

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi","description":"The OpenAPI endpoints let you integrate your existing or newly generated OpenAPI definitions into GitBook. This includes uploading, updating, and retrieving specs.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpec\" grouped=\"false\" %}\n    The OpenAPISpec 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"}},"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"}}},"OpenAPISpec":{"type":"object","properties":{"object":{"description":"The object type, which is always \"openapi-spec\"","type":"string","enum":["openapi-spec"]},"id":{"description":"Unique identifier","type":"string"},"createdAt":{"description":"Date of creation","$ref":"#/components/schemas/Timestamp"},"updatedAt":{"description":"Date of the last update","$ref":"#/components/schemas/Timestamp"},"slug":{"$ref":"#/components/schemas/OpenAPISpecSlug"},"sourceURL":{"$ref":"#/components/schemas/URL"},"processingState":{"$ref":"#/components/schemas/OpenAPISpecProcessingState"},"visibility":{"$ref":"#/components/schemas/OpenAPISpecVisibility"},"lastVersion":{"type":"string","description":"ID of the latest version of the OpenAPI specification"},"lastProcessedAt":{"description":"Date of the last processing","$ref":"#/components/schemas/Timestamp"},"lastProcessErrorCode":{"$ref":"#/components/schemas/OpenAPISpecProcessingErrorCode"},"lastProcessedErrors":{"type":"array","items":{"$ref":"#/components/schemas/OpenAPIErrorObject"}},"lastProcessedErrorCount":{"type":"integer","minimum":0,"description":"Total number of processing errors before truncation of lastProcessedErrors."},"permissions":{"type":"object","description":"The set of permissions for the OpenAPI specification.","required":["view","edit"],"properties":{"view":{"type":"boolean","description":"Can the user view the specification."},"edit":{"type":"boolean","description":"Can the user edit the specification."}}},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"description":"URL of the OpenAPI specification in the API","$ref":"#/components/schemas/URL"},"app":{"description":"URL of the OpenAPI specification in the application","$ref":"#/components/schemas/URL"},"published":{"type":"string","description":"URL of the published spec. Only defined when visibility is \"published.\"","format":"uri"}},"required":["app","location"]}},"required":["object","id","createdAt","updatedAt","slug","processingState","lastProcessedErrorCount","permissions","urls"]},"Timestamp":{"type":"string","format":"date-time"},"OpenAPISpecSlug":{"description":"Slug used as reference","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$"},"URL":{"type":"string","format":"uri","maxLength":2048},"OpenAPISpecProcessingState":{"description":"Processing state","enum":["pending","progress","complete"]},"OpenAPISpecVisibility":{"type":"string","description":"The visibility setting of the OpenAPI spec.\n* `private`: The spec is not publicly available.\n* `public`: The spec is available to anyone with a public link.\n","enum":["private","public"]},"OpenAPISpecProcessingErrorCode":{"description":"OpenAPI processing error code","enum":["FETCH_TIMEOUT","FETCH_ERROR","PARSE_ERROR"]},"OpenAPIErrorObject":{"type":"object","description":"OpenAPI error object.","properties":{"message":{"type":"string","description":"Description of the error."},"code":{"type":"string","description":"Unique code of the error."}},"required":["message"]}}},"paths":{"/orgs/{organizationId}/openapi":{"get":{"operationId":"listOpenAPISpecs","summary":"List all OpenAPI spec","tags":["openapi"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$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/OpenAPISpec"}}}}]}}}}}}}}}
```

## POST /orgs/{organizationId}/openapi

> Create an OpenAPI spec

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi","description":"The OpenAPI endpoints let you integrate your existing or newly generated OpenAPI definitions into GitBook. This includes uploading, updating, and retrieving specs.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpec\" grouped=\"false\" %}\n    The OpenAPISpec 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"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"OpenAPISpecSlug":{"description":"Slug used as reference","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$"},"OpenAPISpecSource":{"oneOf":[{"description":"Create a specification from an URL","type":"object","properties":{"url":{"$ref":"#/components/schemas/URL"}},"required":["url"]},{"description":"Create a specification from a text string","type":"object","properties":{"text":{"description":"OpenAPI specification as text","type":"string","minLength":1}},"required":["text"]}]},"URL":{"type":"string","format":"uri","maxLength":2048},"OpenAPISpec":{"type":"object","properties":{"object":{"description":"The object type, which is always \"openapi-spec\"","type":"string","enum":["openapi-spec"]},"id":{"description":"Unique identifier","type":"string"},"createdAt":{"description":"Date of creation","$ref":"#/components/schemas/Timestamp"},"updatedAt":{"description":"Date of the last update","$ref":"#/components/schemas/Timestamp"},"slug":{"$ref":"#/components/schemas/OpenAPISpecSlug"},"sourceURL":{"$ref":"#/components/schemas/URL"},"processingState":{"$ref":"#/components/schemas/OpenAPISpecProcessingState"},"visibility":{"$ref":"#/components/schemas/OpenAPISpecVisibility"},"lastVersion":{"type":"string","description":"ID of the latest version of the OpenAPI specification"},"lastProcessedAt":{"description":"Date of the last processing","$ref":"#/components/schemas/Timestamp"},"lastProcessErrorCode":{"$ref":"#/components/schemas/OpenAPISpecProcessingErrorCode"},"lastProcessedErrors":{"type":"array","items":{"$ref":"#/components/schemas/OpenAPIErrorObject"}},"lastProcessedErrorCount":{"type":"integer","minimum":0,"description":"Total number of processing errors before truncation of lastProcessedErrors."},"permissions":{"type":"object","description":"The set of permissions for the OpenAPI specification.","required":["view","edit"],"properties":{"view":{"type":"boolean","description":"Can the user view the specification."},"edit":{"type":"boolean","description":"Can the user edit the specification."}}},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"description":"URL of the OpenAPI specification in the API","$ref":"#/components/schemas/URL"},"app":{"description":"URL of the OpenAPI specification in the application","$ref":"#/components/schemas/URL"},"published":{"type":"string","description":"URL of the published spec. Only defined when visibility is \"published.\"","format":"uri"}},"required":["app","location"]}},"required":["object","id","createdAt","updatedAt","slug","processingState","lastProcessedErrorCount","permissions","urls"]},"Timestamp":{"type":"string","format":"date-time"},"OpenAPISpecProcessingState":{"description":"Processing state","enum":["pending","progress","complete"]},"OpenAPISpecVisibility":{"type":"string","description":"The visibility setting of the OpenAPI spec.\n* `private`: The spec is not publicly available.\n* `public`: The spec is available to anyone with a public link.\n","enum":["private","public"]},"OpenAPISpecProcessingErrorCode":{"description":"OpenAPI processing error code","enum":["FETCH_TIMEOUT","FETCH_ERROR","PARSE_ERROR"]},"OpenAPIErrorObject":{"type":"object","description":"OpenAPI error object.","properties":{"message":{"type":"string","description":"Description of the error."},"code":{"type":"string","description":"Unique code of the error."}},"required":["message"]}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[400]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/orgs/{organizationId}/openapi":{"post":{"operationId":"createOpenAPISpec","summary":"Create an OpenAPI spec","tags":["openapi"],"parameters":[{"$ref":"#/components/parameters/organizationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"$ref":"#/components/schemas/OpenAPISpecSlug"},"source":{"$ref":"#/components/schemas/OpenAPISpecSource"}},"required":["source","slug"]}}}},"responses":{"201":{"description":"OpenAPI specification has been created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAPISpec"}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}}}}
```

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

> Get an OpenAPI spec by its slug

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi","description":"The OpenAPI endpoints let you integrate your existing or newly generated OpenAPI definitions into GitBook. This includes uploading, updating, and retrieving specs.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpec\" grouped=\"false\" %}\n    The OpenAPISpec 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"},"OpenAPISpec":{"type":"object","properties":{"object":{"description":"The object type, which is always \"openapi-spec\"","type":"string","enum":["openapi-spec"]},"id":{"description":"Unique identifier","type":"string"},"createdAt":{"description":"Date of creation","$ref":"#/components/schemas/Timestamp"},"updatedAt":{"description":"Date of the last update","$ref":"#/components/schemas/Timestamp"},"slug":{"$ref":"#/components/schemas/OpenAPISpecSlug"},"sourceURL":{"$ref":"#/components/schemas/URL"},"processingState":{"$ref":"#/components/schemas/OpenAPISpecProcessingState"},"visibility":{"$ref":"#/components/schemas/OpenAPISpecVisibility"},"lastVersion":{"type":"string","description":"ID of the latest version of the OpenAPI specification"},"lastProcessedAt":{"description":"Date of the last processing","$ref":"#/components/schemas/Timestamp"},"lastProcessErrorCode":{"$ref":"#/components/schemas/OpenAPISpecProcessingErrorCode"},"lastProcessedErrors":{"type":"array","items":{"$ref":"#/components/schemas/OpenAPIErrorObject"}},"lastProcessedErrorCount":{"type":"integer","minimum":0,"description":"Total number of processing errors before truncation of lastProcessedErrors."},"permissions":{"type":"object","description":"The set of permissions for the OpenAPI specification.","required":["view","edit"],"properties":{"view":{"type":"boolean","description":"Can the user view the specification."},"edit":{"type":"boolean","description":"Can the user edit the specification."}}},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"description":"URL of the OpenAPI specification in the API","$ref":"#/components/schemas/URL"},"app":{"description":"URL of the OpenAPI specification in the application","$ref":"#/components/schemas/URL"},"published":{"type":"string","description":"URL of the published spec. Only defined when visibility is \"published.\"","format":"uri"}},"required":["app","location"]}},"required":["object","id","createdAt","updatedAt","slug","processingState","lastProcessedErrorCount","permissions","urls"]},"Timestamp":{"type":"string","format":"date-time"},"OpenAPISpecSlug":{"description":"Slug used as reference","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$"},"URL":{"type":"string","format":"uri","maxLength":2048},"OpenAPISpecProcessingState":{"description":"Processing state","enum":["pending","progress","complete"]},"OpenAPISpecVisibility":{"type":"string","description":"The visibility setting of the OpenAPI spec.\n* `private`: The spec is not publicly available.\n* `public`: The spec is available to anyone with a public link.\n","enum":["private","public"]},"OpenAPISpecProcessingErrorCode":{"description":"OpenAPI processing error code","enum":["FETCH_TIMEOUT","FETCH_ERROR","PARSE_ERROR"]},"OpenAPIErrorObject":{"type":"object","description":"OpenAPI error object.","properties":{"message":{"type":"string","description":"Description of the error."},"code":{"type":"string","description":"Unique code of the error."}},"required":["message"]}},"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}":{"get":{"operationId":"getOpenAPISpecBySlug","summary":"Get an OpenAPI spec by its slug","tags":["openapi"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/openapiSpecSlug"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAPISpec"}}}},"404":{"description":"No matching OpenAPI specification found","$ref":"#/components/responses/NotFoundError"}}}}}}
```

## PUT /orgs/{organizationId}/openapi/{specSlug}

> Create or update an OpenAPI spec

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi","description":"The OpenAPI endpoints let you integrate your existing or newly generated OpenAPI definitions into GitBook. This includes uploading, updating, and retrieving specs.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpec\" grouped=\"false\" %}\n    The OpenAPISpec 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"},"OpenAPISpecSource":{"oneOf":[{"description":"Create a specification from an URL","type":"object","properties":{"url":{"$ref":"#/components/schemas/URL"}},"required":["url"]},{"description":"Create a specification from a text string","type":"object","properties":{"text":{"description":"OpenAPI specification as text","type":"string","minLength":1}},"required":["text"]}]},"URL":{"type":"string","format":"uri","maxLength":2048},"OpenAPISpec":{"type":"object","properties":{"object":{"description":"The object type, which is always \"openapi-spec\"","type":"string","enum":["openapi-spec"]},"id":{"description":"Unique identifier","type":"string"},"createdAt":{"description":"Date of creation","$ref":"#/components/schemas/Timestamp"},"updatedAt":{"description":"Date of the last update","$ref":"#/components/schemas/Timestamp"},"slug":{"$ref":"#/components/schemas/OpenAPISpecSlug"},"sourceURL":{"$ref":"#/components/schemas/URL"},"processingState":{"$ref":"#/components/schemas/OpenAPISpecProcessingState"},"visibility":{"$ref":"#/components/schemas/OpenAPISpecVisibility"},"lastVersion":{"type":"string","description":"ID of the latest version of the OpenAPI specification"},"lastProcessedAt":{"description":"Date of the last processing","$ref":"#/components/schemas/Timestamp"},"lastProcessErrorCode":{"$ref":"#/components/schemas/OpenAPISpecProcessingErrorCode"},"lastProcessedErrors":{"type":"array","items":{"$ref":"#/components/schemas/OpenAPIErrorObject"}},"lastProcessedErrorCount":{"type":"integer","minimum":0,"description":"Total number of processing errors before truncation of lastProcessedErrors."},"permissions":{"type":"object","description":"The set of permissions for the OpenAPI specification.","required":["view","edit"],"properties":{"view":{"type":"boolean","description":"Can the user view the specification."},"edit":{"type":"boolean","description":"Can the user edit the specification."}}},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"description":"URL of the OpenAPI specification in the API","$ref":"#/components/schemas/URL"},"app":{"description":"URL of the OpenAPI specification in the application","$ref":"#/components/schemas/URL"},"published":{"type":"string","description":"URL of the published spec. Only defined when visibility is \"published.\"","format":"uri"}},"required":["app","location"]}},"required":["object","id","createdAt","updatedAt","slug","processingState","lastProcessedErrorCount","permissions","urls"]},"Timestamp":{"type":"string","format":"date-time"},"OpenAPISpecSlug":{"description":"Slug used as reference","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$"},"OpenAPISpecProcessingState":{"description":"Processing state","enum":["pending","progress","complete"]},"OpenAPISpecVisibility":{"type":"string","description":"The visibility setting of the OpenAPI spec.\n* `private`: The spec is not publicly available.\n* `public`: The spec is available to anyone with a public link.\n","enum":["private","public"]},"OpenAPISpecProcessingErrorCode":{"description":"OpenAPI processing error code","enum":["FETCH_TIMEOUT","FETCH_ERROR","PARSE_ERROR"]},"OpenAPIErrorObject":{"type":"object","description":"OpenAPI error object.","properties":{"message":{"type":"string","description":"Description of the error."},"code":{"type":"string","description":"Unique code of the error."}},"required":["message"]}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[400]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/orgs/{organizationId}/openapi/{specSlug}":{"put":{"operationId":"createOrUpdateOpenAPISpecBySlug","summary":"Create or update an OpenAPI spec","tags":["openapi"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/openapiSpecSlug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/OpenAPISpecSource"}},"required":["source"]}}}},"responses":{"200":{"description":"OpenAPI specification has been updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAPISpec"}}}},"201":{"description":"OpenAPI specification has been created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAPISpec"}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}}}}
```

## DELETE /orgs/{organizationId}/openapi/{specSlug}

> Delete an OpenAPI spec

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi","description":"The OpenAPI endpoints let you integrate your existing or newly generated OpenAPI definitions into GitBook. This includes uploading, updating, and retrieving specs.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpec\" grouped=\"false\" %}\n    The OpenAPISpec 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"}}},"paths":{"/orgs/{organizationId}/openapi/{specSlug}":{"delete":{"operationId":"deleteOpenAPISpecBySlug","summary":"Delete an OpenAPI spec","tags":["openapi"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/openapiSpecSlug"}],"responses":{"204":{"description":"Specification did not exist"},"205":{"description":"OpenAPI specification has been deleted"}}}}}}
```

## PATCH /orgs/{organizationId}/openapi/{specSlug}

> Update OpenAPI spec visibility

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"openapi","description":"The OpenAPI endpoints let you integrate your existing or newly generated OpenAPI definitions into GitBook. This includes uploading, updating, and retrieving specs.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpec\" grouped=\"false\" %}\n    The OpenAPISpec 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"},"OpenAPISpecVisibility":{"type":"string","description":"The visibility setting of the OpenAPI spec.\n* `private`: The spec is not publicly available.\n* `public`: The spec is available to anyone with a public link.\n","enum":["private","public"]},"OpenAPISpec":{"type":"object","properties":{"object":{"description":"The object type, which is always \"openapi-spec\"","type":"string","enum":["openapi-spec"]},"id":{"description":"Unique identifier","type":"string"},"createdAt":{"description":"Date of creation","$ref":"#/components/schemas/Timestamp"},"updatedAt":{"description":"Date of the last update","$ref":"#/components/schemas/Timestamp"},"slug":{"$ref":"#/components/schemas/OpenAPISpecSlug"},"sourceURL":{"$ref":"#/components/schemas/URL"},"processingState":{"$ref":"#/components/schemas/OpenAPISpecProcessingState"},"visibility":{"$ref":"#/components/schemas/OpenAPISpecVisibility"},"lastVersion":{"type":"string","description":"ID of the latest version of the OpenAPI specification"},"lastProcessedAt":{"description":"Date of the last processing","$ref":"#/components/schemas/Timestamp"},"lastProcessErrorCode":{"$ref":"#/components/schemas/OpenAPISpecProcessingErrorCode"},"lastProcessedErrors":{"type":"array","items":{"$ref":"#/components/schemas/OpenAPIErrorObject"}},"lastProcessedErrorCount":{"type":"integer","minimum":0,"description":"Total number of processing errors before truncation of lastProcessedErrors."},"permissions":{"type":"object","description":"The set of permissions for the OpenAPI specification.","required":["view","edit"],"properties":{"view":{"type":"boolean","description":"Can the user view the specification."},"edit":{"type":"boolean","description":"Can the user edit the specification."}}},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"description":"URL of the OpenAPI specification in the API","$ref":"#/components/schemas/URL"},"app":{"description":"URL of the OpenAPI specification in the application","$ref":"#/components/schemas/URL"},"published":{"type":"string","description":"URL of the published spec. Only defined when visibility is \"published.\"","format":"uri"}},"required":["app","location"]}},"required":["object","id","createdAt","updatedAt","slug","processingState","lastProcessedErrorCount","permissions","urls"]},"Timestamp":{"type":"string","format":"date-time"},"OpenAPISpecSlug":{"description":"Slug used as reference","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$"},"URL":{"type":"string","format":"uri","maxLength":2048},"OpenAPISpecProcessingState":{"description":"Processing state","enum":["pending","progress","complete"]},"OpenAPISpecProcessingErrorCode":{"description":"OpenAPI processing error code","enum":["FETCH_TIMEOUT","FETCH_ERROR","PARSE_ERROR"]},"OpenAPIErrorObject":{"type":"object","description":"OpenAPI error object.","properties":{"message":{"type":"string","description":"Description of the error."},"code":{"type":"string","description":"Unique code of the error."}},"required":["message"]}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[400]},"message":{"type":"string"}},"required":["code","message"]}}}}}},"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}":{"patch":{"operationId":"updateOpenAPISpecBySlug","summary":"Update OpenAPI spec visibility","tags":["openapi"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/openapiSpecSlug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"visibility":{"$ref":"#/components/schemas/OpenAPISpecVisibility"}},"required":["visibility"]}}}},"responses":{"200":{"description":"OpenAPI specification visibility has been updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAPISpec"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"description":"No matching OpenAPI specification found","$ref":"#/components/responses/NotFoundError"}}}}}}
```