OpenAPI

Upload, access, or version-control your OpenAPI specifications directly in GitBook.

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

Attributes

objectstring · enumRequired

The object type, which is always "openapi-spec"

Possible values:

idstringRequired

Unique identifier

createdAtstring · date-timeRequired

Date of creation

updatedAtstring · date-timeRequired

Date of the last update

slugstring · min: 1 · max: 100Required

Slug used as reference

Pattern: ^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$

sourceURLstring · uri · max: 2048Optional

processingStateundefined · enumRequired

Processing state

Possible values:

visibilitystring · enumOptional

The visibility setting of the OpenAPI spec.

• private: The spec is not publicly available.
• public: The spec is available to anyone with a public link.

Possible values:

lastVersionstringOptional

ID of the latest version of the OpenAPI specification

lastProcessedAtstring · date-timeOptional

Date of the last processing

lastProcessErrorCodeundefined · enumOptional

OpenAPI processing error code

Possible values:

lastProcessedErrorCountintegerRequired

Total number of processing errors before truncation of lastProcessedErrors.

The OpenAPISpec object

{
  "object": "openapi-spec",
  "id": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "slug": "text",
  "sourceURL": "https://example.com",
  "processingState": "pending",
  "visibility": "private",
  "lastVersion": "text",
  "lastProcessedAt": "2026-01-01T00:00:00.000Z",
  "lastProcessErrorCode": "FETCH_TIMEOUT",
  "lastProcessedErrors": [
    {
      "message": "text",
      "code": "text"
    }
  ],
  "lastProcessedErrorCount": 1,
  "permissions": {
    "view": true,
    "edit": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}