The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

OpenAPI

Manage API documentation that follows the OpenAPI specification.

List all the OpenAPI specifications in the organization

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "openapi-spec",
      "id": "text",
      "createdAt": "2025-04-03T19:40:33.668Z",
      "updatedAt": "2025-04-03T19:40:33.668Z",
      "slug": "text",
      "sourceURL": "https://example.com",
      "processingState": "pending",
      "lastVersion": "text",
      "lastProcessedAt": "2025-04-03T19:40:33.668Z",
      "lastProcessErrorCode": "FETCH_TIMEOUT",
      "permissions": {
        "edit": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      }
    }
  ]
}

OK

Create an organization OpenAPI specification

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
slugstring · min: 1 · max: 100required

Slug used as reference

Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
sourceone ofrequired

Create a specification from an URL

Create a specification from a text string

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "slug": "text",
    "source": {
      "url": "https://example.com"
    }
  }'
{
  "object": "openapi-spec",
  "id": "text",
  "createdAt": "2025-04-03T19:40:33.668Z",
  "updatedAt": "2025-04-03T19:40:33.668Z",
  "slug": "text",
  "sourceURL": "https://example.com",
  "processingState": "pending",
  "lastVersion": "text",
  "lastProcessedAt": "2025-04-03T19:40:33.668Z",
  "lastProcessErrorCode": "FETCH_TIMEOUT",
  "permissions": {
    "edit": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OpenAPI specification has been created

Get an organization OpenAPI specification by its slug

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "openapi-spec",
  "id": "text",
  "createdAt": "2025-04-03T19:40:33.668Z",
  "updatedAt": "2025-04-03T19:40:33.668Z",
  "slug": "text",
  "sourceURL": "https://example.com",
  "processingState": "pending",
  "lastVersion": "text",
  "lastProcessedAt": "2025-04-03T19:40:33.668Z",
  "lastProcessErrorCode": "FETCH_TIMEOUT",
  "permissions": {
    "edit": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OK

Create or update an organization OpenAPI specification by its slug

put
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
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"
    }
  }'
{
  "object": "openapi-spec",
  "id": "text",
  "createdAt": "2025-04-03T19:40:33.668Z",
  "updatedAt": "2025-04-03T19:40:33.668Z",
  "slug": "text",
  "sourceURL": "https://example.com",
  "processingState": "pending",
  "lastVersion": "text",
  "lastProcessedAt": "2025-04-03T19:40:33.668Z",
  "lastProcessErrorCode": "FETCH_TIMEOUT",
  "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
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

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

OpenAPI specification has been deleted

List all the OpenAPI specification versions

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "openapi-spec-version",
      "id": "text",
      "createdAt": "2025-04-03T19:40:33.668Z",
      "url": "https://example.com",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      }
    }
  ]
}

OK

Get the latest OpenAPI specification version

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/latest' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "openapi-spec-version",
  "id": "text",
  "createdAt": "2025-04-03T19:40:33.668Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OK

Get the latest OpenAPI specification version content

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

specSlugstringrequired

Slug of the OpenAPI specification

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

OK

Get an OpenAPI specification version by its ID

get
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
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "openapi-spec-version",
  "id": "text",
  "createdAt": "2025-04-03T19:40:33.668Z",
  "url": "https://example.com",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

OK

Get an OpenAPI specification version content by its ID

get
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
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "filesystem": {},
  "url": "https://example.com"
}

OK

Was this helpful?