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

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"

Available options:
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 · enumrequiredAvailable options:
useCasestring · enumoptionalAvailable options:
communityTypestring · enumoptionalAvailable options:
defaultRoleone ofoptional

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

"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.

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

Available options:
billingobjectoptional

Billing details, only available for org members.

urlsobjectrequired

URLs associated with the object

trialobjectrequired
customHostnamestringoptional

Custom hostname linked to this organization

blockedobjectoptional

If the organization is blocked, information about the block will appear here

internal_isOnNewTrialbooleanoptional

If true, the organization is on the new trial which includes sites and the Pro plan.

internal_billingMigrationobjectoptional
permissionsobjectrequired

The set of permissions for the organization

The Organization object

{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2025-04-16T04:38:06.585Z",
  "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-04-16T04:38:06.585Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-04-16T04:38:06.585Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_isOnNewTrial": true,
  "internal_billingMigration": {
    "deadline": "2025-04-16T04:38:06.585Z",
    "discountPercent": 1,
    "discountEndDate": "2025-04-16T04:38:06.585Z"
  },
  "permissions": {
    "admin": true,
    "createContent": 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
application/json
all ofoptional
get
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-04-16T04:38:06.585Z",
      "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-04-16T04:38:06.585Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-04-16T04:38:06.585Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "reason": "security"
      },
      "internal_isOnNewTrial": true,
      "internal_billingMigration": {
        "deadline": "2025-04-16T04:38:06.585Z",
        "discountPercent": 1,
        "discountEndDate": "2025-04-16T04:38:06.585Z"
      },
      "permissions": {
        "admin": true,
        "createContent": true
      }
    }
  ]
}

Get an organization by its ID

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Responses
application/json
objectoptional
get
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-04-16T04:38:06.585Z",
  "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-04-16T04:38:06.585Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-04-16T04:38:06.585Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_isOnNewTrial": true,
  "internal_billingMigration": {
    "deadline": "2025-04-16T04:38:06.585Z",
    "discountPercent": 1,
    "discountEndDate": "2025-04-16T04:38:06.585Z"
  },
  "permissions": {
    "admin": true,
    "createContent": 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

"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.

defaultContentone ofoptional
logoone ofoptional
ssobooleanoptional
aibooleanoptional
inviteLinksbooleanoptional
Responses
application/json
objectoptional
patch
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-04-16T04:38:06.585Z",
  "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-04-16T04:38:06.585Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-04-16T04:38:06.585Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_isOnNewTrial": true,
  "internal_billingMigration": {
    "deadline": "2025-04-16T04:38:06.585Z",
    "discountPercent": 1,
    "discountEndDate": "2025-04-16T04:38:06.585Z"
  },
  "permissions": {
    "admin": true,
    "createContent": 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
application/json
one ofoptional

An invite link created in an organization

An invite link to an organization

An invite link to a specific space in an organization

An invite link to a specific collection in an organization

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

Deletes an organization invite.

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

inviteIdstringrequired

The unique id of the invite

Responses
delete
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

Update role of an organization invite

Update level of an organization content invite

Responses
application/json
one ofoptional

An invite link created in an organization

An invite link to an organization

An invite link to a specific space in an organization

An invite link to a specific collection in an organization

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

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
application/json
all ofoptional
get
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
application/json
objectoptional
get
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-04-16T04:38:06.585Z",
      "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-04-16T04:38:06.585Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-04-16T04:38:06.585Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "reason": "security"
      },
      "internal_isOnNewTrial": true,
      "internal_billingMigration": {
        "deadline": "2025-04-16T04:38:06.585Z",
        "discountPercent": 1,
        "discountEndDate": "2025-04-16T04:38:06.585Z"
      },
      "permissions": {
        "admin": true,
        "createContent": true
      }
    }
  ]
}

Was this helpful?