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.

objectstring · enumrequired

Type of Object, always equals to "organization"

Options: organization

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 · enumrequired

Options: business, community

useCasestring · enumoptional

Options: internalDocs, docsSite, audienceControlledSite, productDocs, teamKnowledgeBase, designSystem, openSourceDocs, notes, other

communityTypestring · enumoptional

Options: nonProfit, openSource, education

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

Options: free_2024, plus_2024, pro_2024, enterprise_2024, community_2024, free, plus, pro, team, business, legacy, startup, enterprise, community, team_oct_2019_free, team_dec_2021, business_dec_2021

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

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

cURL

JavaScript

Python

HTTP

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

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "organization",
      "id": "text",
      "title": "text",
      "createdAt": "2025-04-16T19:43:56.719Z",
      "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-16T19:43:56.719Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-04-16T19:43:56.719Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "reason": "security"
      },
      "internal_isOnNewTrial": true,
      "internal_billingMigration": {
        "deadline": "2025-04-16T19:43:56.719Z",
        "discountPercent": 1,
        "discountEndDate": "2025-04-16T19:43:56.719Z"
      },
      "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

cURL

JavaScript

Python

HTTP

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

200

404

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

defaultContentone ofoptional

logoone ofoptional

ssobooleanoptional

aibooleanoptional

inviteLinksbooleanoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "emailDomains": [
      "text"
    ],
    "hostname": "text",
    "defaultRole": "admin",
    "defaultContent": {
      "type": "site",
      "site": "text"
    },
    "logo": "https://example.com",
    "sso": true,
    "ai": true,
    "inviteLinks": true
  }'

200

400

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

The organization has been updated

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

cURL

JavaScript

Python

HTTP

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

200

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

Invite link in the organization.

Deletes an organization invite.

delete

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

inviteIdstringrequired

The unique id of the invite

Responses

cURL

JavaScript

Python

HTTP

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

205

No body

The organization invite has been deleted

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

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/link-invites/{inviteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'

200

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

The organization invite has been updated

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

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/search?query=text' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

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

cURL

JavaScript

Python

HTTP

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

200

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

Was this helpful?

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Get the list of organizations for the currently authenticated user

Get an organization by its ID

Update an organization

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Get an organization by its ID

Deletes an organization invite.

Update an organization invite

Show child attributes

Show child attributes

Search content in an organization

Get all organizations by email domain