FalconryScale
DevelopersAPI reference

Invite someone to the team

Owner or admin only. Sends a team invite EMAIL to the given address (this is the one tool that emails someone) and holds a seat for 14 days. Never call it on your own initiative: repeat the exact address and role back to the user and confirm before calling. Fails with 409 when the team is full or the address already has a pending invite, and with 429 after 5 invite changes (invites plus revokes) in an hour or 20 in a day. The invite code is not returned: the invitee joins from the email.

POST
/team/invites

Authorization

bearerAuth
headerAuthorizationBearer <token>

A Clerk user API key or OAuth access token carrying the falconry:read and/or falconry:write scope.

Request Body

application/json
  1. body
email*string

The invitee's email address, exactly as the user gave it.

Match^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Formatemail
Lengthlength <= 254
role*string

'member' can log on shared birds; 'viewer' is read-only. Admin seats can only be granted in the app.

Value in"member""viewer"
locale?string

Language of the invite email. Defaults to English.

Value in"en""it""es""ar"

Response Body

Invite someone to the team

application/json
  1. response
inviteId*string

Opaque Convex document id.

Lengthlength <= 64
expiresAt*string
emailQueued*boolean
Example Request
curl -X POST 'https://app.falconryscale.com/api/v1/team/invites' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com",
  "role": "member"
}'
Example Response
{
  "inviteId": "string",
  "expiresAt": "string",
  "emailQueued": true
}

Get the caller's team

Returns the caller's team: its name, the caller's role, members (display names and roles only), seat usage, and, for an owner or admin, pending invites with masked addresses. `team` is null when the caller is not on a team.

Revoke a pending invite

Owner or admin only. Cancels a pending team invite so its link stops working and the seat frees up. Cannot be undone (send a new invite instead), so confirm which invite with the user first. Counts toward the same 5 per hour / 20 per day limit as invites (429 when exceeded).