Teams - Help Genie

All requests use a single endpoint: POST https://api.helpgenie.ai/v1 with resource: "teams".

Access control

Access varies by action. Team owners and internal admins have full access to all actions. Team members have read-only access to get and members. Any authenticated user can create a team.

Action	Any user	Team member	Team owner	Admin
`get`	No	Yes (read-only)	Yes	Yes
`create`	Yes	—	—	Yes
`update`	No	No	Yes	Yes
`delete`	No	No	Yes	Yes
`members`	No	Yes	Yes	Yes
`invite`	No	No	Yes	Yes
`invitations`	No	No	Yes	Yes
`cancel-invite`	No	No	Yes	Yes
`resend-invite`	No	No	Yes	Yes
`remove-member`	No	No	Yes	Yes
`get-branding`	No	Yes	Yes	Yes
`update-branding`	No	No	Yes	Yes
`clear-branding`	No	No	Yes	Yes
`share-genie`	No	No	Yes	Yes
`grant-genie-access`	No	No	Yes	Yes
`remove-genie-access`	No	No	Yes	Yes

Only team owners and internal admins can manage invitations and remove members. Regular team members have read-only access to get and members actions only.

Team management workflow

Create a team

Use the create action to set up a new team. The authenticated user automatically becomes the team owner.

Invite members

Use the invite action to send invitations by email. Track pending invitations with the invitations action.

Members accept

Invited users accept the invitation to join the team. Their profile is updated with the team_id.

Manage the team

Use members to view the roster, remove-member to remove users, and cancel-invite to revoke pending invitations.

Get a team

Retrieves a specific team by ID with all team members.

string

required

Must be "teams"

string

required

Must be "get"

string

required

The team ID.

Response

boolean

object

Show properties

object

Show properties

number

string

object

string

object[]

Show properties

string

Either "Owner" or "Member".

const response = await ApiService.invoke<{
  team: Team;
  members: TeamMember[];
}>({
  resource: "teams",
  action: "get",
  id: "123",
});

Create a team

Creates a new team. The authenticated user automatically becomes the team owner.

string

required

Must be "teams"

string

required

Must be "create"

object

required

Show properties

string

required

Team name.

string

required

Team brand name.

object

Branding configuration (e.g. colors, logos).

Response (status 201)

boolean

object

Show properties

object

The newly created team object.

const response = await ApiService.invoke<{ team: Team }>(
  {
    resource: "teams",
    action: "create",
    data: {
      name: "Marketing Team",
      brand: "ACME Corp",
      branding: { color: "#FF0000" },
    },
  },
  201
);

Update a team

Updates team settings such as name, brand, and branding.

string

required

Must be "teams"

string

required

Must be "update"

string

required

The team ID.

object

required

Show properties

string

Updated team name.

string

Updated brand name.

object

Updated branding configuration.

string

Admin only. Transfers team ownership to this user ID. The new owner must already be a member of the team and cannot be the current owner.

Response

boolean

object

Show properties

object

The updated team object.

const response = await ApiService.invoke<{ team: Team }>({
  resource: "teams",
  action: "update",
  id: "123",
  data: {
    name: "Updated Team Name",
  },
});

Delete a team

Permanently deletes a team and removes all members.

string

required

Must be "teams"

string

required

Must be "delete"

string

required

The team ID.

Response

boolean

object

Show properties

boolean

string

Deletion result description.

string[]

Array of any cleanup errors, if applicable.

This permanently deletes the team and removes all member associations.

const response = await ApiService.invoke<{
  success: boolean;
  message: string;
}>({
  resource: "teams",
  action: "delete",
  id: "123",
});

List team members

Retrieves all members of a team.

string

required

Must be "teams"

string

required

Must be "members"

string

required

The team ID.

Response

boolean

object

Show properties

object[]

Show properties

string

Either "Owner" or "Member".

number

Total number of members.

const response = await ApiService.invoke<{
  members: TeamMember[];
  count: number;
}>({
  resource: "teams",
  action: "members",
  id: "123",
});

Invite a member

Sends a team invitation to an email address. If a previous invitation exists for the same email, it is replaced. The invitee receives an email and must accept before joining.

string

required

Must be "teams"

string

required

Must be "invite"

string

required

The team ID.

object

required

Show properties

string

required

Email address of the person to invite.

string

Admin only. Sends the invitation on behalf of this user ID.

Response (status 201)

boolean

object

Show properties

object

Show properties

string

Invitation UUID.

string

Email address the invitation was sent to.

string

Always "pending" for a newly created invitation.

string

ISO 8601 timestamp of when the invitation was sent.

string | null

ISO 8601 timestamp of acceptance, or null if not yet accepted.

string | null

ISO 8601 expiry timestamp, or null if no expiry is set.

const response = await ApiService.invoke<{ invitation: TeamInvitation }>({
  resource: "teams",
  action: "invite",
  id: "123",
  data: {
    email: "user@example.com",
  },
});

curl -X POST https://api.helpgenie.ai/v1/teams \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "teams",
    "action": "invite",
    "id": "123",
    "data": {
      "email": "newmember@example.com"
    }
  }'

List pending invitations

Retrieves all pending invitations for a team.

string

required

Must be "teams"

string

required

Must be "invitations"

string

required

The team ID.

Response

boolean

object

Show properties

object[]

Show properties

string

Invitation UUID.

string

Invited email address.

string

Current invitation status (e.g. "pending").

string

ISO 8601 timestamp of when the invitation was sent.

string | null

ISO 8601 timestamp of acceptance, or null if not yet accepted.

string | null

ISO 8601 expiry timestamp, or null if no expiry is set.

number

Number of pending invitations.

const response = await ApiService.invoke<{
  invitations: TeamInvitation[];
  count: number;
}>({
  resource: "teams",
  action: "invitations",
  id: "123",
});

Cancel an invitation

Cancels a pending team invitation.

string

required

Must be "teams"

string

required

Must be "cancel-invite"

string

required

The invitation UUID.

object

required

Show properties

number

required

The team ID the invitation belongs to.

Response

boolean

object

Show properties

boolean

const response = await ApiService.invoke<{ success: boolean }>({
  resource: "teams",
  action: "cancel-invite",
  id: "invitation-uuid",
  data: {
    teamId: 123,
  },
});

Resend an invitation

Refreshes the timestamp on a pending invitation, triggering a new invitation email to the invitee.

string

required

Must be "teams"

string

required

Must be "resend-invite"

string

required

The invitation UUID to resend.

object

required

Show properties

number

required

The team ID the invitation belongs to.

string

Admin only. Perform this action on behalf of this user ID.

Only invitations with status: "pending" can be resent. Returns 404 if the invitation is not found or is no longer pending.

Response

boolean

object

Show properties

object

Show properties

string

Invitation UUID.

string

Email address the invitation was sent to.

string

Always "pending" for a resent invitation.

string

ISO 8601 timestamp updated to the time the invitation was resent.

string | null

ISO 8601 timestamp of acceptance, or null if not yet accepted.

string | null

ISO 8601 expiry timestamp, or null if no expiry is set.

const response = await ApiService.invoke<{ invitation: TeamInvitation }>({
  resource: "teams",
  action: "resend-invite",
  id: "invitation-uuid",
  data: {
    teamId: 123,
  },
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Content-Type: application/json" \
  -H "x-api-key: hg_live_YOUR_KEY" \
  -d '{
    "resource": "teams",
    "action": "resend-invite",
    "id": "invitation-uuid",
    "data": {
      "teamId": 123
    }
  }'

Remove a member

Removes a member from a team.

string

required

Must be "teams"

string

required

Must be "remove-member"

string

required

The team ID.

object

required

Show properties

string

required

The user UUID of the member to remove.

Response

boolean

object

Show properties

boolean

const response = await ApiService.invoke<{ success: boolean }>({
  resource: "teams",
  action: "remove-member",
  id: "123",
  data: {
    memberId: "user-uuid",
  },
});

Branding actions

`get-branding`

Returns the team’s branding configuration. Parameters — none (uses the authenticated user’s team).

`update-branding`

Updates the team’s branding (colors, logo, gradient settings). Team owner or admin only. Parameters

Field	Type	Description
`primaryColor`	string	Primary brand color (hex)
`secondaryColor`	string	Secondary brand color (hex)
`logoUrl`	string	URL of the brand logo
`gradientEnabled`	boolean	Whether gradient is enabled

`clear-branding`

Resets all branding fields to null. Team owner or admin only. Parameters — none.

Shares a Genie with team members. Parameters

Field	Type	Required	Description
`agentId`	string	Yes	Genie UUID to share

`grant-genie-access`

Grants a team member access to a specific Genie. Parameters

Field	Type	Required	Description
`agentId`	string	Yes	Genie UUID
`userId`	string	Yes	Team member UUID to grant access

`remove-genie-access`

Revokes a team member’s access to a specific Genie. Parameters

Field	Type	Required	Description
`agentId`	string	Yes	Genie UUID
`userId`	string	Yes	Team member UUID to revoke

Error responses

Status	Code	Description
400	`VALIDATION_ERROR`	Missing or invalid required parameters
401	`UNAUTHORIZED`	No valid authentication token
403	`FORBIDDEN`	User lacks permission for the operation
404	`NOT_FOUND`	Team or resource not found
500	`INTERNAL_ERROR`	Server error during processing

​Access control

​Team management workflow

​Get a team

​Response

​Create a team

​Response (status 201)

​Update a team

​Response

​Delete a team

​Response

​List team members

​Response

​Invite a member

​Response (status 201)

​List pending invitations

​Response

​Cancel an invitation

​Response

​Resend an invitation

​Response

​Remove a member

​Response

​Branding actions

​get-branding

​update-branding

​clear-branding

​Genie sharing actions

​share-genie

​grant-genie-access

​remove-genie-access

​Error responses

Access control

Team management workflow

Get a team

Response

Create a team

Response (status 201)

Update a team

Response

Delete a team

Response

List team members

Response

Invite a member

Response (status 201)

List pending invitations

Response

Cancel an invitation

Response

Resend an invitation

Response

Remove a member

Response

Branding actions

`get-branding`

`update-branding`

`clear-branding`

Genie sharing actions

`share-genie`

`grant-genie-access`

`remove-genie-access`

Error responses