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"

Allowed 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 · enumRequiredAllowed values:
useCasestring · enumOptionalAllowed values:
communityTypestring · enumOptionalAllowed 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.

Allowed 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

Allowed values:
customHostnamestringOptional

Custom hostname linked to this organization

internal_isOnNewTrialbooleanOptional

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

The Organization object

{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2025-04-21T17:14:51.717Z",
  "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-21T17:14:51.717Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-04-21T17:14:51.717Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_isOnNewTrial": true,
  "internal_billingMigration": {
    "deadline": "2025-04-21T17:14:51.717Z",
    "discountPercent": 1,
    "discountEndDate": "2025-04-21T17:14:51.717Z"
  },
  "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-21T17:14:51.717Z",
      "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-21T17:14:51.717Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-04-21T17:14:51.717Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "reason": "security"
      },
      "internal_isOnNewTrial": true,
      "internal_billingMigration": {
        "deadline": "2025-04-21T17:14:51.717Z",
        "discountPercent": 1,
        "discountEndDate": "2025-04-21T17:14:51.717Z"
      },
      "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
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-21T17:14:51.717Z",
  "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-21T17:14:51.717Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-04-21T17:14:51.717Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_isOnNewTrial": true,
  "internal_billingMigration": {
    "deadline": "2025-04-21T17:14:51.717Z",
    "discountPercent": 1,
    "discountEndDate": "2025-04-21T17:14:51.717Z"
  },
  "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

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.

Allowed values:
defaultContentone ofOptional
string · enum | nullableOptionalAllowed values:
logoone ofOptional
string · uri · max: 2048Optional
string · enum | nullableOptionalAllowed values:
ssobooleanOptional
aibooleanOptional
inviteLinksbooleanOptional
Responses
application/json
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-21T17:14:51.717Z",
  "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-21T17:14:51.717Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-04-21T17:14:51.717Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_isOnNewTrial": true,
  "internal_billingMigration": {
    "deadline": "2025-04-21T17:14:51.717Z",
    "discountPercent": 1,
    "discountEndDate": "2025-04-21T17:14:51.717Z"
  },
  "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

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
Responses
application/json
one ofOptional

An invite link created 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
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-21T17:14:51.717Z",
      "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-21T17:14:51.717Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-04-21T17:14:51.717Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "reason": "security"
      },
      "internal_isOnNewTrial": true,
      "internal_billingMigration": {
        "deadline": "2025-04-21T17:14:51.717Z",
        "discountPercent": 1,
        "discountEndDate": "2025-04-21T17:14:51.717Z"
      },
      "permissions": {
        "admin": true,
        "createContent": true
      }
    }
  ]
}

Was this helpful?