Create or update an OpenAPI spec

Creates the organization's OpenAPI spec with this slug, or replaces its source with a new version. The spec is processed asynchronously, and pages that already render it are regenerated once it is. Creating a spec adds no page: to publish its API reference in a space, insert a page that renders it with an insert_computed_page change, through the updateChangeRequestContent operation.

Available in MCP

put

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

specSlugstringRequired

Slug of the OpenAPI specification

Body

sourceone ofRequired

or

Responses

200

OpenAPI specification has been updated

application/json

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.

201

OpenAPI specification has been created

application/json

400

Bad Request

application/json

put/orgs/{organizationId}/openapi/{specSlug}

PUT /v1/orgs/{organizationId}/openapi/{specSlug} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "source": {
    "url": "https://example.com"
  }
}

{
  "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"
  }
}