API reference

Team

6 endpoints in this group.

Lists team members

GET/api/v1/team/members

Needs admin permission. Scope: team:read.

Scope
team:read
SDK method
listTeamMembers · list_team_members
MCP tool
listTeamMembersread-only

Paginated

Parameters

NameTypeRequiredDescription
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/team/members?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "email": "ayse@example.com",
      "role": "owner",
      "bot_ids": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ],
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Changes a member's role and bot access

PATCH/api/v1/team/members/{id}

Only the owner can change roles and the owner role can't be granted (ownership transfer stays in the dashboard). bot_ids applies to the member role only; null means all bots. Needs admin permission. Scope: team:write.

Scope
team:write
SDK method
updateTeamMember · update_team_member
MCP tool
updateTeamMemberirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
roleenumnoadmin | member
bot_idsuuid[] | nullnoitems ≤ 200

Example request

curl -X PATCH "https://hiboty.com/api/v1/team/members/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"member","bot_ids":["3fa85f64-5717-4562-b3fc-2c963f66afa6"]}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "email": "ayse@example.com",
    "role": "owner",
    "bot_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Removes a member from the team

DELETE/api/v1/team/members/{id}

The owner and the key's creator can't be removed (409 member_not_removable); only the owner can remove an admin. The member's conversation assignments are cleared. Needs admin permission. Scope: team:write.

Scope
team:write
SDK method
removeTeamMember · remove_team_member
MCP tool
removeTeamMemberirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/team/members/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true,
    "unassigned_conversations": 1
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.member_not_removable
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists pending invitations

GET/api/v1/team/invitations

The invitation link isn't returned. Needs admin permission. Scope: team:read.

Scope
team:read
SDK method
listTeamInvitations · list_team_invitations
MCP tool
listTeamInvitationsread-only

Paginated

Parameters

NameTypeRequiredDescription
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/team/invitations?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "ayse@example.com",
      "role": "admin",
      "expires_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Sends a team invitation

POST/api/v1/team/invitations

The plan's seat limit applies, as in the dashboard (403 plan_limit). The invitation goes by email and the link isn't returned; email_sent is false if the email couldn't be sent. Needs admin permission. Scope: team:write.

Scope
team:write
SDK method
createTeamInvitation · create_team_invitation
MCP tool
createTeamInvitationexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
emailemailyes
roleenumyesadmin | member

Example request

curl -X POST "https://hiboty.com/api/v1/team/invitations" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","role":"member"}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "ayse@example.com",
    "role": "admin",
    "expires_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "email_sent": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.plan_limit
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Cancels an invitation

DELETE/api/v1/team/invitations/{id}

Needs admin permission. Scope: team:write.

Scope
team:write
SDK method
cancelTeamInvitation · cancel_team_invitation
MCP tool
cancelTeamInvitationirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/team/invitations/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.