Add team membership write endpoint to Preview spec - #619
Add team membership write endpoint to Preview spec#619ryadhtaher-coder wants to merge 5 commits into
Conversation
Adds PUT /teams/{id} and its request payload to the Preview spec. The
endpoint takes the complete desired member set rather than a delta, so
the description spells out that omitted teammates are removed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Spell out that membership is the only writable field, that priority levels on balanced teams are read-only, and that a token acting for a teammate is held to that teammate's permissions. Adds the matching error examples. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Adds the 409 a caller sees when another request is already changing the same team's members, and states which fields the endpoint accepts. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The endpoint accepts a team read back from the API whole, so the description should not claim only three fields are allowed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
anubhav-intercom
left a comment
anubhav-intercom
left a comment
There was a problem hiding this comment.
Reviewed at 94867bcf, cross-checked against the implementation in intercom/intercom#556314. The 409 you documented in 9cd751b7 covers the lock path correctly — three things left, the first blocking.
| management system, since sending an unchanged list makes no changes at all. | ||
|
|
||
|
|
||
| A token that acts on behalf of a teammate carries that teammate's permissions: |
There was a problem hiding this comment.
This spec no longer parses. YAML.load_file on this branch fails with mapping values are not allowed in this context at line 21307 column 86, while origin/main parses cleanly.
The cause is the trailing : at the end of this line: inside a plain (unquoted) multi-line scalar, a colon at end-of-line terminates the scalar and YAML reads it as a mapping key.
Making the description a block scalar (description: >-) or rewording so the line doesn't end in a colon both fix it.
| also set name | ||
| schema: | ||
| "$ref": "#/components/schemas/error" | ||
| '403': |
There was a problem hiding this comment.
Both examples under this 403 use code: forbidden, but the implementation returns a 403 with a different code as well: api_plan_restricted, from raise_feature_unavailable in app/commands/api/v3/team_memberships/update.rb when the feature flag is off.
Since the flag starts off everywhere, that's the first 403 most callers will actually see — and the one they need to branch on to tell "not enabled for this workspace" from "not permitted". Worth documenting alongside the two forbidden cases.
| type: string | ||
| tags: | ||
| - Teams | ||
| operationId: updateTeam |
There was a problem hiding this comment.
updateTeam is the natural generated name for a general team update (client.teams.update), but this operation writes membership only — name, distribution_method and the priority fields are all rejected with a 400.
Once SDKs generate from this the name is claimed, and the team CRUD endpoint that Part 2 of #556134 scopes can't have it without a breaking rename. Something like updateTeamMembers leaves that room.
The description held a colon inside an unquoted multi-line scalar, which made the whole document unparseable. Both it and the expanded 409 use block scalars. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2 participants
Why?
The REST API can list and read teams but has no way to change who belongs to one, so a workspace that manages its rota in an external scheduling or workforce system cannot keep team membership in sync automatically.
How?
Documents a new Preview endpoint that replaces a team's member list, taking the complete desired set rather than a delta so re-sending an unchanged list changes nothing.
API versions affected: Preview only.
Generated with Claude Code