OpenAPI

Manage API documentation that follows the OpenAPI specification.

Get the latest OpenAPI specification version

get

/orgs/{organizationId}/openapi/{specSlug}/versions/latest

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/latest' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

200

{
  "id": "text",
  "createdAt": "2025-03-09T02:07:18.230Z",
  "url": "https://example.com",
  "object": "openapi-spec-version",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OK

Get the latest OpenAPI specification version content

get

/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

200

{
  "filesystem": {},
  "url": "https://example.com"
}

OK

Get an OpenAPI specification version by its ID

get

/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

versionIdstringrequired

The unique ID of the OpenAPI specification version

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

200

{
  "id": "text",
  "createdAt": "2025-03-09T02:07:18.230Z",
  "url": "https://example.com",
  "object": "openapi-spec-version",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OK

Get an OpenAPI specification version content by its ID

get

/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

versionIdstringrequired

The unique ID of the OpenAPI specification version

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

200

{
  "filesystem": {},
  "url": "https://example.com"
}

OK

List all the OpenAPI specifications in the organization

get

/orgs/{organizationId}/openapi

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "createdAt": "2025-03-09T02:07:18.230Z",
      "updatedAt": "2025-03-09T02:07:18.230Z",
      "slug": "text",
      "sourceURL": "https://example.com",
      "processingState": "pending",
      "lastVersion": "text",
      "lastProcessedAt": "2025-03-09T02:07:18.230Z",
      "lastProcessErrorCode": "FETCH_TIMEOUT",
      "object": "openapi-spec",
      "permissions": {
        "edit": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      }
    }
  ]
}

OK

Get an organization OpenAPI specification by its slug

get

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

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

200

{
  "id": "text",
  "createdAt": "2025-03-09T02:07:18.230Z",
  "updatedAt": "2025-03-09T02:07:18.230Z",
  "slug": "text",
  "sourceURL": "https://example.com",
  "processingState": "pending",
  "lastVersion": "text",
  "lastProcessedAt": "2025-03-09T02:07:18.230Z",
  "lastProcessErrorCode": "FETCH_TIMEOUT",
  "object": "openapi-spec",
  "permissions": {
    "edit": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OK

Create or update an organization OpenAPI specification by its slug

put

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

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Body

sourceone ofrequired

Create a specification from an URL

Create a specification from a text string

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": {
      "url": "https://example.com"
    }
  }'

200

201

400

default

200

{
  "id": "text",
  "createdAt": "2025-03-09T02:07:18.230Z",
  "updatedAt": "2025-03-09T02:07:18.230Z",
  "slug": "text",
  "sourceURL": "https://example.com",
  "processingState": "pending",
  "lastVersion": "text",
  "lastProcessedAt": "2025-03-09T02:07:18.230Z",
  "lastProcessErrorCode": "FETCH_TIMEOUT",
  "object": "openapi-spec",
  "permissions": {
    "edit": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OpenAPI specification has been updated

Delete an organization OpenAPI specification by its slug

delete

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

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

205

default

205

No body

OpenAPI specification has been deleted

List all the OpenAPI specification versions

get

/orgs/{organizationId}/openapi/{specSlug}/versions

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "createdAt": "2025-03-09T02:07:18.230Z",
      "url": "https://example.com",
      "object": "openapi-spec-version",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      }
    }
  ]
}

OK