Create an OpenAPI spec

Adds an OpenAPI spec to the organization, from a URL or from its text. The spec is processed asynchronously and no page is created: to publish its API reference in a space, insert a page that renders it with an insert_computed_page change, through the updateChangeRequestContent operation. That reference fills in once processing completes and is regenerated each time the spec is updated.

Available in MCP

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

Body

slugstring · min: 1 · max: 100Required

Slug used as reference

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

sourceone ofRequired

or

Responses

201

OpenAPI specification has been created

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.

400

Bad Request

application/json

post/orgs/{organizationId}/openapi

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

{
  "slug": "text",
  "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"
  }
}