FalconryScale
DevelopersAPI reference

Update a raptor's details

Edits a raptor's details. Only the fields you send change: omit a field to keep it, send null to clear it. Needs edit rights on the bird (its owner, or a team admin). Photos can't be changed through the API.

PATCH
/raptors/{raptorId}

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path Parameters

raptorId*string

A raptor's id, from list_raptors.

Lengthlength <= 64

Request Body

application/json
  1. body
name?string
Length1 <= length <= 100
speciesId?string

Opaque Convex document id.

Lengthlength <= 64
acquisitionDate?string

ISO 8601 date (yyyy-mm-dd).

Match^\d{4}-\d{2}-\d{2}$
acquisitionMethod?string
Value in"bred""trapped""rescued""purchased""transferred""other"
gender?|null
birthDate?|null
bandNumber?|null
microchipId?|null
targetWeightMinGrams?|null
targetWeightMaxGrams?|null
transmitterFrequencyMhz?|null
notes?|null
fate?string

Life-record outcome. For the roster lifecycle (active, sold, archived, ...) use set_raptor_status.

Value in"active""deceased""transferred""lost""released""other"
fateNote?|null

Response Body

Update a raptor's details

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 PATCH 'https://app.falconryscale.com/api/v1/raptors/string' \
  -H 'Content-Type: application/json' \
  -d '{}'
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"
}

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.

Search raptor species

Finds species by part of their common or scientific name, with typical weight ranges in grams. Use it to get the `speciesId` that create_raptor and update_raptor need.