REST API

The REST API reads and writes the same data the FalconryScale app shows you, over plain HTTP. It's meant for scripts and server-to-server calls, not for a browser fetch() from a third-party page, no CORS headers are served.

Base URLCopy Anchor Link

https://app.falconryscale.com/api/v1

AuthenticationCopy Anchor Link

Every request needs a bearer credential carrying falconry:read and, for a write endpoint, falconry:write scope too:

Authorization: Bearer <api key or OAuth access token>

Session cookies aren't accepted here. See API keys for the simplest way to get a credential, or OAuth for how an AI assistant connects without one.

EndpointsCopy Anchor Link

Every id (raptorId, a weight's id, and so on) is an opaque string, copy it from a previous response rather than constructing one yourself.

Reads use GET (inputs in the query string). Writes use POST to create or act, PATCH to change part of a record, and DELETE to remove one, all with a JSON body. A PATCH only changes the fields you send: leave a field out to keep it, send null to clear it. Every operation also exists as an MCP tool with the same name.

Profile, today and preferencesCopy Anchor Link

get_today_summary is one call for "how many raptors, which are already weighed today, which still need weighing, and my unread alert count", instead of three separate calls. update_profile covers your name, bio, location, display preferences and falconry experience; your email, plan and photos can't be changed through the API.

RaptorsCopy Anchor Link

list_raptors takes an optional scope query parameter: all (own and team-shared birds, the default), mine (own only), or team (every bird your team shares with you). create_raptor needs a speciesId from search_species, and a free account is capped at 3 active raptors. There's no delete: archive a bird with set_raptor_status instead, which you can undo.

WeightsCopy Anchor Link

get_weight_history takes optional since (an ISO 8601 datetime) and limit to bound the results, limit defaults to, and caps at, 500. get_latest_weights takes an optional raptorIds list (at most 200 ids), pass a comma-separated list of ids to scope it, or omit it to check your whole roster at once, the "who still needs weighing" read. log_weight needs weightGrams; measuredAt, stomachState (empty or fed), and prey details are optional.

ActivitiesCopy Anchor Link

list_activities takes optional activityType, and a from/to date range (ISO 8601 dates). Feeding is logged separately from training, flight exercise and hunting, use log_feeding for the former and log_activity for the latter. log_activity also takes training details (creance length and recall distance, in metres) and, for a hunt, the outcome, prey count and a slip assessment.

Food and feeding plansCopy Anchor Link

A food item's id is the preyTypeId a fed weigh-in takes. start_bring_down_plan defaults to the raptor's latest weigh-in and ready weight, over the same safe minimum number of days the app uses (never more than 1.5% a day).

HealthCopy Anchor Link

Both lists take an optional limit, defaulting to, and capped at, 200. A health record's attachments come back as metadata only (file name, type and size), not a download link, and attachments can only be added in the app. Deleting a health record also deletes its attached files.

DocumentsCopy Anchor Link

Documents are metadata only: title, type, issue and expiry dates, issuing authority, tags, and file name and size, never the file or a link to it. Pass expiringWithinDays to list_documents for the renewals view, soonest expiry first. Uploading and deleting documents stay in the app.

TeamCopy Anchor Link

Members are listed by display name and role only, never by email, and a pending invite shows a masked address. Inviting and revoking need the owner or admin role. invite_team_member sends the invite email (the only endpoint that emails anyone), accepts the member and viewer roles only, and never returns the join code: the invitee joins from the email.

Alerts and achievementsCopy Anchor Link

list_alerts is cursor-paginated: pass the previous response's nextCursor to get the next page, and stop once hasMore is false. list_achievements returns your total XP, what you've unlocked, and your progress toward the rest.

Not available through the APICopy Anchor Link

Account deletion, subscriptions and payments, the marketplace, file uploads, and public share links stay in the app.

Data notesCopy Anchor Link

• Weights are always grams. Whatever unit a person's own display preference uses, every weight this API returns or accepts is in grams.
• Dates and datetimes are ISO 8601. A date-only field (like an activity's activityDate) is yyyy-mm-dd; a full timestamp (like a weigh-in's measuredAt) includes the time.
• Team birds follow the caller's role. A raptor shared with your team carries isOwn and myRole (self for your own birds, otherwise your team role on that bird), and list_raptors's scope parameter controls whose birds come back.

For the exact request and response shape of every field, see the generated API reference. For status codes and the error format, see Errors and rate limits.