API reference

Every operation the public REST API (`/api/v1`) exposes, generated from the OpenAPI document.

Get the caller's profile

Returns the signed-in caller's own Falconry Scale profile: name, bio, display preferences, and subscription tier. Call this first to learn who the caller is before any raptor-scoped call.

Edits the caller's own profile: name, bio, location, display preferences (units, precision, date format, language) and falconry experience. Only the fields you send change; null clears an optional field. Email, plan and photos can't be changed here.

Get today's roster checklist

A single-call morning overview: how many raptors the caller has, which have already been weighed today, which still need weighing, and the caller's unread alert count. Prefer this over separate list_raptors + get_latest_weights + list_alerts calls when all you need is the checklist.

Get notification preferences

Returns the caller's notification switches: each push toggle, its matching `_email` toggle, the push master switch, and the evening digest time (UTC). Unset switches show the app's default.

Update notification preferences

Turns individual notification switches on or off, or changes the evening digest time (HH:MM, UTC). Only the keys you send change. Returns the full, updated preferences.

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`.

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.

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.

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.

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.

List a raptor’s past moults

Returns a raptor's finished moults, most recent first, with start/end dates (ISO 8601) and end weight in grams.

Get a raptor’s weight-alert thresholds

Returns the thresholds that raise a weight alert for this raptor: a rapid-drop percent and a min/max weight in grams.

Update a raptor’s weight-alert thresholds

Changes the weight-alert thresholds. Only the fields you send change; null turns a threshold off. Needs edit rights on the bird.

Star or unstar a raptor

Marks a raptor as a favourite (isFavorite true) or removes the star (false). Returns the updated raptor.

Change a raptor's status

Moves a raptor through its lifecycle: active, sold, deceased, released, or archived (archive hides it from the active roster without deleting anything). Can be reversed by setting 'active' again, which fails with 409 quota_exceeded when the bird's owner is on the free plan and already has 3 active birds. Confirm with the user before marking a bird sold, deceased or released.

Set a raptor's ready weight

Sets the raptor's flying (ready) weight and tolerance in grams, the numbers the morning checklist compares each weigh-in against.

Put a raptor into moult

Starts moult mode for a raptor (optionally with a moult target weight in grams). End it with end_moult, which records the moult in the history.

End a raptor’s moult

Ends moult mode. The finished moult (start, end, and the bird's latest weigh-in as the end weight) is saved to list_moult_history.

Share a raptor with the team, or make it private

Owner only. shared true shares the bird with the caller's team (every member then sees it, and members can log on it); false makes it private again and cuts off teammates' access. Confirm with the user before changing who can see a bird.

Get a raptor’s weigh-in history

Returns one raptor's logged weigh-ins, newest first, in grams. Use `since` to bound a date range and `limit` to cap the count (default and max 500). A free-tier account's history beyond 30 days reads as empty (the app's own retention rule), not an error.

Log a weigh-in

Records a new weigh-in for a raptor, in grams. This is how an AI assistant logs a scale reading on the caller's behalf.

Get the latest weigh-in per raptor

Returns each raptor's two most recent weigh-ins plus its target/ready weight, for a fast morning-checklist read ("who still needs weighing today, who's out of range"). Pass `raptorIds` to scope to a subset, or omit it to check the whole roster.

Get one weigh-in

Returns one weigh-in by id, including the name of the food item fed (fed weigh-ins only). 404s if it does not exist or is not visible to the caller.

Correct a weigh-in

Corrects a logged weigh-in (a mistyped weight, the wrong time, a missing note). Only the fields you send change; null clears an optional field. The grams-per-hour figures are recalculated. Weight alerts are not re-run.

Delete a weigh-in

Permanently deletes one weigh-in. This cannot be undone. Before calling, read the entry back to the user (weight, date and raptor) and get their explicit confirmation.

List a raptor’s activities

Returns one raptor’s logged activities (feeding, training, hunting, flight exercise, health observation, transport), newest first. Filter by `activityType` and/or a `from`/`to` date range.

Log a training, flight, or hunting activity

Records a training, flight-exercise, or hunting session for a raptor on the caller's behalf, with optional training details (creance length, recall distance in metres) and, for a hunt, the outcome, prey count and slip assessment. For feeding, use log_feeding instead.

Get one activity

Returns one feeding, training, hunting or other activity by id, with every recorded detail. 404s if it does not exist, was deleted, or is not visible to the caller.

Correct an activity

Edits a logged activity. Only the fields you send change; null clears an optional field. The weight change is recomputed from the pre/post flight weights. A hunt's outcome and slip assessment can't be edited after logging. Team members may edit only rows they logged themselves; owners and admins may edit any.

Delete an activity

Deletes one activity (feeding, training, hunt, ...). It disappears from every list and cannot be restored from this API. Before calling, read the activity back to the user (type, date and raptor) and get their explicit confirmation.

Log a feeding

Records a feeding activity for a raptor on the caller's behalf. For a scale reading of the amount fed, use log_weight with stomachState 'fed' instead.

List food items

Returns the food items the caller can log (built-in ones plus their own custom items), with the caller's favourite flag and usage count. Use an item's `id` as `preyTypeId` in log_weight / update_weight for a fed weigh-in.

Add a custom food item

Adds a custom food item to the caller's list. Names must be unique per user (case-insensitive): a duplicate answers 409 duplicate_name.

Edit a custom food item

Edits one of the caller's own custom food items (built-in items can't be edited: 404). Only the fields you send change; null clears an optional field.

Star or unstar a food item

Marks a food item (built-in or custom) as one of the caller’s favourites, or removes the star.

List a raptor’s feeding schedules

Returns a raptor's feeding schedules, oldest first: target weight, daily feed slots, whether it is a moult schedule, and any bring-down plan parameters. For the day-by-day bring-down targets, use get_bring_down_plan.

Get a raptor’s active bring-down plan

Returns the raptor's active bring-down plan (bringing the bird from its start weight down to its ready weight safely, at most 1.5% a day): today's day number, the total days, and the target weight for every day, in grams. `plan` is null when none is running.

Start a bring-down plan

Starts a bring-down plan for a raptor, the same as the app's Feeding plan screen: from its latest weigh-in down to its ready weight unless you pass other weights, over the safe minimum number of days. Fails with 409 if a plan is already running, and with 400 if there is no weigh-in or ready weight to default to. Returns the new plan's daily targets.

Stop the active bring-down plan

Stops the raptor's active bring-down plan (it is kept as an inactive schedule, not deleted). 404s if no plan is running.

List a raptor’s health records

Returns one raptor’s health-care history (observations, treatments, vet visits, vaccinations, lab results, ...), most recent first. Capped at 200 rows by default (use `limit`).

Add a health record

Records a health event for a raptor: an observation, treatment, vet visit, vaccination, injury, illness, medication, lab result, parasite check or moult note. Fill only the fields that apply. Attachments must be added in the app. For an ongoing medication course with dose tracking, use create_medication instead.

Get one health record

Returns one health record by id. 404s if it does not exist or is not visible to the caller.

Update a health record

Edits a health record, for example to record the outcome or resolution date of an illness. Only the fields you send change; null clears an optional field. Team members may edit only records they logged; owners and admins may edit any.

Delete a health record

Permanently deletes a health record AND its attached files. This cannot be undone. Before calling, read the record back to the user (type, date, raptor, and how many attachments it has) and get their explicit confirmation.

List a raptor’s medication courses

Returns one raptor’s medication courses (active and past), most recently started first. Capped at 200 rows by default (use `limit`).

Start a medication course

Adds a medication course for a raptor (name, dosage, frequency, start and optional end date, optional daily reminder). Log each day’s dose with log_medication_dose.

Get one medication course

Returns one medication course by id, with its dose log. 404s if it does not exist or is not visible to the caller.

Update a medication course

Edits a medication course, for example to change the dosage or set an end date to finish it. Only the fields you send change; null clears an optional field.

Delete a medication course

Permanently deletes a medication course and its whole dose log. This cannot be undone. To simply finish a course, set its endDate with update_medication instead. Before deleting, confirm the course (name, raptor, dates) with the user.

Log a medication dose

Records whether one day's dose was taken, missed or skipped. Logging the same date again replaces that day's entry. Returns the course with its updated dose log.

List documents

Lists the caller's documents (permits, CITES papers, vet records, insurance, ...) as metadata: title, type, dates, issuing authority and file name/size, newest first. No file contents or download links. Pass `expiringWithinDays` for the renewals view, soonest expiry first.

Get one document’s details

Returns one document's metadata by id (no file contents or link). 404s if it does not exist or is not visible to the caller.

Update a document’s details

Edits a document's details (title, dates, issuing authority, tags, expiry reminders, which raptor it belongs to). The file itself can't be changed through the API. Only the fields you send change; null clears an optional field.

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.

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.

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).