Organizations

Manage your organizations and group your members, spaces, and resources under one collaborative structure.

The Organizations API provides a robust way to handle the administrative structure of your GitBook workspace. By creating and configuring organizations, you can group multiple users, spaces, and collections, simplifying your permission management and fostering efficient collaboration for teams of any size.

The Organization object

Attributes

objectstring · enumRequired

Type of Object, always equals to "organization"

Possible values:

idstringRequired

Unique identifier for the organization

titlestring · min: 2 · max: 255Required

Name of the organization

createdAtstring · date-timeRequired

emailDomainsstring[]Required

hostnamestring · min: 3 · max: 32Optional

Default hostname for the organization's public content, e.g. .gitbook.io

typestring · enumRequiredPossible values:

useCasestring · enumOptionalPossible values:

communityTypestring · enumOptionalPossible values:

defaultRoleone ofOptional

The role of a member in an organization, null for guests

string · enum | nullableOptional

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Possible values:

defaultContentone ofOptional

The default content for the organization

ssobooleanOptional

Whether SSO is enforced organization-wide

aibooleanOptional

If true, the organization is configured to use all our AI features.

inviteLinksbooleanRequired

If true, invite links are enabled for this organization.

planstring · enumRequired

Name of the product

Possible values:

customHostnamestringOptional

Custom hostname linked to this organization

internal_isOnNewTrialboolean · enumOptionalDeprecated

Deprecated. Always true. All organizations are on new trials.

Possible values:

The Organization object

{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2025-05-05T07:01:10.312Z",
  "emailDomains": [
    "text"
  ],
  "hostname": "text",
  "type": "business",
  "useCase": "internalDocs",
  "communityType": "nonProfit",
  "defaultRole": "admin",
  "defaultContent": {
    "type": "site",
    "site": "text"
  },
  "sso": true,
  "ai": true,
  "inviteLinks": true,
  "plan": "free_2024",
  "billing": {
    "interval": "monthly",
    "endDate": "2025-05-05T07:01:10.312Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-05-05T07:01:10.312Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_billingMigration": {
    "deadline": "2025-05-05T07:01:10.312Z",
    "discountPercent": 1,
    "discountEndDate": "2025-05-05T07:01:10.312Z"
  },
  "permissions": {
    "view": true,
    "admin": true,
    "ownTeam": true,
    "createContent": true,
    "createOpenAPISpec": true,
    "viewBilling": true,
    "listMembers": true,
    "listTeams": true,
    "listIntegrations": true
  }
}

Get the list of organizations for the currently authenticated user

get

Authorizations

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

Responseall of

get

HTTPcURLJavaScriptPython

GET /v1/orgs HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "organization",
      "id": "text",
      "title": "text",
      "createdAt": "2025-05-05T07:01:10.312Z",
      "emailDomains": [
        "text"
      ],
      "hostname": "text",
      "type": "business",
      "useCase": "internalDocs",
      "communityType": "nonProfit",
      "defaultRole": "admin",
      "defaultContent": {
        "type": "site",
        "site": "text"
      },
      "sso": true,
      "ai": true,
      "inviteLinks": true,
      "plan": "free_2024",
      "billing": {
        "interval": "monthly",
        "endDate": "2025-05-05T07:01:10.312Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-05-05T07:01:10.312Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "reason": "security"
      },
      "internal_billingMigration": {
        "deadline": "2025-05-05T07:01:10.312Z",
        "discountPercent": 1,
        "discountEndDate": "2025-05-05T07:01:10.312Z"
      },
      "permissions": {
        "view": true,
        "admin": true,
        "ownTeam": true,
        "createContent": true,
        "createOpenAPISpec": true,
        "viewBilling": true,
        "listMembers": true,
        "listTeams": true,
        "listIntegrations": true
      }
    }
  ]
}

Get an organization by its ID

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

Path parameters

organizationIdstringRequired

The unique id of the organization

Responses

200

OK

application/json

404

No matching organization found for given id

application/json

get

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2025-05-05T07:01:10.312Z",
  "emailDomains": [
    "text"
  ],
  "hostname": "text",
  "type": "business",
  "useCase": "internalDocs",
  "communityType": "nonProfit",
  "defaultRole": "admin",
  "defaultContent": {
    "type": "site",
    "site": "text"
  },
  "sso": true,
  "ai": true,
  "inviteLinks": true,
  "plan": "free_2024",
  "billing": {
    "interval": "monthly",
    "endDate": "2025-05-05T07:01:10.312Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-05-05T07:01:10.312Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_billingMigration": {
    "deadline": "2025-05-05T07:01:10.312Z",
    "discountPercent": 1,
    "discountEndDate": "2025-05-05T07:01:10.312Z"
  },
  "permissions": {
    "view": true,
    "admin": true,
    "ownTeam": true,
    "createContent": true,
    "createOpenAPISpec": true,
    "viewBilling": true,
    "listMembers": true,
    "listTeams": true,
    "listIntegrations": true
  }
}

Update an organization

patch

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

Body

titlestring · min: 2 · max: 255Optional

Name of the organization

emailDomainsstring[]Optional

hostnamestring · min: 3 · max: 32Optional

Default hostname for the organization's public content, e.g. .gitbook.io

defaultRoleone ofOptional

The role of a member in an organization, null for guests

string · enum | nullableOptional

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Possible values:

defaultContentone ofOptional

or

string · enum | nullableOptionalPossible values:

logoone ofOptional

string · uri · max: 2048Optional

or

string · enum | nullableOptionalPossible values:

ssobooleanOptional

aibooleanOptional

inviteLinksbooleanOptional

Responses

200

The organization has been updated

application/json

400

Invalid default content space or collection provided

application/json

patch

HTTPcURLJavaScriptPython

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

{
  "title": "text",
  "emailDomains": [
    "text"
  ],
  "hostname": "text",
  "defaultRole": "admin",
  "defaultContent": {
    "type": "site",
    "site": "text"
  },
  "logo": "https://example.com",
  "sso": true,
  "ai": true,
  "inviteLinks": true
}

{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2025-05-05T07:01:10.312Z",
  "emailDomains": [
    "text"
  ],
  "hostname": "text",
  "type": "business",
  "useCase": "internalDocs",
  "communityType": "nonProfit",
  "defaultRole": "admin",
  "defaultContent": {
    "type": "site",
    "site": "text"
  },
  "sso": true,
  "ai": true,
  "inviteLinks": true,
  "plan": "free_2024",
  "billing": {
    "interval": "monthly",
    "endDate": "2025-05-05T07:01:10.312Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-05-05T07:01:10.312Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_billingMigration": {
    "deadline": "2025-05-05T07:01:10.312Z",
    "discountPercent": 1,
    "discountEndDate": "2025-05-05T07:01:10.312Z"
  },
  "permissions": {
    "view": true,
    "admin": true,
    "ownTeam": true,
    "createContent": true,
    "createOpenAPISpec": true,
    "viewBilling": true,
    "listMembers": true,
    "listTeams": true,
    "listIntegrations": true
  }
}

Get an organization by its ID

get

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

inviteIdstringRequired

The unique id of the invite

Responses

200

Invite link in the organization.

application/json

Responseone of

An invite link created in an organization

or

or

get

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/link-invites/{inviteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Invite link in the organization.

{
  "object": "invite",
  "id": "text",
  "role": "admin",
  "redundant": true
}

Deletes an organization invite.

delete

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

inviteIdstringRequired

The unique id of the invite

Responses

205

The organization invite has been deleted

delete

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/link-invites/{inviteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

205

The organization invite has been deleted

No content

Update an organization invite

patch

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

inviteIdstringRequired

The unique id of the invite

Body

one ofOptional

or

Responses

200

The organization invite has been updated

application/json

Responseone of

An invite link created in an organization

or

or

patch

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/link-invites/{inviteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "role": "admin"
}

200

The organization invite has been updated

{
  "object": "invite",
  "id": "text",
  "role": "admin",
  "redundant": true
}

Search content in an organization

get

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

Query parameters

querystring · max: 512Required

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

Responseall of

get

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/search HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "title": "text",
      "pages": [
        {
          "id": "text",
          "title": "text",
          "path": "text",
          "sections": [
            {
              "id": "text",
              "title": "text",
              "path": "text",
              "body": "text",
              "urls": {
                "app": "https://example.com"
              }
            }
          ],
          "urls": {
            "app": "https://example.com"
          }
        }
      ]
    }
  ]
}

Get all organizations by email domain

get

Authorizations

Path parameters

emailDomainstringRequired

Email domain

Responses

200

OK

application/json

get

HTTPcURLJavaScriptPython

GET /v1/email-domains/{emailDomain}/orgs HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "organizations": [
    {
      "object": "organization",
      "id": "text",
      "title": "text",
      "createdAt": "2025-05-05T07:01:10.312Z",
      "emailDomains": [
        "text"
      ],
      "hostname": "text",
      "type": "business",
      "useCase": "internalDocs",
      "communityType": "nonProfit",
      "defaultRole": "admin",
      "defaultContent": {
        "type": "site",
        "site": "text"
      },
      "sso": true,
      "ai": true,
      "inviteLinks": true,
      "plan": "free_2024",
      "billing": {
        "interval": "monthly",
        "endDate": "2025-05-05T07:01:10.312Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-05-05T07:01:10.312Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "reason": "security"
      },
      "internal_billingMigration": {
        "deadline": "2025-05-05T07:01:10.312Z",
        "discountPercent": 1,
        "discountEndDate": "2025-05-05T07:01:10.312Z"
      },
      "permissions": {
        "view": true,
        "admin": true,
        "ownTeam": true,
        "createContent": true,
        "createOpenAPISpec": true,
        "viewBilling": true,
        "listMembers": true,
        "listTeams": true,
        "listIntegrations": true
      }
    }
  ]
}