Teams - InstaPods

Every pod belongs to a team, and every request acts on your active team. See Teams for what a team is and how billing is scoped to it. Most write operations here are owner-only. There are two roles, owner and member.

List Your Teams

GET /api/teams

Response: 200 OK

[
  {
    "id": "team_abc123",
    "name": "Acme",
    "slug": "acme",
    "owner_id": "usr_xyz",
    "account_type": "standard",
    "trust_tier": "verified",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
]

Every team you belong to, whether you own it or were invited to it.

Create a Team

POST /api/teams

{ "name": "Acme" }

Response: 201 Created - returns the team. The slug is derived from the name; you don’t set it. You become the owner.

Get a Team

GET /api/teams/{id}

Returns 404 if the team doesn’t exist or you’re not a member of it - the two are deliberately indistinguishable.

Update a Team

PUT /api/teams/{id}

{ "name": "Acme Inc" }

Renaming re-derives the slug. Owner-only (403 otherwise).

Delete a Team

DELETE /api/teams/{id}

Response: 200 OK

{ "status": "deleted" }

Owner-only.

A team that still owns pods cannot be deleted. You get a 409 naming the count: delete or transfer its pods first. This is a guard, not an inconvenience - pods orphaned from their team keep running and keep accruing charges with nothing able to bill or reach them.

Switch Active Team

POST /api/teams/switch

{ "team_id": "team_abc123" }

Sets which team subsequent requests act on. Returns the updated user object. Returns 403 if you aren’t a member of that team.

An API token is bound to the team that was active when you created it, and switching does not move it. A token always acts on its own team, which is what makes it safe to leave in CI.

Members

List Members

GET /api/teams/{id}/members

[
  {
    "id": "tm_abc",
    "team_id": "team_abc123",
    "user_id": "usr_xyz",
    "role": "owner",
    "joined_at": "2026-01-15T10:00:00Z"
  }
]

List Members With Names

GET /api/teams/{id}/members/details

The same list with each member’s name and email resolved, which is what the team settings screen renders. Use this when you want to show who someone is rather than just their user ID.

[
  {
    "id": "tm_abc",
    "team_id": "team_abc123",
    "user_id": "usr_xyz",
    "role": "owner",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "joined_at": "2026-01-15T10:00:00Z"
  }
]

Add a Member

POST /api/teams/{id}/members

{
  "email": "ada@example.com",
  "role": "member"
}

Adds someone who already has an InstaPods account directly, with no invitation step. Use invitations for anyone else. Response: 201 Created - returns the membership. Owner-only.

Code	Reason
`400`	`email` missing
`404`	No InstaPods account with that email - send an invitation instead
`409`	Already a member of this team

Remove a Member

DELETE /api/teams/{id}/members/{uid}

Response: 200 OK

{ "status": "removed" }

The owner can remove anyone; anyone can remove themselves (that’s how you leave a team). The team owner cannot be removed - transfer ownership or delete the team instead.

Invitations

For inviting someone who doesn’t have an account yet. An invitation is a signed link, valid for 7 days.

Send an Invitation

POST /api/teams/{id}/invitations

{
  "email": "grace@example.com",
  "role": "member"
}

Response: 201 Created

{
  "id": "inv_abc123",
  "team_id": "team_abc123",
  "email": "grace@example.com",
  "role": "member",
  "token": "8f3c...",
  "invited_by": "usr_xyz",
  "expires_at": "2026-02-27T10:00:00Z",
  "created_at": "2026-02-20T10:00:00Z"
}

Owner-only. Returns 409 if that email already belongs to a member of this team.

List Pending Invitations

GET /api/teams/{id}/invitations

Owner-only.

Revoke an Invitation

DELETE /api/teams/{id}/invitations/{invId}

Owner-only. Returns {"status": "deleted"}.

Look Up an Invitation

GET /api/invitations/{token}

Public - this is what the invitation landing page calls before the recipient has an account. It returns only what’s needed to render “you’ve been invited”, never the team’s contents:

{
  "team_name": "Acme",
  "inviter_name": "Ada Lovelace",
  "email": "grace@example.com",
  "role": "member",
  "expires_at": "2026-02-27T10:00:00Z"
}

Returns 404 for a token that is unknown or expired.

Accept an Invitation

POST /api/invitations/accept

Works two ways, depending on whether the caller is signed in. Already signed in - send just the token:

{ "token": "8f3c..." }

No account yet - sign up and join in one call:

{
  "token": "8f3c...",
  "email": "grace@example.com",
  "name": "Grace Hopper",
  "password": "a-strong-password"
}

This registers the account, logs it in (setting the session cookie) and joins the team. Omitting any of email, name or password while signed out returns 401. Response: 200 OK

{
  "status": "joined",
  "team_id": "team_abc123"
}

status is already_member if you were already on the team; either way the invitation is consumed and the team becomes your active one.

​List Your Teams

​Create a Team

​Get a Team

​Update a Team

​Delete a Team

​Switch Active Team

​Members

​List Members

​List Members With Names

​Add a Member

​Remove a Member

​Invitations

​Send an Invitation

​List Pending Invitations

​Revoke an Invitation

​Look Up an Invitation

​Accept an Invitation

List Your Teams

Create a Team

Get a Team

Update a Team

Delete a Team

Switch Active Team

Members

List Members

List Members With Names

Add a Member

Remove a Member

Invitations

Send an Invitation

List Pending Invitations

Revoke an Invitation

Look Up an Invitation

Accept an Invitation