Generate Backend docs - Organization API

[alexisintech]

• Generates the /backend/organization/** docs with typedoc
• Adds new pages for the org-domain endpoints (create/get-list/update/delete) and get-instance-organization-membership-list.
• To be merged into the master PR: Generate backend docs MOTHER PR!

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Error		Jun 18, 2026 8:32pm

[SarahSoutoul]

@alexisintech

I’m seeing a set of typedoc/linking warnings from this branch.

A few of the new backend organization-domain pages are linking to /docs/reference/backend/types/backend-organization-domain, but that type page doesn't appear to exist. The same thing is happening for a few other backend type references as well:

• backend-deleted-object-resource
• organization-invitation
• organization-membership

So right now it looks like the new Typedoc-generated references are introducing broken links to backend type pages that aren't present in the docs tree.

I'm also seeing a docs/reference/backend/organization/delete-organization-domain.mdx warning. This doc is not in the manifest.json, but will still be publicly accessible and other docs can link to it. That one should just be adding the method into the manifest.

So I think the branch probably needs the missing backend type pages added or the generated references adjusted and delete-organization-domain.mdx added to manifest.json. Happy to apply those changes if you want me to. Wanted to flag them first!

[alexisintech]

@SarahSoutoul ahh I forgot to test the build in clerk docs. I'll remember to do that 🤦‍♀️ thanks sarah!!
I've added the missing page to the manifest, and fixed all of the links!
also added a page for /docs/reference/backend/backend-organization-domain

[SarahSoutoul]

@alexisintech Okay here are some things I've noticed reviewing all the Organization methods:

1. For createOrganization() and updateOrganizationMembershipMetadata(), the types appear differently from the live docs, but also from other methods who also have privateMetadata/ publicMetadata params.

   Example of types btw local vs live site

   

   Example of how it appears for other methods

   

2. For createOrganizationDomain(), should the word admin be linked like it is within createOrganization() params to be consistent.

   

3. For createOrganizationInvitationBulk(), the type for Role isn't the same as it is displayed in other methods. See the difference below.

   

   I fixed it by doing the following but not sure if that's what you want:

   • Added /** @generateWithEmptyComment */ above CreateBulkOrganizationInvitationParams rather than /** @inline */
   • Used <Typedoc src="backend/create-bulk-organization-invitation-params" /> in the docs to display those params individually under <Typedoc src="backend/organization-api/methods/create-organization-invitation-bulk" />
   • Added a link replacement in javascript to make sure create-bulk-organization-invitation-params links properly.

   Here is the final result:

   

4. For replaceOrganizationMetadata(), MetadataParams leads to 404

   

5. For updateOrganizationMembership(), it looks a bit weird/confusing to have the params called CreateOrganizationMembershipParams here but not sure if it’s fixable since technically: export type UpdateOrganizationMembershipParams = CreateOrganizationMembershipParams;

   

6. Finally, for the The Backend OrganizationDomain object, the type for enrollmentMode is different than how it is for the createOrganizationDomain() method.

   

   VS

   

   I fixed it by adding /** @inline */ on top of OrganizationEnrollmentMode but not sure if that's what you want.

   Last but minor thing is do we want the Properties heading to be removed here? Looks a bit odd UI-wise.

   

[alexisintech]

@alexisintech Okay here are some things I've noticed reviewing all the Organization methods:

1. For createOrganization() and updateOrganizationMembershipMetadata(), the types appear differently from the live docs, but also from other methods who also have privateMetadata/ publicMetadata params.
   Example of types btw local vs live site
   
   Example of how it appears for other methods
   
   

2. For createOrganizationDomain(), should the word admin be linked like it is within createOrganization() params to be consistent.
   

3. For createOrganizationInvitationBulk(), the type for Role isn't the same as it is displayed in other methods. See the difference below.
   
   
   I fixed it by doing the following but not sure if that's what you want:

   • Added /** @generateWithEmptyComment */ above CreateBulkOrganizationInvitationParams rather than /** @inline */
   • Used <Typedoc src="backend/create-bulk-organization-invitation-params" /> in the docs to display those params individually under <Typedoc src="backend/organization-api/methods/create-organization-invitation-bulk" />
   • Added a link replacement in javascript to make sure create-bulk-organization-invitation-params links properly.

   Here is the final result:
   

4. For replaceOrganizationMetadata(), MetadataParams leads to 404
   

5. For updateOrganizationMembership(), it looks a bit weird/confusing to have the params called CreateOrganizationMembershipParams here but not sure if it’s fixable since technically: export type UpdateOrganizationMembershipParams = CreateOrganizationMembershipParams;
   

6. Finally, for the The Backend OrganizationDomain object, the type for enrollmentMode is different than how it is for the createOrganizationDomain() method.
   
   VS
   
   I fixed it by adding /** @inline */ on top of OrganizationEnrollmentMode but not sure if that's what you want.
   Last but minor thing is do we want the Properties heading to be removed here? Looks a bit odd UI-wise.
   

For the MetadataParams issues (your points 1 and 4):

• Point 1: I added a solution for the times where it outputs TPublic and TPrivate, it will now correctly resolve to OrganizationPrivateMetadata and OrganizationPublicMetadata.
• Point 4: I @inlined it so that it no longer shows up as metadata-params.mdx (will flatten in the table and not link to anything).

For point 2, I've added the link for "admin"

For point 3, I've changed the type to export type CreateBulkOrganizationInvitationParams = Array<Omit<CreateOrganizationInvitationParams, 'organizationId'>>; so now it picks up all the correct types, including the role's type. and using omit is better anyways, because now we aren't repeating parameters and their descriptions across multiple types.

For point 5, unfortunately it does resolve to that. we could possibly add a custom tag to keep the type name 🤔 like @keepRedeclaredTypeName or something??

For point 6, I added the @inline tag just like you said - yep that's the proper solution!

For the last point, I added logic for OrganizationDomainVerification to get flattened into the outputted table for OrganizationDomain, so we can remove the dedicated section for it. I've pushed a commit for that here 89ec67b

The javascript updates are in this commit: 49556f8