API reference

Team

The owner of an X account can share it with other Gemlead users. Each member works on it with the owner's plan and credits, and their role decides what they may change, zone by zone. Billing and the X account's connection stay the owner's.

The owner and the admins invite and change members. Only the owner makes someone an admin or changes an admin. An X account has 50 members at most, invites included.

A member whose role edits the settings can make their own API key or connect an AI app. That key works with the member's role, never more, and stops once they leave the team.

Endpoints

GET/v1/team
POST/v1/team/members
PATCH/v1/team/members/:member_id
DELETE/v1/team/members/:member_id
POST/v1/team/leave

The team object

Who works on the X account in Gemlead, its owner first, and what the key's own user may do there.

Attributes

objectstring
Always team.
account_idstring
The X account's ID, as in the account object.
your_rolestring
The role of the key's user. owner for the owner's keys.
ownerviewersettereditoradmincustom
your_member_idstring or null
The key's user as a member, null for the owner.
ownerobject
The Gemlead user who connected the X account and pays for it.
membersarray of objects
The members and the invites, as team member objects.
max_membersinteger
How many members an X account has at most, invites included.

Team object

{
  "object": "team",
  "account_id": "a9PzK2vRtM",
  "your_role": "owner",
  "your_member_id": null,
  "owner": {
    "name": "Alex Moreau",
    "email": "alex@acme.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg"
  },
  "members": [
    {
      "id": "Tm4kQ9wZrB",
      "object": "team_member",
      "email": "sara@acme.com",
      "name": "Sara Kim",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1733920571/sara_400x400.jpg",
      "role": "setter",
      "zones": {
        "personas": "view",
        "campaigns": "view",
        "chat": "edit",
        "leads": "edit",
        "settings": "view"
      },
      "status": "active",
      "created_at": "2026-09-14T09:21:05.300Z"
    },
    {
      "id": "Tm8vX2pLnC",
      "object": "team_member",
      "email": "dev@acme.com",
      "name": null,
      "profile_image_url": null,
      "role": "custom",
      "zones": {
        "personas": "edit",
        "campaigns": "view",
        "chat": "view",
        "leads": "edit",
        "settings": "view"
      },
      "status": "invited",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "max_members": 50
}

Retrieve the team

GET/v1/teamread scopeMCPget_team

Returns the X account's owner, then each member and invite with their role and zones, and the role of the key's own user.

Returns

The team object.

GET/v1/team

curl https://gemlead.ai/api/v1/team \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "object": "team",
  "account_id": "a9PzK2vRtM",
  "your_role": "owner",
  "your_member_id": null,
  "owner": {
    "name": "Alex Moreau",
    "email": "alex@acme.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg"
  },
  "members": [
    {
      "id": "Tm4kQ9wZrB",
      "object": "team_member",
      "email": "sara@acme.com",
      "name": "Sara Kim",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1733920571/sara_400x400.jpg",
      "role": "setter",
      "zones": {
        "personas": "view",
        "campaigns": "view",
        "chat": "edit",
        "leads": "edit",
        "settings": "view"
      },
      "status": "active",
      "created_at": "2026-09-14T09:21:05.300Z"
    },
    {
      "id": "Tm8vX2pLnC",
      "object": "team_member",
      "email": "dev@acme.com",
      "name": null,
      "profile_image_url": null,
      "role": "custom",
      "zones": {
        "personas": "edit",
        "campaigns": "view",
        "chat": "view",
        "leads": "edit",
        "settings": "view"
      },
      "status": "invited",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "max_members": 50
}

The team member object

Someone the owner shares the X account with, or an invite they have not taken yet.

Attributes

idstring
Unique identifier for the member.
objectstring
Always team_member.
emailstring
The email the invite went to.
namestring or null
Their name in Gemlead. Null until they join.
profile_image_urlstring or null
Their profile picture's URL.
rolestring
viewer sees everything and changes nothing. setter works the chat and the leads. editor changes everything but the settings. admin changes everything and runs the team. custom changes the zones you pick.
viewersettereditoradmincustom
zonesobject
What the member may change, zone by zone, each view or edit. The role sets them, and custom keeps the ones you pick.
statusstring
active once they have a Gemlead account at this email, invited until then.
invitedactive
created_atstring
When the invite was sent, ISO 8601.

Team member object

{
  "id": "Tm4kQ9wZrB",
  "object": "team_member",
  "email": "sara@acme.com",
  "name": "Sara Kim",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1733920571/sara_400x400.jpg",
  "role": "setter",
  "zones": {
    "personas": "view",
    "campaigns": "view",
    "chat": "edit",
    "leads": "edit",
    "settings": "view"
  },
  "status": "active",
  "created_at": "2026-09-14T09:21:05.300Z"
}

Invite a member

POST/v1/team/memberswrite scopeMCPedit_team

Invites someone to the X account's team by email, with a role, and sends them an email. Someone with a Gemlead account at this email joins at once, anyone else once they sign up with it.

Body parameters

emailstringRequired
The person's email, up to 200 characters.
rolestringRequired
What the member may do. See role in the team member object.
viewersettereditoradmincustom
zonesobject
With the custom role only, what the member may change, zone by zone, each view or edit. A zone left out is view.

Returns

The new team member object, its status at active when they have a Gemlead account, else invited.

Errors

400parameter_missing
A required parameter is missing. param names it.
400parameter_invalid
A parameter has a value the API does not accept, like zones with a role other than custom or the owner's own email. param names it.
400parameter_unknown
The body has a field this endpoint does not take.
403forbidden
The key's user may not change the team. The owner and the admins can, and only the owner makes or changes an admin.
400resource_already_exists
This email is in the team already, as a member or an invite.
400limit_reached
The X account has 50 members already, invites included.

POST/v1/team/members

curl -X POST https://gemlead.ai/api/v1/team/members \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@acme.com",
    "role": "custom",
    "zones": {
      "personas": "edit",
      "leads": "edit"
    }
  }'

Response200

{
  "id": "Tm8vX2pLnC",
  "object": "team_member",
  "email": "dev@acme.com",
  "name": null,
  "profile_image_url": null,
  "role": "custom",
  "zones": {
    "personas": "edit",
    "campaigns": "view",
    "chat": "view",
    "leads": "edit",
    "settings": "view"
  },
  "status": "invited",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Update a member

PATCH/v1/team/members/:member_idwrite scopeMCPedit_team

Changes a member's role, or what they may change zone by zone. Sending zones makes the role custom, and only the zones you send change.

Path parameters

member_idstringRequired
The team member's ID.

Body parameters

rolestring
What the member may do. See role in the team member object.
viewersettereditoradmincustom
zonesobject
The zones to change, each view or edit. The others stay as they are.

Returns

The updated team member object.

Errors

404resource_missing
No team member with this ID on the key's account.
400parameter_invalid
A parameter has a value the API does not accept. param names it.
400parameter_unknown
The body has a field this endpoint does not take.
403forbidden
The key's user may not change the team. The owner and the admins can, and only the owner makes or changes an admin.

PATCH/v1/team/members/:member_id

curl -X PATCH \
  https://gemlead.ai/api/v1/team/members/Tm4kQ9wZrB \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "editor"
  }'

Response200

{
  "id": "Tm4kQ9wZrB",
  "object": "team_member",
  "email": "sara@acme.com",
  "name": "Sara Kim",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1733920571/sara_400x400.jpg",
  "role": "editor",
  "zones": {
    "personas": "edit",
    "campaigns": "edit",
    "chat": "edit",
    "leads": "edit",
    "settings": "view"
  },
  "status": "active",
  "created_at": "2026-09-14T09:21:05.300Z"
}

Remove a member

DELETE/v1/team/members/:member_idwrite scopeMCPedit_team

Removes a member from the team, or cancels an invite. They lose access to the X account at once.

Path parameters

member_idstringRequired
The team member's ID.

Returns

An object with the member's id and deleted set to true.

Errors

404resource_missing
No team member with this ID on the key's account.
403forbidden
The key's user may not change the team. The owner and the admins can, and only the owner makes or changes an admin.

DELETE/v1/team/members/:member_id

curl -X DELETE \
  https://gemlead.ai/api/v1/team/members/Tm8vX2pLnC \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "Tm8vX2pLnC",
  "object": "team_member",
  "deleted": true
}

Leave the team

POST/v1/team/leavewrite scopeMCPedit_team

Takes the key's own user out of the X account's team. It works with a member's key, never with the owner's.

Returns

An object with the member's id and deleted set to true.

Errors

400owner_cannot_leave
The key is the owner's. The owner removes members instead.

POST/v1/team/leave

curl -X POST https://gemlead.ai/api/v1/team/leave \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "Tm4kQ9wZrB",
  "object": "team_member",
  "deleted": true
}