FalconryScale
DevelopersAPI reference

Add a raptor

Adds a new bird to the caller's roster. Look up `speciesId` with search_species first. A free-tier account is capped at 3 active raptors: past the cap this answers 409 quota_exceeded, and the caller has to upgrade in the app. Confirm the name and species with the user before calling.

POST
/raptors

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
name*string
Length1 <= length <= 100
speciesId*string

From search_species.

Lengthlength <= 64
acquisitionDate*string

ISO 8601 date (yyyy-mm-dd) the bird was acquired.

Match^\d{4}-\d{2}-\d{2}$
acquisitionMethod*string
Value in"bred""trapped""rescued""purchased""transferred""other"
gender?string
Value in"male""female""unknown"
birthDate?string

Hatch date, ISO 8601 (yyyy-mm-dd).

Match^\d{4}-\d{2}-\d{2}$
bandNumber?string
Length1 <= length <= 100
microchipId?string
Length1 <= length <= 100
targetWeightMinGrams?number

Grams.

Range0 < value <= 20000
targetWeightMaxGrams?number

Grams.

Range0 < value <= 20000
transmitterFrequencyMhz?number

Telemetry transmitter frequency, MHz.

Range0 < value <= 10000
notes?string
Lengthlength <= 4000
shareWithTeam?boolean

Share the new bird with the caller's team. Defaults to true when the caller is on a team.

Response Body

Add a raptor

application/json
  1. response
id*string

Opaque Convex document id.

Lengthlength <= 64
name*string
species*|null
gender*|null
status*|null
acquisitionDate*string

ISO 8601 date (yyyy-mm-dd).

birthDate*|

ISO 8601 date (yyyy-mm-dd), the hatch date.

bandNumber*string|null
microchipId*string|null
notes*string|null
avatarUrl*string|null
headerUrl*string|null
targetWeightMinGrams*number|null
targetWeightMaxGrams*number|null
readyWeightGrams*number|null
toleranceGrams*number|null
latestWeightGrams*|

The raptor's most recent logged weigh-in, grams.

isFavorite*boolean
isInMoult*boolean
moultStartedAt*|

ISO 8601 datetime the current moult started, when in moult.

moultTargetWeightGrams*number|null
acquisitionMethod*|null
fate*|null
fateNote*string|null
transmitterFrequencyMhz*number|null
isTeamShared*boolean

Whether the bird is shared with its owner's team.

ownerName*|

The owner's display name, for a team-shared bird the caller does not own.

canLog*boolean

Whether the caller may log weigh-ins, feedings and activities on this bird.

canEdit*boolean

Whether the caller may edit the bird's details and plans.

isOwn*boolean|null
myRole*|

'self' when the caller owns the bird, else their team role on it.

Example Request
curl -X POST 'https://app.falconryscale.com/api/v1/raptors' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "speciesId": "string",
  "acquisitionDate": "string",
  "acquisitionMethod": "bred"
}'
Example Response
{
  "id": "string",
  "name": "string",
  "species": {
    "id": "string",
    "commonName": "string",
    "scientificName": "string",
    "photoUrl": "string"
  },
  "gender": "male",
  "status": "active",
  "acquisitionDate": "string",
  "birthDate": "string",
  "bandNumber": "string",
  "microchipId": "string",
  "notes": "string",
  "avatarUrl": "string",
  "headerUrl": "string",
  "targetWeightMinGrams": 0,
  "targetWeightMaxGrams": 0,
  "readyWeightGrams": 0,
  "toleranceGrams": 0,
  "latestWeightGrams": 0,
  "isFavorite": true,
  "isInMoult": true,
  "moultStartedAt": "string",
  "moultTargetWeightGrams": 0,
  "acquisitionMethod": "bred",
  "fate": "active",
  "fateNote": "string",
  "transmitterFrequencyMhz": 0,
  "isTeamShared": true,
  "ownerName": "string",
  "canLog": true,
  "canEdit": true,
  "isOwn": true,
  "myRole": "self"
}

List the caller's raptors

Returns the caller's roster of raptors (birds), newest-added first. Each one carries its current target/ready weight and most recent weigh-in in grams. Use `get_raptor` for the full detail of one, or follow up with get_weight_history/list_activities/list_health_records using the returned `id`.

Get one raptor

Returns the full detail of one raptor by id. 404s if the raptor does not exist or is not visible to the caller.