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:

mergeRulesone ofRequired

or

customHostnamestringOptional

Custom hostname linked to this organization

The Organization object

{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2026-01-23T12:08:47.042Z",
  "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": "2026-01-23T12:08:47.042Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true,
    "pricing": {
      "members": {
        "plus_2024": {
          "monthly": 1,
          "yearly": 1
        },
        "pro_2024": {
          "monthly": 1,
          "yearly": 1
        }
      },
      "sites": {
        "premium": {
          "monthly": 1,
          "yearly": 1
        },
        "ultimate": {
          "monthly": 1,
          "yearly": 1
        }
      }
    },
    "usageAddons": {
      "ANY_ADDITIONAL_PROPERTY": {
        "enabled": true
      }
    },
    "minUsers": 1,
    "maxUsers": 1,
    "paidMembers": 1
  },
  "mergeRules": {
    "type": "rules",
    "rules": [
      {
        "rule": "require_specific_reviewers",
        "users": [
          "text"
        ]
      }
    ]
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "count": 1,
    "endDate": "2026-01-23T12:08:47.042Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "source": "backoffice",
    "reason": "text"
  },
  "internal_billingMigration": {
    "deadline": "2026-01-23T12:08:47.042Z",
    "discountPercent": 1,
    "discountEndDate": "2026-01-23T12:08:47.042Z"
  },
  "permissions": {
    "view": true,
    "admin": true,
    "ownTeam": true,
    "createContent": true,
    "createOpenAPISpec": true,
    "ingestConversations": true,
    "viewBilling": true,
    "listMembers": true,
    "listTeams": true,
    "listIntegrations": true,
    "listInstallations": true,
    "installIntegration": true
  }
}

Get the list of organizations for the currently authenticated user

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

get

/orgs

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": "2026-01-23T12:08:47.042Z",
      "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": "2026-01-23T12:08:47.042Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true,
        "pricing": {
          "members": {
            "plus_2024": {
              "monthly": 1,
              "yearly": 1
            },
            "pro_2024": {
              "monthly": 1,
              "yearly": 1
            }
          },
          "sites": {
            "premium": {
              "monthly": 1,
              "yearly": 1
            },
            "ultimate": {
              "monthly": 1,
              "yearly": 1
            }
          }
        },
        "usageAddons": {
          "ANY_ADDITIONAL_PROPERTY": {
            "enabled": true
          }
        },
        "minUsers": 1,
        "maxUsers": 1,
        "paidMembers": 1
      },
      "mergeRules": {
        "type": "rules",
        "rules": [
          {
            "rule": "require_specific_reviewers",
            "users": [
              "text"
            ]
          }
        ]
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "count": 1,
        "endDate": "2026-01-23T12:08:47.042Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "source": "backoffice",
        "reason": "text"
      },
      "internal_billingMigration": {
        "deadline": "2026-01-23T12:08:47.042Z",
        "discountPercent": 1,
        "discountEndDate": "2026-01-23T12:08:47.042Z"
      },
      "permissions": {
        "view": true,
        "admin": true,
        "ownTeam": true,
        "createContent": true,
        "createOpenAPISpec": true,
        "ingestConversations": true,
        "viewBilling": true,
        "listMembers": true,
        "listTeams": true,
        "listIntegrations": true,
        "listInstallations": true,
        "installIntegration": true
      }
    }
  ]
}

Get an organization by its ID

get

Authorizations

useruser-internaluser-staffuser-internal-or-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/orgs/{organizationId}

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": "2026-01-23T12:08:47.042Z",
  "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": "2026-01-23T12:08:47.042Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true,
    "pricing": {
      "members": {
        "plus_2024": {
          "monthly": 1,
          "yearly": 1
        },
        "pro_2024": {
          "monthly": 1,
          "yearly": 1
        }
      },
      "sites": {
        "premium": {
          "monthly": 1,
          "yearly": 1
        },
        "ultimate": {
          "monthly": 1,
          "yearly": 1
        }
      }
    },
    "usageAddons": {
      "ANY_ADDITIONAL_PROPERTY": {
        "enabled": true
      }
    },
    "minUsers": 1,
    "maxUsers": 1,
    "paidMembers": 1
  },
  "mergeRules": {
    "type": "rules",
    "rules": [
      {
        "rule": "require_specific_reviewers",
        "users": [
          "text"
        ]
      }
    ]
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "count": 1,
    "endDate": "2026-01-23T12:08:47.042Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "source": "backoffice",
    "reason": "text"
  },
  "internal_billingMigration": {
    "deadline": "2026-01-23T12:08:47.042Z",
    "discountPercent": 1,
    "discountEndDate": "2026-01-23T12:08:47.042Z"
  },
  "permissions": {
    "view": true,
    "admin": true,
    "ownTeam": true,
    "createContent": true,
    "createOpenAPISpec": true,
    "ingestConversations": true,
    "viewBilling": true,
    "listMembers": true,
    "listTeams": true,
    "listIntegrations": true,
    "listInstallations": true,
    "installIntegration": true
  }
}

Update an organization

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Body

application/json

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

mergeRulesone ofOptional

or

Responses

200

The organization has been updated

application/json

400

Invalid default content space or collection provided

application/json

patch

/orgs/{organizationId}

HTTPcURLJavaScriptPython

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

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

{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2026-01-23T12:08:47.042Z",
  "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": "2026-01-23T12:08:47.042Z",
    "hasPaymentFailed": true,
    "isScheduledToCancel": true,
    "pricing": {
      "members": {
        "plus_2024": {
          "monthly": 1,
          "yearly": 1
        },
        "pro_2024": {
          "monthly": 1,
          "yearly": 1
        }
      },
      "sites": {
        "premium": {
          "monthly": 1,
          "yearly": 1
        },
        "ultimate": {
          "monthly": 1,
          "yearly": 1
        }
      }
    },
    "usageAddons": {
      "ANY_ADDITIONAL_PROPERTY": {
        "enabled": true
      }
    },
    "minUsers": 1,
    "maxUsers": 1,
    "paidMembers": 1
  },
  "mergeRules": {
    "type": "rules",
    "rules": [
      {
        "rule": "require_specific_reviewers",
        "users": [
          "text"
        ]
      }
    ]
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "count": 1,
    "endDate": "2026-01-23T12:08:47.042Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "source": "backoffice",
    "reason": "text"
  },
  "internal_billingMigration": {
    "deadline": "2026-01-23T12:08:47.042Z",
    "discountPercent": 1,
    "discountEndDate": "2026-01-23T12:08:47.042Z"
  },
  "permissions": {
    "view": true,
    "admin": true,
    "ownTeam": true,
    "createContent": true,
    "createOpenAPISpec": true,
    "ingestConversations": true,
    "viewBilling": true,
    "listMembers": true,
    "listTeams": true,
    "listIntegrations": true,
    "listInstallations": true,
    "installIntegration": true
  }
}

Deletes an organization invite.

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

inviteIdstringRequired

The unique id of the invite

Responses

204

Organization invite did not exist

205

The organization invite has been deleted

delete

/orgs/{organizationId}/link-invites/{inviteId}

HTTPcURLJavaScriptPython

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

No content

Join an organization

post

Join an organization if the user's verified email domain matches one of the organization's allowed email domains. This endpoint allows existing users to join organizations they're eligible for based on their email domain.

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Responses

204

Successfully joined the organization

400

User's email domain is not valid

application/json

404

Organization not found

application/json

post

/orgs/{organizationId}/join

HTTPcURLJavaScriptPython

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

No content

Search content in an organization

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

get

/orgs/{organizationId}/search

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/search?query=text 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"
              }
            }
          ],
          "ancestors": [
            {
              "title": "text"
            }
          ],
          "urls": {
            "app": "https://example.com"
          }
        }
      ]
    }
  ]
}

Get Docs agent instructions for an organization

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Responses

200

OK

application/json

get

/orgs/{organizationId}/agent-instructions

HTTPcURLJavaScriptPython

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

200

OK

{
  "object": "agent-instructions",
  "instructions": {
    "object": "document",
    "data": {
      "schemaVersion": 1,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "key": "text",
        "nodes": [
          "[Circular Reference]"
        ],
        "isVoid": false,
        "data": {
          "align": "start"
        }
      }
    ],
    "meta": {
      "token": "text"
    }
  },
  "updatedAt": "2026-01-23T12:08:47.042Z",
  "updatedBy": "text",
  "urls": {
    "location": "text"
  }
}

Update Docs agent instructions for an organization

put

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Body

application/json

Responses

200

Updated instructions

application/json

put

/orgs/{organizationId}/agent-instructions

HTTPcURLJavaScriptPython

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

{
  "instructions": {
    "object": "document",
    "data": {
      "schemaVersion": 1,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "key": "text",
        "nodes": [
          "[Circular Reference]"
        ],
        "isVoid": false,
        "data": {
          "align": "start"
        }
      }
    ],
    "meta": {
      "token": "text"
    }
  }
}

200

Updated instructions

{
  "object": "agent-instructions",
  "instructions": {
    "object": "document",
    "data": {
      "schemaVersion": 1,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "key": "text",
        "nodes": [
          "[Circular Reference]"
        ],
        "isVoid": false,
        "data": {
          "align": "start"
        }
      }
    ],
    "meta": {
      "token": "text"
    }
  },
  "updatedAt": "2026-01-23T12:08:47.042Z",
  "updatedBy": "text",
  "urls": {
    "location": "text"
  }
}

Get all organizations by email domain

get

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

emailDomainstringRequired

Email domain

Responses

200

OK

application/json

get

/email-domains/{emailDomain}/orgs

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": "2026-01-23T12:08:47.042Z",
      "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": "2026-01-23T12:08:47.042Z",
        "hasPaymentFailed": true,
        "isScheduledToCancel": true,
        "pricing": {
          "members": {
            "plus_2024": {
              "monthly": 1,
              "yearly": 1
            },
            "pro_2024": {
              "monthly": 1,
              "yearly": 1
            }
          },
          "sites": {
            "premium": {
              "monthly": 1,
              "yearly": 1
            },
            "ultimate": {
              "monthly": 1,
              "yearly": 1
            }
          }
        },
        "usageAddons": {
          "ANY_ADDITIONAL_PROPERTY": {
            "enabled": true
          }
        },
        "minUsers": 1,
        "maxUsers": 1,
        "paidMembers": 1
      },
      "mergeRules": {
        "type": "rules",
        "rules": [
          {
            "rule": "require_specific_reviewers",
            "users": [
              "text"
            ]
          }
        ]
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "count": 1,
        "endDate": "2026-01-23T12:08:47.042Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "source": "backoffice",
        "reason": "text"
      },
      "internal_billingMigration": {
        "deadline": "2026-01-23T12:08:47.042Z",
        "discountPercent": 1,
        "discountEndDate": "2026-01-23T12:08:47.042Z"
      },
      "permissions": {
        "view": true,
        "admin": true,
        "ownTeam": true,
        "createContent": true,
        "createOpenAPISpec": true,
        "ingestConversations": true,
        "viewBilling": true,
        "listMembers": true,
        "listTeams": true,
        "listIntegrations": true,
        "listInstallations": true,
        "installIntegration": true
      }
    }
  ]
}