Sharing with a team

Instead of listing names on every document, make a team once and share with the team. Someone joins, they get what the team has. Someone leaves, they lose it everywhere — in one action, not a search through documents.

§01The idea in one picture

§02Before you start: a member is an account

A team member is a PitchStation account, not an email address on a list. There is no way to check that a stranger controls an address, so an address alone cannot let someone in.

Two ways in:

• They already have an account — add them by email (confirmed addresses only) or username. Done; they get one email listing what the team grants.
• They don't have one yet — invite them. From the Teams page (or POST /api/teams/:id/invites), send an invitation to their email with a personal note in your own words. They get a signup link; the moment they sign up and confirm that address, they join automatically — you get an email when it happens, they get the document list. Until then the invitation grants nothing: it appears in no access check, and you can revoke it any time from the pending list.

§03Do it in four steps

curl -X POST https://pitchstation.ai/api/teams \
  -H "Authorization: Bearer $PITCHSTATION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"handle":"design","name":"Design team"}'

{ "success": true,
  "team": { "id": 2,
             "ref": "@leo_lin/design",   ← how anyone names it unambiguously
             "members": 1,              ← you, automatically
             "yourRole": "owner" } }

# by email — the usual case
-d '{"email":"simon@example.com"}'

# or by username, if you know it
-d '{"username":"simonruan"}'

curl -X POST https://pitchstation.ai/api/teams/2/members \
  -H "Authorization: Bearer $PITCHSTATION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"username":"simonruan"}'

{ "success": true,
  "granted": 0,
  "note": "This team has no documents yet." }

{ "code": "USER_NOT_FOUND",
  "error": "No account for \"nobody@example.com\". A team member must
            already have an account: ask them to sign up at
            /signup.html, then add them." }

curl -X POST https://pitchstation.ai/api/share \
  -H "Authorization: Bearer $PITCHSTATION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Q3 plan", "access":"account",
       "htmlContent":"…",
       "teams":["design"]}'

{ "slug": "QeexQIP5",
  "teams": { "teams": [ { "ref": "@leo_lin/design", "members": 2 } ] } }

{ "success": true,
  "granted": 1,
  "note": "That also gives them access to 1 document already
            shared with this team." }

§04Opening a document you already shared privately

You do not have to republish. Widen it in place and the link, password, analytics and comments all carry forward:

curl -X PATCH https://pitchstation.ai/api/share/<slug>/access \
  -H "Authorization: Bearer $PITCHSTATION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"addTeams":["design"]}'

{ "promoted": { "from": "link", "to": "account",
                "note": "a team member must sign in to be recognised as one" },
  "grantedTo": 2,
  "note": "This document is now open to 2 more people." }

Going the other way needs no ceremony — {"removeTeams":["design"]} takes it back immediately.

§05When two teams have the same name

You can be in your own design team and a client's design team at the same time. When you type just design, PitchStation refuses and asks which — it does not pick one:

{ "code": "TEAM_AMBIGUOUS",
  "error": "\"design\" matches 2 teams. Name one exactly — nothing was shared.",
  "candidates": [
    { "ref": "@leo_lin/design", "members": 1, "yourRole": "admin"  },
    { "ref": "@bob/design",     "members": 2, "yourRole": "member" } ] }

Retry with the one you meant — "teams":["@bob/design"] or "teamIds":[3] — and it goes through.

§06What happens when someone leaves

This is the reason to use teams at all. Offboarding somebody becomes one call instead of remembering every document they were named on.

§07Asking an assistant instead

If you have PitchStation connected to Claude Code, Codex or another assistant, say what you want:

"Make a team called design, add simon@example.com, and share
 the Q3 plan with it."

§08Who gets told, and when

Sharing something with a team emails the team. Changing who can reach a document you already shared does not, unless you ask.

# the miss most people hit: widened without notify, and now want to tell them
curl -X POST https://pitchstation.ai/api/share/<slug>/notify \
  -H "Authorization: Bearer $PITCHSTATION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"to":"members"}'          # or ["members","owner"]

# announce a document the team can already reach — same URL, same analytics
curl -X PATCH https://pitchstation.ai/api/share/<slug>/access \
  -H "Authorization: Bearer $PITCHSTATION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"addTeams":["aip"],"notify":true}'

{ "grantedTo": 2,
  "notified": ["yanglee@mobileinteractive.com"] }

Two things it will not do: it never emails you unless you ask for owner, and it never re-sends a password — the password is stored hashed and cannot be recovered, so pass it on yourself. The response says so when the share has one.

Widening without notify now tells you it stayed quiet, rather than looking like a notification that failed:

{ "notified": [],
  "notifyNote": "Nobody was emailed. Pass \"notify\": true to tell the 1 member,
                  or POST /api/share/<slug>/notify later." }

§09Things worth knowing

• Team names are not globally unique. Two people can both have a design team; that is why §05 exists.
• Any member can share to the team; only admins manage membership and settings. Sharing is the everyday act, membership is the privileged one. The owner is a permanent admin; other admins are promoted (and demoted) explicitly — re-adding someone never changes their role.
• Anyone but the owner can leave. Leaving ends their own access everywhere the team granted it; an admin would have to add them back.
• Teams and named individuals add up. You can share with a team and two people outside it.
• A team member skips the share password. They are already signed in and already authorised — otherwise you would be sending a password to the whole team.
• Sealed shares cannot use teams. The key never reaches our servers, so we cannot admit a membership we do not control. You will get a clear refusal.
• The team owner cannot be removed. Archive the team instead.

§10Not built yet

• Snapshot membership — a share frozen to the roster as it stood. Today membership is always live (D6); ask if you need the frozen kind.
• Ownership transfer. The owner is permanent; archive covers wind-downs.