New API version release by brunol95 · Pull Request #3380 · clerk/clerk-docs

brunol95 · 2026-05-18T20:37:59Z

🔎 Previews:

What does this solve? What changed?

In the next API version, metadata updates through the user update method are disallowed. This PR documents the API version page along with sdk changes to support the new version.

Todos

Update/Finalize API version date
Merge chore(backend, clerk-js): Deprecate metadata updates in user update methods javascript#8587
Merge chore(backend): Deprecate metadata updates in organization update method javascript#8787
Merge deprecate the metadata fields in user update clerk-android#650
Merge deprecate metadata field in user update clerk-ios#415
Update SDK version TBDs (see reminder comment)

Deadline

05/26

vercel · 2026-05-18T20:38:04Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Jun 10, 2026 3:19pm

…om/clerk/clerk-docs into bruno/user-5311-latest-api-version

…m type name - Correct del/ins line ranges in the 2026-05-12 and Core 3 metadata examples so closing braces highlight correctly - Use > [!NOTE] callouts on the native mobile user pages - Align updateUserMetadata() param type with @clerk/backend (UserMetadataParams) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

manovotny · 2026-05-22T17:28:12Z

Pushed some review fixes directly in 3414da8.

Fixed the del/ins line ranges in the metadata examples so the diff highlighting is correct: the backend example in the 2026-05-12 guide now highlights replaceUserMetadata()'s closing line, and the frontend user.update() examples (in both the 2026-05-12 guide and the Core 3 accordion) now account for the 6-line block instead of treating it as 5.
Switched the native iOS/Android > Note: blockquotes to > [!NOTE] callouts to match the other native-mobile pages.
Renamed the updateUserMetadata() params type from UpdateUserMetadataParams to UserMetadataParams so it matches @clerk/backend and the new replaceUserMetadata() page.

Have a look, and let me know if anything looks off. I also updated the todo list in the PR description with a few more items.

manovotny · 2026-05-22T16:22:39Z

+| Python | TBD |
+| Remix | TBD |
+| Ruby | TBD |
+| Vue | TBD |


Leaving a comment to flag that TBDs need to be fixed before merge. From @brunol95:

On the day of the release - my plan is to update the docs with all the latest version once the sdk PRs are merged/released

SarahSoutoul · 2026-05-26T18:09:25Z

@brunol95 left a docs review with some small fixes:

Made consistent the phrase future major API version across the changes as some were using future major version
Made consistent all of the deprecated properties changes to be consistent with rest of docs.
Improved the wording of some of the text.

I noticed there was still a mention of client.users.updateUser() but from my understanding, it's fine to keep it as is cause we're not updating any publicMetadata or the other metadata properties. Is that correct?

- updateUser() metadata param deprecation points to both updateUserMetadata() (partial/merge) and replaceUserMetadata() (full replacement) so migrators relying on replace semantics aren't silently switched to merge - Drop "API" from "future major API version" — these are SDK deprecations, not bound to a future API version date - Move the deprecation > [!NOTE] callout to the top of the "Update user metadata" section on the native iOS/Android pages Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

manovotny · 2026-05-26T22:08:57Z

Pushed re-review fixes directly in 0886311.

Expanded the deprecation guidance on updateUser()'s publicMetadata/privateMetadata/unsafeMetadata params to point to both updateUserMetadata() (partial/deep-merge) and replaceUserMetadata() (full replacement). The previous wording only mentioned the merge path, which would silently change behavior for anyone relying on updateUser()'s replace semantics.
Dropped "API" from "future major API version" in update-user.mdx, core-3.mdx, and objects/user.mdx. These are SDK-level deprecations — they'll be removed in a future major SDK release (per clerk/javascript#8587) — and "API version" risked conflating that with the dated API versions documented elsewhere in this PR.
Moved the > [!NOTE] deprecation callout to the top of the "Update user metadata" section on both user.ios.mdx and user.mdx, per Sarah's thread.

brunol95 · 2026-05-27T01:22:11Z

I noticed there was still a mention of client.users.updateUser() but from my understanding, it's fine to keep it as is cause we're not updating any publicMetadata or the other metadata properties. Is that correct?

yep! client.users.updateUser() is still a valid method just can't be used for updating metadata.

…eOrganizationMetadata()

…om/clerk/clerk-docs into bruno/user-5311-latest-api-version

…/user-5311-latest-api-version

- Fix ins line ranges in the 2026-05-12 organization example so the replaceOrganizationMetadata() closing line highlights - Correct the guide intro: PATCH metadata endpoints deep-merge, PUT endpoints replace in full - Align updateOrganization() deprecation wording with updateUser() (bold format, partial vs full replacement paths, no "API" in "future major version") - Unify org metadata params type as OrganizationMetadataParams across both org metadata reference pages - Add the replace TIP to updateOrganizationMetadata(), mirroring updateUserMetadata() Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

manovotny · 2026-06-10T15:24:17Z

Pushed re-review fixes for the Organizations expansion directly in 2007d70.

Fixed the ins line ranges on the organization example in the 2026-05-12 guide so replaceOrganizationMetadata()'s closing line highlights (same off-by-one as the user example fixed earlier).
Corrected the guide intro — it claimed the dedicated metadata endpoints "provide deep-merge semantics," but the guide documents both PATCH (deep-merge) and PUT (full replace) endpoints. It now says which does which.
Aligned updateOrganization()'s metadata deprecation wording with the updateUser() equivalents: bold format, both migration paths (updateOrganizationMetadata() for partial updates, replaceOrganizationMetadata() for full replacement), and "future major version" without "API."
Unified the org metadata params type name as OrganizationMetadataParams on both org metadata reference pages — the new replace page and the existing update page had invented two different names for the same shape (clerk/javascript#8787 uses one type for both methods, matching how the user pages share UserMetadataParams).
Added the full-replace TIP to updateOrganizationMetadata(), mirroring the one on updateUserMetadata().

Verified the org endpoint changes against clerk/clerk_go#18806 (metadata rejection on org PATCH at 2026-05-12) and the SDK claims against clerk/javascript#8787, clerk-ios#415, and clerk-android#650. Build and lint pass.

manovotny · 2026-06-10T15:24:18Z

+  - Update an organization's data or metadata
+  - `PATCH /v1/organizations/{organization_id}`, `PATCH /v1/organizations/{organization_id}/metadata`, and `PUT /v1/organizations/{organization_id}/metadata`
+
+  10 requests per 10 seconds per organization
+
+  ---
+
+  - Update an organization membership's data or metadata
+  - `PATCH /v1/organizations/{organization_id}/memberships/{user_id}` and `PATCH /v1/organizations/{organization_id}/memberships/{user_id}/metadata`
+
+  10 requests per 10 seconds per organization membership


All five endpoints check out in clerk_go, but I couldn't find where the 10-requests-per-10-seconds buckets for Organizations and memberships are defined.

Where do these values come from?

These values are defined within our terraform infrastructure

Dug through terraform-app-infra to confirm. The user limit is there — "Block user update with same user_id (10reqs/10s)" in the clerk.dev zone — but it only matches PATCH today; the PUT coverage sits on bruno/user-5280-user-metadata-put-rate-limit, which is unmerged with no open PR. For the Organization and membership rows I can't find anything: no merged rule, no branch, and no open PR matching those paths. Is that infra change still to come?

Yes, I will get the infra changes in when we release. I'll link the PRs here

draft for new api versionn changes

70920c3

brunol95 requested a review from a team as a code owner May 18, 2026 20:38

brunol95 added the do not merge label May 18, 2026

brunol95 marked this pull request as draft May 18, 2026 20:38

update rate limit for user data

1563598

vercel Bot deployed to Preview May 19, 2026 18:43 View deployment

Merge branch 'main' into bruno/user-5311-latest-api-version

6e8e606

vercel Bot deployed to Preview May 19, 2026 22:56 View deployment

brunol95 added 2 commits May 20, 2026 12:44

update mobile refs with updateMetadata method

5b8d164

Merge branch 'bruno/user-5311-latest-api-version' of https://github.c…

87220cc

…om/clerk/clerk-docs into bruno/user-5311-latest-api-version

vercel Bot deployed to Preview May 20, 2026 16:47 View deployment

brunol95 marked this pull request as ready for review May 20, 2026 17:46

Merge branch 'main' into bruno/user-5311-latest-api-version

3081b84

vercel Bot deployed to Preview May 22, 2026 15:52 View deployment

manovotny self-assigned this May 22, 2026

manovotny reviewed May 22, 2026

View reviewed changes

vercel Bot deployed to Preview May 22, 2026 17:30 View deployment

SarahSoutoul self-assigned this May 22, 2026

docs review

0a04e76

vercel Bot deployed to Preview May 26, 2026 17:53 View deployment

Merge branch 'main' into bruno/user-5311-latest-api-version

a5c2eaa

vercel Bot deployed to Preview May 26, 2026 18:05 View deployment

SarahSoutoul reviewed May 26, 2026

View reviewed changes

Comment thread docs/reference/native-mobile/user.mdx Outdated

vercel Bot deployed to Preview May 26, 2026 22:11 View deployment

brunol95 added 2 commits June 8, 2026 16:48

Deprecate metadata params on updateOrganization() and document replac…

4c1b8fa

…eOrganizationMetadata()

Merge branch 'bruno/user-5311-latest-api-version' of https://github.c…

5f3359f

…om/clerk/clerk-docs into bruno/user-5311-latest-api-version

vercel Bot deployed to Preview June 8, 2026 21:56 View deployment

update rate limits for orgs and org membership

e0122c7

vercel Bot deployed to Preview June 9, 2026 14:51 View deployment

Merge branch 'main' of https://github.com/clerk/clerk-docs into bruno…

84f9a35

…/user-5311-latest-api-version

vercel Bot deployed to Preview June 9, 2026 21:47 View deployment

brunol95 requested review from SarahSoutoul and manovotny June 9, 2026 21:51

vercel Bot deployed to Preview June 10, 2026 15:19 View deployment

manovotny reviewed Jun 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New API version release#3380

New API version release#3380
brunol95 wants to merge 15 commits into
mainfrom
bruno/user-5311-latest-api-version

brunol95 commented May 18, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 18, 2026 •

edited

Loading

Uh oh!

manovotny commented May 22, 2026

Uh oh!

manovotny May 22, 2026

Uh oh!

SarahSoutoul commented May 26, 2026

Uh oh!

Uh oh!

manovotny commented May 26, 2026

Uh oh!

brunol95 commented May 27, 2026

Uh oh!

manovotny commented Jun 10, 2026

Uh oh!

manovotny Jun 10, 2026

Uh oh!

brunol95 Jun 10, 2026

Uh oh!

manovotny Jun 10, 2026

Uh oh!

brunol95 Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

brunol95 commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔎 Previews:

What does this solve? What changed?

Todos

Deadline

Uh oh!

vercel Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

manovotny commented May 22, 2026

Uh oh!

manovotny May 22, 2026

Choose a reason for hiding this comment

Uh oh!

SarahSoutoul commented May 26, 2026

Uh oh!

Uh oh!

manovotny commented May 26, 2026

Uh oh!

brunol95 commented May 27, 2026

Uh oh!

manovotny commented Jun 10, 2026

Uh oh!

manovotny Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

brunol95 Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

manovotny Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

brunol95 Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

brunol95 commented May 18, 2026 •

edited

Loading

vercel Bot commented May 18, 2026 •

edited

Loading