Skip to main content

Review Teams

Create and manage review teams that Human Reviews route to: workspace-unique names, an optional notification webhook URL, and owner-managed team membership.

Review teams are the routing registry for Human Reviews: named groups of workspace users a review can be assigned to, either at raise time (team_id on POST /v1/apps/:id/reviews) or later via POST /v1/reviews/:reviewId/assign. The inbox filters make the rest work: a team's members triage GET /v1/reviews?status=open and pick up what is routed their way. Teams are plane-neutral by design — Apps consume them today, other review-routing surfaces adopt the same registry later.

The CRUD is deliberately small. GET /v1/review-teams lists teams (read tier, name-ordered). POST /v1/review-teams creates one from a name (max 200 chars, workspace-unique — a duplicate answers 409 naming the clash) and an optional webhook_url (max 2000 chars) for team notification integrations. PATCH /v1/review-teams/:teamId renames or swaps the webhook URL (pass webhook_url: null to clear it); DELETE /v1/review-teams/:teamId removes the team. All three writes are owner tier — a human workspace owner — while reads sit at the read tier like the rest of the surface.

Membership is managed per team: GET /v1/review-teams/:teamId/members lists members, POST /v1/review-teams/:teamId/members adds one by user_id (a duplicate add answers 409 User is already a member of this team), and DELETE /v1/review-teams/:teamId/members/:userId removes one, answering { "removed": true }. Members are workspace users — the same identities that appear as assignee_user_id on reviews and as resolvers in the ledger.

curl — create a team and add a member

curl -s -X POST https://api.talonic.com/v1/review-teams \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Finance Ops", "webhook_url": "https://hooks.example.com/finance-ops" }'
# → { "id": "3f2b9c44-…", "name": "Finance Ops",
#     "webhook_url": "https://hooks.example.com/finance-ops", "created_at": "…" }

curl -s -X POST https://api.talonic.com/v1/review-teams/$TEAM_ID/members \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "9a7e1c22-4f0b-4e0e-8a4b-6d2f0c9b1e77" }'

curl — route a review to the team

curl -s -X POST https://api.talonic.com/v1/reviews/$REVIEW_ID/assign \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "team_id": "3f2b9c44-1e0a-4b7c-9d21-5a8f0e6c3b12" }'
Team writes require a human workspace owner because teams are authority routing: whoever controls team membership controls who resolves approvals. Assigning an individual review, by contrast, is an operate-tier action any operator or granted agent can perform.

A team's webhook_url is a notification hook: whenever a review is raised with that team as assignee (team_id on POST /v1/apps/:id/reviews), Talonic POSTs the same JSON envelope the workspace-level app.review.raised webhook carries (review_id, app_id, run_id, kind, question, team) to that URL, unsigned and with the standard retry ladder. Platform-raised reviews (threshold holds, decision-agent failures, SLA fallbacks) arrive as app.exception.raised instead. Use the team hook for the team's own channel and the workspace webhook for your integration. Resolution flows back through the normal resolve endpoint, so a team bot can read the inbox filtered to its assignments and resolve data_request reviews autonomously while leaving approval kinds to humans.

Frequently asked questions

Can an API key create or modify review teams?+
No. Team creation, update, deletion, and membership changes are owner-tier operations requiring a human workspace owner session; machine callers are rejected with 403. Keys can list teams and members at the read tier, and assign individual reviews at the operate tier.
What happens to open reviews when their team is deleted?+
The reviews survive; deletion removes the routing target, not the work. Reassign affected reviews to another team or directly to a user via POST /v1/reviews/:reviewId/assign — the workspace inbox keeps listing them regardless of assignment.
Can a review be assigned to both a team and a user?+
The assign body accepts team_id and/or user_id — routing to a team's queue, a specific person, or both (a team with a named owner for the item). Each review carries assignee_team_id and assignee_user_id separately, and the inbox filters on assignee_user_id.
Is team membership required to resolve a review?+
No. Assignment is routing, not authorization: any actor passing the resolver policy for the review's kind may resolve it, assigned or not. Use assignment to organize work and the inbox filters to scope views, not as an access control.

Related

Human Reviews
Apps Overview
Grants & Client Access
Webhook Events