Getting started

The fam. API

Every published endpoint, as it is: the same table the application runs on, described. One base URL, one envelope, one kind of id, a key that acts as its owner: a person, or an integration.

Base URL: https://app.fam.services/api/v1
Auth: Bearer key
Format: JSON · OpenAPI 3.1.0
Endpoints: 41 in 12 resources

Three steps

An admin mints a key on the organization's console, Console › API: their own, or an integration's. It is shown once. The key acts as its owner, with the owner's permission profile at every location, and only within its scopes (whose key, which scopes).
Send it as a bearer on every request: Authorization: Bearer fam_…. No cookie, no CSRF token.
Every reply says ok first. A refusal is a 4xx that names its error, the param it is about, a message and its doc_url (the envelope, every word). An id says what it is: ticket_…, user_…. Every reply carries Request-Id; a write takes Idempotency-Key; a list pages on cursor; what happens reaches your webhooks.

Resources

Assets2 endpointsA thing at a location that tickets are about: a machine, a door, a printer, a vehicle.Attachments1 endpointA file on a record (a ticket, a comment, a cost, an asset, a location): a photo, a worksheet, a certificate, an invoice; stored once, read through a short-lived signed URL, kept when its record is deleted.Bookings7 endpointsOne person holding one bookable thing for one window: pending, approved, checked in, released.Comments2 endpointsWhat people write on a ticket, a planned ticket, a booking: the conversation on the thing.Files1 endpointA file a caller uploaded through the API (POST /files), waiting to be attached to a record by its id; unattached, it is dropped after a day.Locations3 endpointsA place the organization runs: an address with areas, assets, tickets and the people who have access there.Me1 endpoint Notifications7 endpointsOne line in a person's inbox: what happened, to what, by whom; read, done, snoozed.Search1 endpointOne box over everything the person may see: tickets, people, locations, assets and more, matched on a number, a name or a few words, narrowed by `key:value` tokens, answered grouped by kind.Tickets9 endpointsOne piece of work at a location: reported, accepted, scheduled, done, rated.Time off5 endpointsDays a person is away: requested, approved, counted against a balance, shown on the team's calendar.Users2 endpointsA human with a seat. Copy names the person or says "person" / "people"; the table is `users`.

Getting started

Authentication

A bearer key on every request. A key acts as its owner, a person or an integration, with that owner's permission profile at every location and only within the key's scopes: there is no organization-wide key that sees everything. A key never exceeds its owner, and never its scopes.

Header

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

Whose key

A personal key is a person's: minted by an admin on Console › API, it acts as them, with their access, and stops when their seat does. It is free, and it is the way to evaluate the API. An integration is an account of the organization's own: a system, named after what it is (SAP sync, the badge printer), with a permission profile an admin gives it at each location and keys of its own. It never signs in, never appears among people, and what it does is recorded under its name. It is licensed like an operator seat, per integration. A key can be moved from a person to an integration without minting a new secret.

Scopes

Every key carries scopes: all, or one word per resource and verb. read covers the resource's GET operations; write covers every operation of it, the reads included. Each endpoint's page names the scope it wants; a key without it is refused insufficient_scope, with reason naming the scope. A scope narrows a key; the owner's profile decides the rest (forbidden beyond it).

The words

allevery operation

Every operation.

assets:readread

The assets operations that read (GET).

bookings:readread

The bookings operations that read (GET).

bookings:writewrite

The bookings operations that write (every method; the reads included).

files:writewrite

The files operations that write (every method; the reads included).

locations:readread

The locations operations that read (GET).

notifications:readread

The notifications operations that read (GET).

notifications:writewrite

The notifications operations that write (every method; the reads included).

search:readread

The search operations that read (GET).

tickets:readread

The tickets operations that read (GET).

tickets:writewrite

The tickets operations that write (every method; the reads included).

time_off:readread

The time off operations that read (GET).

time_off:writewrite

The time off operations that write (every method; the reads included).

users:readread

The users operations that read (GET).

Schemes

api_keyhttp · bearer

An API key minted on the organization's console (Console › API), sent as Authorization: Bearer fam_…. The key acts as its owner — the person who minted it, or an integration (a bot account of the organization with a permission profile of its own) — with that owner's permission profile at every location. It carries scopes: all, or per resource <resource>:read (its GET operations) and <resource>:write (every operation of it, the reads included); each operation below names the scope it wants. It may expire, and it can be rotated with a day of grace.

sessionapiKey

The signed-in session (the application's own browser cookie).

Getting started

Envelope

Every reply is one JSON object that says ok first. What follows is the row's own words. Every reply also carries the same few headers.

2xx Done

4xx Refused

The envelope of a refusal: a 4xx status, ok: false, the error word (and a finer reason), the param it is about, the message sentence, the doc_url of the word and the call_id of this call. Every word is listed under Errors.

okbooleanrequired

false.

errorenumrequired

The machine word for the refusal (invalid_field, not_found, too_soon): what to branch on. Every word is listed under Errors.

Values: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight no_country no_policy no_approver no_bucket invalid_state comment_required no_attachments purged no_recipients no_valid_recipients too_many_recipients kind_invalid invalid_request attachment_missing no_assignment asset_required asset_no_category floor_inactive checklist_required file_too_large file_not_found target_has_no_access not_bookable already_booked too_long too_soon too_far_ahead too_many_days multi_day_not_allowed outside_opening_hours space_closed company_closed away profile_not_allowed no_check_in_required too_early too_late off_network not_live released_no_show booking_canceled already_decided url_invalid no_events too_many_endpoints

messagestringrequired

The word's sentence, in English: what happened, for a log or a developer.

doc_urlstring · urirequired

The word's page on the reference.

call_idstringrequired

The id of this API call, the Request-Id header's value: what to quote to support.

paramstring

The query or body word the refusal is about, when it is about one.

reasonstring

The finer word under error, when there is one (unknown, type, either, window_not_a_time).

Headers on every reply

Request-Idheader

This call's id: what to quote to support (the console lists a key's calls by it).

Fam-Versionheader

The version of the contract that answered.

RateLimitheader

The key's quota (IETF draft 7): limit=600, remaining=<n>, reset=<seconds>.

RateLimit-Policyheader

The policy: 600;w=60.

Idempotent-Replayedheader

Present and true when the reply is the stored reply of the first call with this Idempotency-Key.

Getting started

Errors

Every error word the API answers, with its status and what it means. A refusal names one; branch on it. The doors' words may come from any endpoint; an endpoint's own words are listed on its page too.

Every endpoint may answer

not_signed_in401

No key on the request. Send Authorization: Bearer <api key>.

api_key_invalid401

The bearer is not a live key: it was never minted, it was revoked, or its owner is switched off (reason: integration_inactive for a deactivated integration, owner_inactive for a deactivated person).

api_key_expired401

The key passed its expiry. Mint a new one on the console, or rotate it before it expires.

insufficient_scope403

The key's scopes do not reach this operation; reason names the scope it wants (tickets:write). Mint a key with that scope, or with all.

forbidden403

The user the key acts as (a person, or an integration) may not do this here: their permission profile at the location does not allow it.

not_found404

No such record, or none the person may see. An id of the wrong kind answers the same.

invalid_field400

A word's value is not what it should be: param names it, reason says how (type, enum, format, unknown, id_kind, or the handler's own word).

invalid_body400

The body is not a JSON object, or not what the operation takes; reason says why.

missing_field400

A required word is missing; param names it. For a choice (asset_id or area_connection_id), param names the first alternative and reason is either.

plan_required403

The organization's plan does not include this surface (bookings, time off).

rate_limited429

Too many calls for this key in the window. Wait Retry-After seconds; the RateLimit header says when the window resets.

idempotency_key_reused422

The Idempotency-Key was already used for a different call (another path, method or body). A key replays one call only.

idempotency_in_flight409

The call with this Idempotency-Key is still running. Retry in a moment to receive its result.

An endpoint's own

no_country409

The person has no country set, so no holidays and no time-off policy apply to them yet.

no_policy409

No time-off policy of the organization covers the person for this type.

no_approver409

Nobody is in place to approve: the request needs an approver and the organization has not named one for the person.

no_bucket409

The organization has no file storage set up, so attachments cannot be posted.

invalid_state409

The request is not in a state this operation may change: reason says which (decided, started).

comment_required400

The comment's text is empty.

no_attachments404

The record has no attachments.

purged410

The attachments were purged: the record's files are no longer retained.

no_recipients400

No user_ids were named.

no_valid_recipients403

None of the people named may be nudged about this ticket (they are not in its audience).

too_many_recipients400

More people were named than a nudge may reach at once (25).

kind_invalid400

The kind is not one of the attachment kinds.

invalid_request400

The address is incomplete: record_id, file_name and the scope (location_id or organization_id) are all needed.

attachment_missing404

No stored file answers to that address.

no_assignment409

Nothing at the location answers that request for the caller: no active assignment matches the request (and the asset, for an asset request), or the caller may not raise it there.

asset_required400

The request is raised on an asset (level: asset) and none was named: send asset_id.

asset_no_category409

The asset has no category, so no request can be routed by it.

floor_inactive409

The area named is on a floor that is no longer available.

checklist_required409

The request asks for a checklist to be answered when the ticket is raised, which the API does not take: raise it in the app.

file_too_large413

The file is over the cap (200 MB).

target_has_no_access400

The person the booking is for has no access to the location.

not_bookable409

The desk or room is not bookable: its type is not set up for booking.

already_booked409

The window clashes with a booking that already holds the desk or room.

too_long409

The window is longer than the type allows.

too_soon409

The window starts sooner than the type allows.

too_far_ahead409

The window starts further ahead than the type allows.

too_many_days409

The series covers more days than the type allows.

multi_day_not_allowed409

The window spans more than one day and the type allows one.

outside_opening_hours409

The window lies outside the location's opening hours.

space_closed409

The desk or room is closed for that window.

company_closed409

The organization is closed that day (a holiday or a closure it set).

away409

The person is away that day (time off), so nothing is booked for them.

profile_not_allowed409

The person's permission profile may not book this type.

no_check_in_required409

The booking's type needs no check-in.

too_early409

Check-in has not opened yet; check_in_opens_at says when.

too_late409

The check-in deadline passed; the booking was released.

off_network403

Check-in from this network is not allowed: the person is not on the location's own network.

not_live409

The booking is not live: it is pending, released, canceled or over.

released_no_show409

The booking was released as a no-show and cannot be changed.

booking_canceled409

The booking was canceled.

already_decided409

The booking was already approved or rejected.

A refusal409

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Which endpoint answers what

no_country Create a time-off request
no_policy Create a time-off request
no_approver Create a booking, Create a time-off request
no_bucket Upload a file, Create a time-off request
invalid_state Cancel a time-off request
comment_required Create a comment
no_attachments List a ticket's attachments
purged List a ticket's attachments
no_recipients Nudge a ticket
no_valid_recipients Nudge a ticket
too_many_recipients Nudge a ticket
kind_invalid Get a signed URL
invalid_request Get a signed URL
attachment_missing Get a signed URL
no_assignment Create a ticket
asset_required Create a ticket
asset_no_category Create a ticket
floor_inactive Create a ticket
checklist_required Create a ticket
file_too_large Upload a file
target_has_no_access Create a booking
not_bookable Create a booking
already_booked Create a booking
too_long Create a booking
too_soon Create a booking
too_far_ahead Create a booking
too_many_days Create a booking
multi_day_not_allowed Create a booking
outside_opening_hours Create a booking
space_closed Create a booking
company_closed Create a booking
away Create a booking
profile_not_allowed Create a booking
no_check_in_required Check in to a booking
too_early Check in to a booking
too_late Check in to a booking
off_network Check in to a booking
not_live Check in to a booking
released_no_show Check in to a booking
booking_canceled Check in to a booking, Approve a booking, Reject a booking
already_decided Approve a booking, Reject a booking

Getting started

Ids

An id is its kind's word, an underscore and 28 hex characters, so you can tell a ticket's from a person's at a glance. Ids are stable forever.

The kinds this document uses

ticket_3108be4ef78579c8760ebf45b188any id

An id of any kind: its first word says which (ticket_…, user_…, location_…).

area_connection_cde4d183f90d8eacaab56447ec6carea connection id

The id of a area connection: area_connection_ + 28 hex characters. An area's connection to a location: the room as it exists there, with its floor, its outline on the plan, its bookable type.

asset_ca15f1c8f67d6a0abb4946917dccasset id

The id of a asset: asset_ + 28 hex characters. A thing at a location that tickets are about: a machine, a door, a printer, a vehicle.

organization_e76c2a2c00fe7837b9339f212b28organization id

The id of a organization: organization_ + 28 hex characters. A customer account: its people, locations, plans and settings, run by its admins.

cost_24f8d50960bc914dac705d81e834cost id

The id of a cost: cost_ + 28 hex characters. Money on a ticket: a quote, a cost, an invoice, approved against a budget.

planned_ticket_f6f64ca6ea9b6d9ed6e886c67f0dplanned ticket id

The id of a planned ticket: planned_ticket_ + 28 hex characters. Work that recurs on a schedule at a location: an inspection, a service, a check. Created from a planned template; each occurrence is a ticket.

planned_ticket_comment_f6f64ca6ea9b6d485bcec7383c82planned ticket comment id

The id of a comment: planned_ticket_comment_ + 28 hex characters. What people write on a ticket, a planned ticket, a booking: the conversation on the thing.

visit_9364cd6658caf118338dd324852evisit id

The id of a visit: visit_ + 28 hex characters. One scheduled occurrence of a planned ticket: its date, its check-in, its outcome.

ticket_3108be4ef78579c8760ebf45b188ticket id

The id of a ticket: ticket_ + 28 hex characters. One piece of work at a location: reported, accepted, scheduled, done, rated.

comment_241d4ddb405190758c14ce5d8c85comment id

The id of a comment: comment_ + 28 hex characters. What people write on a ticket, a planned ticket, a booking: the conversation on the thing.

page_fd8aaa19314e6e5d75022291b9c6page id

The id of a page: page_ + 28 hex characters. A document on a section, written in blocks, with an owner, a review interval and an audience.

time_off_request_31a4d5fa74118074085964c701a0time off request id

The id of a time-off request: time_off_request_ + 28 hex characters. A person asking for days off: a type, a range, who covers, approved or rejected by their manager.

time_off_type_31a4d5fa7e747a7fe076c20a6e06time off type id

The id of a time-off type: time_off_type_ + 28 hex characters. A kind of time off the organization grants in a country: paid or not, needs proof or not, how many days a year.

location_bfa88cf22cff5365bfa88cf22cfflocation id

The id of a location: location_ + 28 hex characters. A place the organization runs: an address with areas, assets, tickets and the people who have access there.

notification_1d119fe8c432064608bb17a9d1ddnotification id

The id of a notification: notification_ + 28 hex characters. One line in a person's inbox: what happened, to what, by whom; read, done, snoozed.

priority_f4d3f91dfcdbf115f4d3f91dfcdbpriority id

The id of a priority: priority_ + 28 hex characters. How urgent a ticket is, with the SLA clock it starts: acceptance, first attendance, resolution.

request_53029dd8f5e0dc0edb4c49e8f90drequest id

The id of a request: request_ + 28 hex characters. A ticket before it is a ticket: what a person files, from a request kind the organization set up.

booking_5144b032fbe428c411e9eb6ab1f9booking id

The id of a booking: booking_ + 28 hex characters. One person holding one bookable thing for one window: pending, approved, checked in, released.

bookable_type_51443c20581e5ed74c410e4e2a66bookable type id

The id of a bookable type: bookable_type_ + 28 hex characters. A kind of thing the organization makes bookable (a desk, a room, a parking spot): its icon, its rules, its labels.

status_252fa430b27d6d676c70fabd2d27status id

The id of a status: status_ + 28 hex characters. Where a ticket stands, in the organization's own words, under one of the app's states.

file_93733d5513f3bdd593733d5513f3file id

The id of a file: file_ + 28 hex characters. A file a caller uploaded through the API (POST /files), waiting to be attached to a record by its id; unattached, it is dropped after a day.

user_063659e14af21d2d8ebed169c27auser id

The id of a person: user_ + 28 hex characters. A human with a seat. Copy names the person or says "person" / "people"; the table is users.

event_056139bb7e3a9ec2c8c109e5b5bfevent id

The id of a event: event_ + 28 hex characters. One thing that happened (a booking created, a comment posted), delivered to every webhook endpoint subscribed to its name; retried until the endpoint answers 2xx.

Getting started

Pagination

ONE page shape on every list, ONE spelling of a moment on every word. A list takes limit and cursor, answers has_more and next_cursor; a lookup takes limit and answers its best matches.

A list

Send limit for the page size (the endpoint says its default and its ceiling). While has_more is true, send the reply's next_cursor as cursor. The cursor is opaque: a position in the list, never a page number, so a row added meanwhile shifts nothing and the tenth page costs what the first did.

limitinteger

How many rows to return at most (the row says its default and its ceiling).

cursorstring

Where the page starts: the next_cursor of the previous reply. Opaque; leave it out for the first page.

has_moreboolean

Whether a next page exists.

next_cursorstring,null

The cursor of the next page; null when this is the last page.

Lists: List assets, List the caller's bookings, List locations, List notifications, List tickets, List people. Lookups (limit alone): Search, Search tickets.

Time

An instant is RFC 3339, always UTC with milliseconds: 2026-09-18T09:12:00.000Z (created_at, start_at, until …); send one with any offset, it is read as the instant it names. A day is YYYY-MM-DD (from, to). A local wall-clock time, where a desk is booked in the location's own zone, is YYYY-MM-DD HH:mm (start_local, schedule_date); the endpoint says which zone.

Getting started

Rate limits

Every key may make 600 calls per 60 seconds, whatever it calls. Every reply says where the key stands; a 429 says how long to wait.

The headers

RateLimitheader

The key's quota (IETF draft 7): limit=600, remaining=<n>, reset=<seconds>.

RateLimit-Policyheader

The policy: 600;w=60.

More

An organization on the high-volume API add-on (Console › API) gives every one of its keys 3000 calls per 60 seconds, and keeps its calls log for a year in place of 30 days. The RateLimit-Policy header says which limit a key is under.

When you hit it

The reply is 429 with error: rate_limited and a Retry-After header in seconds. Wait that long, then continue; a client library backs off on it (the ones under SDKs and tools do). A few endpoints carry their own smaller limits on top (a nudge storm is a nudge storm); they answer the same word.

Getting started

Idempotency

A write retried after a timeout must not book the desk twice. Send Idempotency-Key on any write with a key of your choosing (a UUID); the same key replays the first reply for 24 hours.

The rule

The first call with a key runs and its reply is stored. The same key with the same call answers the stored reply, byte for byte, with Idempotent-Replayed: true. The same key with a different call (another path, method or body) is refused idempotency_key_reused; the same key while the first call is still running is refused idempotency_in_flight, retry in a moment. A 5xx or a 429 is not stored: retry those and get a real answer. Up to 255 characters, on POST, PUT, PATCH, DELETE.

Getting started

Versioning

The path is the version (/api/v1) and every reply says which one answered (Fam-Version). A change is additive and needs no action; a breaking change is never made in place.

The rule

Additive: a new endpoint, a new word in a reply, a new event, a new error word. Your code keeps working; read only the words you know. Breaking: a word renamed or removed, a shape changed, an endpoint removed. The old endpoint is marked deprecated with a sunset day at least 90 days out, every reply it gives carries Deprecation (RFC 9745) and Sunset (RFC 8594) and a Link to the entry below, its page says what to call instead, and it keeps answering until the day. Log those two headers in your client and nothing surprises you.

Changelog

2026-09-19addedIdentity: an INTEGRATION is an account of the organization's own (a system, with a permission profile and keys of its own, licensed per integration); a key belongs to a person or to an integration, and GET /me says which (seat: integration). A deactivated owner answers api_key_invalid with reason (integration_inactive, owner_inactive). Get the caller
2026-09-19changedScopes: a key carries scopes (all, or per resource <resource>:read / <resource>:write, write includes read) in place of read / write; every operation names the scope it wants (the document's security), and insufficient_scope names it in reason. Existing keys were carried over (write → all, read → every :read).
2026-09-19addedThe high-volume API add-on: 3,000 calls a minute per key in place of 600, and a year of calls kept; RateLimit-Policy says which.
2026-09-19addedThe records: the caller (GET /me), the tickets (a list with status, location_id, requester_id and updated_since for a sync; one by id; one created with POST /tickets for a request GET /locations/{id}/requests lists), the locations, the assets and the people. One shape per record; a search match is the record too. The event ticket.created. Get the caller, List tickets, Get a ticket, Create a ticket, List locations, Get a location, List what may be requested at a location, List assets, Get an asset, List people, Get a person
2026-09-19addedFiles: POST /files takes a file as multipart/form-data and answers its id; a comment or a ticket names the id in attachments (file_not_found for an id that was spent or never uploaded). Upload a file, Create a comment, Create a ticket
2026-09-19addedWebhooks: an organization registers https endpoints on Console › API and receives signed events (Fam-Signature, HMAC-SHA256) for bookings, comments, ticket updates and time off, retried on a backoff ladder.
2026-09-19addedEvery reply carries Request-Id (the call's id, call_id in every refusal), Fam-Version and the RateLimit headers; a key is limited per minute; a write honours Idempotency-Key for a day.
2026-09-19addedEvery refusal carries message (the word's sentence), doc_url (its anchor on the reference) and param (the word it is about); every word has a page under Errors.
2026-09-19changedONE page shape on every list: limit + cursor in, has_more + next_cursor out. before_ms / before_unread and the cursor object are gone (the first published version was never called). List notifications, List the caller's bookings
2026-09-19changedONE spelling of an instant: RFC 3339 (2026-09-18T09:12:00.000Z). start_at / end_at replace start_ts / end_ts, until replaces until_ms, check_in_opens_at / check_in_deadline / created_at / snooze_until are instants. Create a booking, List the caller's bookings, List notifications, Snooze notifications
2026-09-19changedA lookup takes limit (its ceiling on the row). Search tickets, Search
2026-09-19changedA request is validated at the door from the document: an unknown word, a wrong type, a missing required word or choice is refused with param and reason before the handler runs.
2026-09-18addedThe first published contract: 29 endpoints, one envelope, opaque ids, bearer keys minted on Console › API.

Getting started

Webhooks

What happens reaches you instead of being polled. An admin registers an https endpoint on Console › API with the events it takes; every matching event is delivered as a signed POST and retried until you answer 2xx.

A delivery

One JSON object: the delivery's id (dedupe on it; a retry carries the same one), the event name, occurred_at, and data, the record in the same words the matching read answers. Answer 2xx within 10 seconds. Anything else is retried 8 times on a ladder (1 min, 5 min, 30 min, 2 h, 12 h, 24 h, 24 h, 24 h); the console shows every delivery and its last status.

The signature

Fam-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 with the endpoint's secret over t, a dot, and the raw body. Recompute it over the exact bytes you received, compare in constant time, refuse a t older than 5 minutes. The secret is shown once when the endpoint is registered.

Events

booking.createdevent

A booking was made: confirmed, or pending an approver (pending says which). Delivered to every endpoint subscribed to booking.created; answer 2xx within 10 seconds or it is retried.

Its words

idbooking id

The record's id.

namestring

The record's name as people read it.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

location_idlocation id

The location's id.

location_namestring

The location's name.

floor_namestring

The floor's name, empty when the thing is not on a floor plan.

time_zonestring

The location's time zone (an IANA name).

start_atstring · date-time

The booking's start as an instant (instead of start_local).

end_atstring · date-time

The booking's end as an instant (instead of end_local).

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

pendingboolean

Whether the booking waits for an approver rather than being confirmed.

releasedboolean

Whether the booking was released before its end.

checked_inboolean

Whether the person checked in.

check_in_methodenum

How the person checked in: network (they were on the location's own network) or manual (they pressed check in); null before they do.

Values: network manual null

check_in_opens_atstring,null · date-time

From when the person may check in; null when the type needs no check-in.

check_in_deadlinestring,null · date-time

Until when the person must check in or lose the booking; null when the type needs no check-in.

booked_byobject,null

Who made the booking when it was not the person themself, null otherwise.

Its words

iduser id

The record's id.

namestring

The record's name as people read it.

booking.approvedevent

A pending booking was approved. Delivered to every endpoint subscribed to booking.approved; answer 2xx within 10 seconds or it is retried.

Its words

idbooking id

The record's id.

namestring

The record's name as people read it.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

location_idlocation id

The location's id.

location_namestring

The location's name.

floor_namestring

The floor's name, empty when the thing is not on a floor plan.

time_zonestring

The location's time zone (an IANA name).

start_atstring · date-time

The booking's start as an instant (instead of start_local).

end_atstring · date-time

The booking's end as an instant (instead of end_local).

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

pendingboolean

Whether the booking waits for an approver rather than being confirmed.

releasedboolean

Whether the booking was released before its end.

checked_inboolean

Whether the person checked in.

check_in_methodenum

How the person checked in: network (they were on the location's own network) or manual (they pressed check in); null before they do.

Values: network manual null

check_in_opens_atstring,null · date-time

From when the person may check in; null when the type needs no check-in.

check_in_deadlinestring,null · date-time

Until when the person must check in or lose the booking; null when the type needs no check-in.

booked_byobject,null

Who made the booking when it was not the person themself, null otherwise.

Its words

iduser id

The record's id.

namestring

The record's name as people read it.

booking.rejectedevent

A pending booking was rejected. Delivered to every endpoint subscribed to booking.rejected; answer 2xx within 10 seconds or it is retried.

Its words

idbooking id

The record's id.

namestring

The record's name as people read it.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

location_idlocation id

The location's id.

location_namestring

The location's name.

floor_namestring

The floor's name, empty when the thing is not on a floor plan.

time_zonestring

The location's time zone (an IANA name).

start_atstring · date-time

The booking's start as an instant (instead of start_local).

end_atstring · date-time

The booking's end as an instant (instead of end_local).

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

pendingboolean

Whether the booking waits for an approver rather than being confirmed.

releasedboolean

Whether the booking was released before its end.

checked_inboolean

Whether the person checked in.

check_in_methodenum

How the person checked in: network (they were on the location's own network) or manual (they pressed check in); null before they do.

Values: network manual null

check_in_opens_atstring,null · date-time

From when the person may check in; null when the type needs no check-in.

check_in_deadlinestring,null · date-time

Until when the person must check in or lose the booking; null when the type needs no check-in.

booked_byobject,null

Who made the booking when it was not the person themself, null otherwise.

Its words

iduser id

The record's id.

namestring

The record's name as people read it.

booking.canceledevent

A booking was canceled by its holder, or released by an admin. Delivered to every endpoint subscribed to booking.canceled; answer 2xx within 10 seconds or it is retried.

Its words

idbooking id

The record's id.

namestring

The record's name as people read it.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

location_idlocation id

The location's id.

location_namestring

The location's name.

floor_namestring

The floor's name, empty when the thing is not on a floor plan.

time_zonestring

The location's time zone (an IANA name).

start_atstring · date-time

The booking's start as an instant (instead of start_local).

end_atstring · date-time

The booking's end as an instant (instead of end_local).

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

pendingboolean

Whether the booking waits for an approver rather than being confirmed.

releasedboolean

Whether the booking was released before its end.

checked_inboolean

Whether the person checked in.

check_in_methodenum

How the person checked in: network (they were on the location's own network) or manual (they pressed check in); null before they do.

Values: network manual null

check_in_opens_atstring,null · date-time

From when the person may check in; null when the type needs no check-in.

check_in_deadlinestring,null · date-time

Until when the person must check in or lose the booking; null when the type needs no check-in.

booked_byobject,null

Who made the booking when it was not the person themself, null otherwise.

Its words

iduser id

The record's id.

namestring

The record's name as people read it.

booking.checked_inevent

The person checked in to their booking. Delivered to every endpoint subscribed to booking.checked_in; answer 2xx within 10 seconds or it is retried.

Its words

idbooking id

The record's id.

namestring

The record's name as people read it.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

location_idlocation id

The location's id.

location_namestring

The location's name.

floor_namestring

The floor's name, empty when the thing is not on a floor plan.

time_zonestring

The location's time zone (an IANA name).

start_atstring · date-time

The booking's start as an instant (instead of start_local).

end_atstring · date-time

The booking's end as an instant (instead of end_local).

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

pendingboolean

Whether the booking waits for an approver rather than being confirmed.

releasedboolean

Whether the booking was released before its end.

checked_inboolean

Whether the person checked in.

check_in_methodenum

How the person checked in: network (they were on the location's own network) or manual (they pressed check in); null before they do.

Values: network manual null

check_in_opens_atstring,null · date-time

From when the person may check in; null when the type needs no check-in.

check_in_deadlinestring,null · date-time

Until when the person must check in or lose the booking; null when the type needs no check-in.

booked_byobject,null

Who made the booking when it was not the person themself, null otherwise.

Its words

iduser id

The record's id.

namestring

The record's name as people read it.

ticket.createdevent

A ticket was raised through the API (POST /tickets); data is the ticket as GET /tickets/{id} answers it. Delivered to every endpoint subscribed to ticket.created; answer 2xx within 10 seconds or it is retried.

Its words

idticket id or planned ticket id or cost id

The record's id.

kindenum

Which kind of record: on a ticket, whether it is a ticket, a planned_ticket or (among search matches) a cost; on a file's address, the record the file hangs off.

Values: ticket planned_ticket cost

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

titlestring

The record's title: a ticket's description as one line, a page's heading.

descriptionstring

The ticket's description.

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: new upcoming rejected not_scheduled in_progress scheduled on_hold canceled completed

prioritystring,null

The ticket's priority, as the organization names it; null when none is set.

categorystring,null

The record's category, as the organization names it; null when none.

location_idlocation id

The location's id.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

request_idrequest id

The request's id: what the ticket is raised for (GET /locations/{id}/requests).

requester_iduser id

The id of the person who raised the ticket.

assignee_typeenum

What the assignee is: an organization (anyone of theirs may act), one user, or a team (a named group of people).

Values: organization team user

assignee_idany id

The assignee's id: an organization's, a team's or a person's, as assignee_type says.

field_operator_iduser id

The id of the field operator (the person doing the work on site).

scheduled_atstring,null · date-time

When the visit is scheduled; null until it is.

completed_atstring,null · date-time

When the work was completed; null until it is.

created_atstring · date-time

When the record was created.

updated_atstring · date-time

When the record last changed.

hrefstring,null · uri

The page in the app the record opens on.

ticket.updatedevent

A ticket's attributes were changed through the API; updated names them. Delivered to every endpoint subscribed to ticket.updated; answer 2xx within 10 seconds or it is retried.

Its words

idticket id or planned ticket id

The record's id.

updatedarray of strings

The attributes the write changed, by name.

comment.createdevent

A comment was posted on a ticket or a planned ticket. Delivered to every endpoint subscribed to comment.created; answer 2xx within 10 seconds or it is retried.

Its words

idcomment id or planned ticket comment id

The record's id.

ticket_idticket id

The ticket's (or planned ticket's) id.

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

user_iduser id

The person's id.

created_atstring · date-time

When the record was created.

time_off.requestedevent

A time-off request was made (status is pending, or approved when no approver was needed). Delivered to every endpoint subscribed to time_off.requested; answer 2xx within 10 seconds or it is retried.

Its words

idtime off request id

The record's id.

user_iduser id

The person's id.

time_off_type_idtime off type id

The id of the time-off type (one of the organization's types).

fromstring · date

The first day of the span, YYYY-MM-DD.

tostring · date

The last day of the span, YYYY-MM-DD.

partenum

For a half-day request: the morning (am) or the afternoon (pm).

Values: am pm

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: pending approved rejected cancelled

countednumber

How many days the request counts against the allowance (a half day counts 0.5).

created_atstring · date-time

When the record was created.

time_off.approvedevent

A time-off request was approved. Delivered to every endpoint subscribed to time_off.approved; answer 2xx within 10 seconds or it is retried.

Its words

idtime off request id

The record's id.

user_iduser id

The person's id.

time_off_type_idtime off type id

The id of the time-off type (one of the organization's types).

fromstring · date

The first day of the span, YYYY-MM-DD.

tostring · date

The last day of the span, YYYY-MM-DD.

partenum

For a half-day request: the morning (am) or the afternoon (pm).

Values: am pm

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: pending approved rejected cancelled

countednumber

How many days the request counts against the allowance (a half day counts 0.5).

created_atstring · date-time

When the record was created.

time_off.rejectedevent

A time-off request was rejected. Delivered to every endpoint subscribed to time_off.rejected; answer 2xx within 10 seconds or it is retried.

Its words

idtime off request id

The record's id.

user_iduser id

The person's id.

time_off_type_idtime off type id

The id of the time-off type (one of the organization's types).

fromstring · date

The first day of the span, YYYY-MM-DD.

tostring · date

The last day of the span, YYYY-MM-DD.

partenum

For a half-day request: the morning (am) or the afternoon (pm).

Values: am pm

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: pending approved rejected cancelled

countednumber

How many days the request counts against the allowance (a half day counts 0.5).

created_atstring · date-time

When the record was created.

time_off.canceledevent

A time-off request was taken back by the person. Delivered to every endpoint subscribed to time_off.canceled; answer 2xx within 10 seconds or it is retried.

Its words

idtime off request id

The record's id.

user_iduser id

The person's id.

time_off_type_idtime off type id

The id of the time-off type (one of the organization's types).

fromstring · date

The first day of the span, YYYY-MM-DD.

tostring · date

The last day of the span, YYYY-MM-DD.

partenum

For a half-day request: the morning (am) or the afternoon (pm).

Values: am pm

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: pending approved rejected cancelled

countednumber

How many days the request counts against the allowance (a half day counts 0.5).

created_atstring · date-time

When the record was created.

Verify it

# what a delivery looks like on the wire
POST https://example.com/hooks/fam
Content-Type: application/json
Fam-Event-Id: event_…
Fam-Signature: t=1758186720,v1=5f0c3a9e…

import crypto from 'node:crypto';

function verify(secret, header, body) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));
}
// body is the RAW request body (a string), never the parsed object

import hmac, hashlib, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(kv.split('=', 1) for kv in header.split(','))
    if abs(time.time() - int(parts['t'])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts['v1'])

A deliveryPOST

{
  "id": "event_056139bb7e3a9ec2c8c109e5b5bf",
  "event": "booking.created",
  "occurred_at": "2026-09-18T09:12:00.000Z",
  "data": {
    "id": "booking_5144b032fbe428c411e9eb6ab1f9",
    "name": "Desk 12",
    "asset_id": "asset_ca15f1c8f67d6a0abb4946917dcc",
    "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
    "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
    "location_name": "Warsaw, Marszałkowska 1",
    "floor_name": "2nd floor",
    "time_zone": "Europe/Warsaw",
    "start_at": "2026-09-21T07:00:00.000Z",
    "end_at": "2026-09-21T15:00:00.000Z",
    "comment": "On my way, there by 14:00.",
    "pending": false,
    "released": false,
    "checked_in": false,
    "check_in_method": "manual",
    "check_in_opens_at": "2026-09-21T06:45:00.000Z",
    "check_in_deadline": "2026-09-21T07:15:00.000Z",
    "booked_by": {
      "id": "user_063659e14af21d2d8ebed169c27a",
      "name": "Anna Kowalska"
    }
  }
}

Getting started

SDKs and tools

Generated from the same document, so they cannot drift from it: a client in JavaScript and in Python, a Postman collection, the OpenAPI file for any generator.

Clients

One file each, no dependencies: one method per endpoint in the endpoint's own words, the envelope read for you (a refusal throws with its error, message and call_id), Idempotency-Key minted on every write, a 429 waited out on Retry-After, every list walked with pages().

fam.js JavaScript (Node 18+, browsers): import { Fam } from './fam.js'
fam.py Python 3.9+, standard library only: from fam import Fam
postman.json a Postman collection: every endpoint, the key as a variable
openapi.json the contract, for any OpenAPI generator or validator

fam.js

import { Fam } from './fam.js';

const fam = new Fam('<api key>');
const { bookings } = await fam.bookings.mine({ limit: 10 });
for await (const b of fam.bookings.mine.pages()) console.log(b.id);
try {
  await fam.bookings.create({ asset_id: '<asset_id>', start_local: '2026-09-21 09:00', end_local: '2026-09-21 17:00' });
} catch (e) {
  console.log(e.error, e.message, e.call_id);   // 'too_soon', …
}

// A file: upload it (a File or a Blob), then name its id in attachments.
const { id } = await fam.files.create({ file });
await fam.tickets.comments.create({ id: '<ticket_id>', comment: 'Photo attached.', attachments: [id] });

fam.py

from fam import Fam, FamError

fam = Fam('<api key>')
page = fam.bookings.mine(limit=10)
for b in fam.bookings.mine.pages():
    print(b['id'])
try:
    fam.bookings.create(asset_id='<asset_id>', start_local='2026-09-21 09:00', end_local='2026-09-21 17:00')
except FamError as e:
    print(e.error, e.message, e.call_id)

# A file: a path, an open file, or (name, bytes, content_type); then its id in attachments.
uploaded = fam.files.create(file='roof-photo.jpg')
fam.tickets.comments.create(id='<ticket_id>', comment='Photo attached.', attachments=[uploaded['id']])

Resource

GET/assets

Returns the assets at the locations the caller may see, by name (50 a page, limit up to 200); location_id keeps one location's, q the ones whose name, type, reference, manufacturer or serial number matches.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs assets:read (or all); a key without it is refused insufficient_scope.

Query parameters

location_idlocation id

The location's id.

qstring

The search text: a number, a name, a few words.

limitinteger

How many rows to return at most (the row says its default and its ceiling).

cursorstring

Where the page starts: the next_cursor of the previous reply. Opaque; leave it out for the first page.

Response

okbooleanrequired

true.

assetsarray of objects

Assets, by name.

Each element

idasset id

The record's id.

namestring

The record's name as people read it.

asset_typestring,null

The asset's type, as the organization names it.

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

categorystring,null

The record's category, as the organization names it; null when none.

location_idlocation id

The location's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

manufacturerstring,null

The asset's manufacturer.

model_numberstring,null

The asset's model number.

serial_numberstring,null

The asset's serial number.

quantityinteger

How many units the asset row stands for.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

has_moreboolean

Whether a next page exists.

next_cursorstring,null

The cursor of the next page; null when this is the last page.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/assets' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/assets', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/assets',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "assets": [
    {
      "id": "asset_ca15f1c8f67d6a0abb4946917dcc",
      "name": "AC unit, meeting room 2",
      "asset_type": "Cassette AC unit",
      "reference": "AC-0031",
      "category": "Plumbing",
      "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
      "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
      "manufacturer": "Daikin",
      "model_number": "FTXM35R",
      "serial_number": "J004521",
      "quantity": 1,
      "active": true
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoxNzU4NDQ1MjAwMDAwLCJpIjoiYm9va2luZ18wMWEwYjRjNyJ9"
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Assets

Get an asset

GET/assets/{id}

Returns one asset at a location the caller may see, by its id.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs assets:read (or all); a key without it is refused insufficient_scope.

Path parameters

idasset idrequired

Response

okbooleanrequired

true.

assetobject

The asset.

Its words

idasset id

The record's id.

namestring

The record's name as people read it.

asset_typestring,null

The asset's type, as the organization names it.

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

categorystring,null

The record's category, as the organization names it; null when none.

location_idlocation id

The location's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

manufacturerstring,null

The asset's manufacturer.

model_numberstring,null

The asset's model number.

serial_numberstring,null

The asset's serial number.

quantityinteger

How many units the asset row stands for.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/assets/<asset_id>' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/assets/<asset_id>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/assets/<asset_id>',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "asset": {
    "id": "asset_ca15f1c8f67d6a0abb4946917dcc",
    "name": "AC unit, meeting room 2",
    "asset_type": "Cassette AC unit",
    "reference": "AC-0031",
    "category": "Plumbing",
    "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
    "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
    "manufacturer": "Daikin",
    "model_number": "FTXM35R",
    "serial_number": "J004521",
    "quantity": 1,
    "active": true
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Attachments

Get a signed URL

GET/attachments/signed-url

Returns a URL for one stored file's bytes, good for five minutes. Address the file the way an attachment reply hands it out: the s3 address (kind, record_id, location_id) and the file's file_name; a file on a connection or a time-off request is scoped by organization_id instead of the location. download asks for a download (saved as download_name) rather than an inline view; verify checks the object exists first (404 attachment_missing); deleted with the entry_id of the deletion signs a file that was deleted but is still retained, for an admin or the person who deleted it.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:read (or all); a key without it is refused insufficient_scope.

Query parameters

At least one of each: location_id or organization_id.

kindenumrequired

Which kind of record: on a ticket, whether it is a ticket, a planned_ticket or (among search matches) a cost; on a file's address, the record the file hangs off.

Values: page ticket planned_ticket cost cost_proposal recurrence asset area_connection location connection time_off_request

record_idany idrequired

The id of the record the attachment hangs off (a ticket, a cost, an asset, a location …); kind says which family.

file_namestringrequired

The file's stored name, as an attachment reply hands it out.

location_idlocation id

The location's id.

organization_idorganization id

The organization's id.

entry_idany id

The timeline entry's id.

verifyboolean

Whether to check that the object exists before signing.

downloadboolean

Whether to sign for a download (an attachment disposition) rather than an inline view.

download_namestring

The file name the download is saved as.

deletedboolean

Whether to sign a tombstoned object: deleted, still retained.

Response

okbooleanrequired

true.

signed_urlstring · uri

The short-lived URL of the bytes.

Errors

This endpoint's own error words:

kind_invalid400

The kind is not one of the attachment kinds.

invalid_request400

The address is incomplete: record_id, file_name and the scope (location_id or organization_id) are all needed.

attachment_missing404

No stored file answers to that address.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/attachments/signed-url?kind=ticket&record_id=%3Cany_id%3E&file_name=a1b2c3d4-roof-photo.jpg&location_id=%3Clocation_id%3E' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/attachments/signed-url?kind=ticket&record_id=%3Cany_id%3E&file_name=a1b2c3d4-roof-photo.jpg&location_id=%3Clocation_id%3E', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/attachments/signed-url?kind=ticket&record_id=%3Cany_id%3E&file_name=a1b2c3d4-roof-photo.jpg&location_id=%3Clocation_id%3E',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "signed_url": "https://files.fam.example/attachments/ticket_3f9a1c7e2b4d5f60718293a4b5c6d7e8/roof-photo.jpg?X-Amz-Expires=300&X-Amz-Signature=5f0c3a9e"
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Bookings

Create a booking

POST/bookings

Books a desk (asset_id) or a room (area_connection_id) over a window, for the caller or, with the grant to book for others, for user_id. The window is local wall-clock time in the location's zone (start_local, end_local) or two instants (start_at, end_at); with repeat_until_local the same hours repeat every day up to that date, one booking per day (created says how many). The booking is pending when the thing's rules ask an approver, else confirmed; a window that touches a booking the person already holds on the same thing is merged into it. Needs the Bookings add-on.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs bookings:write (or all); a key without it is refused insufficient_scope.

Body application/json

At least one of each: asset_id or area_connection_id; start_local + end_local or start_at + end_at.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

user_iduser id

The person's id.

start_localstring · local-date-time

The booking's start as local wall-clock time in the location's zone, YYYY-MM-DD HH:mm.

end_localstring · local-date-time

The booking's end, the same way.

start_atstring · date-time

The booking's start as an instant (instead of start_local).

end_atstring · date-time

The booking's end as an instant (instead of end_local).

repeat_until_localstring · date

Repeat the same hours every day up to this date: a series, not one long booking.

Response

okbooleanrequired

true.

idbooking id

The record's id.

pendingboolean

Whether the booking waits for an approver rather than being confirmed.

mergedboolean

Whether the window extended a booking the person already held instead of making a second one.

createdinteger

How many bookings the call made: 1, or one per day of a series.

Errors

This endpoint's own error words:

target_has_no_access400

The person the booking is for has no access to the location.

no_approver409

Nobody is in place to approve: the request needs an approver and the organization has not named one for the person.

not_bookable409

The desk or room is not bookable: its type is not set up for booking.

already_booked409

The window clashes with a booking that already holds the desk or room.

too_long409

The window is longer than the type allows.

too_soon409

The window starts sooner than the type allows.

too_far_ahead409

The window starts further ahead than the type allows.

too_many_days409

The series covers more days than the type allows.

multi_day_not_allowed409

The window spans more than one day and the type allows one.

outside_opening_hours409

The window lies outside the location's opening hours.

space_closed409

The desk or room is closed for that window.

company_closed409

The organization is closed that day (a holiday or a closure it set).

away409

The person is away that day (time off), so nothing is booked for them.

profile_not_allowed409

The person's permission profile may not book this type.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/bookings' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"asset_id":"<asset_id>","start_local":"2026-09-21 09:00","end_local":"2026-09-21 17:00"}'

const res = await fetch('https://app.fam.services/api/v1/bookings', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "asset_id": "<asset_id>",
    "start_local": "2026-09-21 09:00",
    "end_local": "2026-09-21 17:00"
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/bookings',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "asset_id": "<asset_id>",
      "start_local": "2026-09-21 09:00",
      "end_local": "2026-09-21 17:00"
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "id": "booking_5144b032fbe428c411e9eb6ab1f9",
  "pending": false,
  "merged": false,
  "created": 1
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Bookings

List the caller's bookings

GET/bookings/mine

Returns the caller's bookings a page at a time (50 by default, 200 at most), live and upcoming, the soonest first; past returns the ones that already ended instead, the latest first. Page on: send the reply's next_cursor as cursor while has_more is true. Needs the Bookings add-on.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs bookings:read (or all); a key without it is refused insufficient_scope.

Query parameters

limitinteger

How many rows to return at most (the row says its default and its ceiling).

cursorstring

Where the page starts: the next_cursor of the previous reply. Opaque; leave it out for the first page.

pastboolean

Whether to include bookings that already ended.

Response

okbooleanrequired

true.

bookingsarray of objects

The page's bookings, each naming the thing it holds by asset_id (a desk) or area_connection_id (a room), the other null.

Each element

idbooking id

The record's id.

namestring

The record's name as people read it.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

location_idlocation id

The location's id.

location_namestring

The location's name.

floor_namestring

The floor's name, empty when the thing is not on a floor plan.

time_zonestring

The location's time zone (an IANA name).

start_atstring · date-time

The booking's start as an instant (instead of start_local).

end_atstring · date-time

The booking's end as an instant (instead of end_local).

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

pendingboolean

Whether the booking waits for an approver rather than being confirmed.

releasedboolean

Whether the booking was released before its end.

checked_inboolean

Whether the person checked in.

check_in_methodenum

How the person checked in: network (they were on the location's own network) or manual (they pressed check in); null before they do.

Values: network manual null

check_in_opens_atstring,null · date-time

From when the person may check in; null when the type needs no check-in.

check_in_deadlinestring,null · date-time

Until when the person must check in or lose the booking; null when the type needs no check-in.

booked_byobject,null

Who made the booking when it was not the person themself, null otherwise.

Its words

iduser id

The record's id.

namestring

The record's name as people read it.

has_moreboolean

Whether a next page exists.

next_cursorstring,null

The cursor of the next page; null when this is the last page.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/bookings/mine' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/bookings/mine', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/bookings/mine',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "bookings": [
    {
      "id": "booking_5144b032fbe428c411e9eb6ab1f9",
      "name": "Desk 12",
      "asset_id": "asset_ca15f1c8f67d6a0abb4946917dcc",
      "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
      "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
      "location_name": "Warsaw, Marszałkowska 1",
      "floor_name": "2nd floor",
      "time_zone": "Europe/Warsaw",
      "start_at": "2026-09-21T07:00:00.000Z",
      "end_at": "2026-09-21T15:00:00.000Z",
      "comment": "On my way, there by 14:00.",
      "pending": false,
      "released": false,
      "checked_in": false,
      "check_in_method": "manual",
      "check_in_opens_at": "2026-09-21T06:45:00.000Z",
      "check_in_deadline": "2026-09-21T07:15:00.000Z",
      "booked_by": {
        "id": "user_063659e14af21d2d8ebed169c27a",
        "name": "Anna Kowalska"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoxNzU4NDQ1MjAwMDAwLCJpIjoiYm9va2luZ18wMWEwYjRjNyJ9"
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Bookings

Check availability

GET/bookings/availability

Returns, for each day of a span at a location (from and to; today and the thirteen days after it when absent, in the location's zone), the bookable types there and how many things of each are still free that day for the caller (the thing's rules, opening hours and closures already applied), whether the caller holds a booking that day, and the closure when the location is closed. Needs the Bookings add-on.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs bookings:read (or all); a key without it is refused insufficient_scope.

Query parameters

location_idlocation idrequired

The location's id.

fromstring · date

The first day of the span, YYYY-MM-DD.

tostring · date

The last day of the span, YYYY-MM-DD.

Response

okbooleanrequired

true.

fromstring · date

The first day of the span, YYYY-MM-DD.

tostring · date

The last day of the span, YYYY-MM-DD.

availabilityobject

Each day of the span by date (YYYY-MM-DD): the bookable types and how many of each are still free that day, whether the caller already holds a booking, and the closure when the location is closed.

Its words

typesarray of objects

The bookable types at the location, each with how many things of it exist and how many are still free that day.

Each element

bookable_type_idbookable type id

The bookable type's id (a desk, a room, a parking spot: one of the organization's types).

labelstring

The label, in the caller's language.

totalinteger

How many bookable things of the type the location has.

leftinteger

How many of them are still free that day.

bookedboolean

Whether the caller already holds a booking that day.

closedobject

The closure when the location is closed that day (a holiday, a closure the organization set), absent when it is open.

Its words

labelstring

The label, in the caller's language.

manualboolean

Whether the closure was set by the organization (rather than a public holiday).

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/bookings/availability?location_id=%3Clocation_id%3E' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/bookings/availability?location_id=%3Clocation_id%3E', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/bookings/availability?location_id=%3Clocation_id%3E',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "from": "2026-09-21",
  "to": "2026-09-25",
  "availability": {
    "2026-09-21": {
      "types": [
        {
          "bookable_type_id": "bookable_type_51443c20581e5ed74c410e4e2a66",
          "label": "Desk",
          "total": 24,
          "left": 7
        }
      ],
      "booked": false,
      "closed": {
        "label": "Public holiday",
        "manual": false
      }
    }
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Bookings

Release a booking

DELETE/bookings/{id}

Releases a booking of the caller's own (or, with the grant to book for others, anyone's at that location): the person no longer holds the thing for that window. A booking already released changes nothing (already). Needs the Bookings add-on.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs bookings:write (or all); a key without it is refused insufficient_scope.

Path parameters

idbooking idrequired

Response

okbooleanrequired

true.

alreadyboolean

Whether nothing changed because the record was already in that state.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X DELETE \
  'https://app.fam.services/api/v1/bookings/<booking_id>' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/bookings/<booking_id>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.delete(
    'https://app.fam.services/api/v1/bookings/<booking_id>',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "already": false
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Bookings

Check in to a booking

POST/bookings/{id}/check-in

Checks the person in to a booking whose check-in window is open: from check_in_opens_at until check_in_deadline (a booking not checked in by then is released as a no-show). The caller's own address on the location's network counts as a network check-in, anything else as manual. Checking in twice changes nothing (already). Needs the Bookings add-on.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs bookings:write (or all); a key without it is refused insufficient_scope.

Path parameters

idbooking idrequired

Response

okbooleanrequired

true.

alreadyboolean

Whether nothing changed because the record was already in that state.

Errors

This endpoint's own error words:

no_check_in_required409

The booking's type needs no check-in.

too_early409

Check-in has not opened yet; check_in_opens_at says when.

too_late409

The check-in deadline passed; the booking was released.

off_network403

Check-in from this network is not allowed: the person is not on the location's own network.

not_live409

The booking is not live: it is pending, released, canceled or over.

released_no_show409

The booking was released as a no-show and cannot be changed.

booking_canceled409

The booking was canceled.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/bookings/<booking_id>/check-in' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/bookings/<booking_id>/check-in', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/bookings/<booking_id>/check-in',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "already": false
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Bookings

Approve a booking

POST/bookings/{id}/approve

Approves a pending booking at a location where the caller is an admin or may approve bookings. Approving one already approved changes nothing (already); one already rejected is refused (already_decided). Needs the Bookings add-on.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs bookings:write (or all); a key without it is refused insufficient_scope.

Path parameters

idbooking idrequired

Response

okbooleanrequired

true.

alreadyboolean

Whether nothing changed because the record was already in that state.

Errors

This endpoint's own error words:

already_decided409

The booking was already approved or rejected.

booking_canceled409

The booking was canceled.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/bookings/<booking_id>/approve' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/bookings/<booking_id>/approve', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/bookings/<booking_id>/approve',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "already": false
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Bookings

Reject a booking

POST/bookings/{id}/reject

Rejects a pending booking at a location where the caller is an admin or may approve bookings. Rejecting one already rejected changes nothing (already); one already approved is refused (already_decided). Needs the Bookings add-on.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs bookings:write (or all); a key without it is refused insufficient_scope.

Path parameters

idbooking idrequired

Response

okbooleanrequired

true.

alreadyboolean

Whether nothing changed because the record was already in that state.

Errors

This endpoint's own error words:

already_decided409

The booking was already approved or rejected.

booking_canceled409

The booking was canceled.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/bookings/<booking_id>/reject' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/bookings/<booking_id>/reject', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/bookings/<booking_id>/reject',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "already": false
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Comments

Update a comment

PUT/comments/{id}

Replaces the text of a comment of the caller's own (never a comment the system wrote).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:write (or all); a key without it is refused insufficient_scope.

Path parameters

idcomment id or planned ticket comment idrequired

Body application/json

commentstringrequired

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

Response

okbooleanrequired

true.

idcomment id or planned ticket comment id

The record's id.

membershipenum

Whether the ticket left or joined the list the caller is looking at (left | joined), when the action changed it.

Values: left joined

alert_textstring

The sentence to show for what happened, in the caller's language.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X PUT \
  'https://app.fam.services/api/v1/comments/<comment_id>' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"comment":"On my way, there by 14:00."}'

const res = await fetch('https://app.fam.services/api/v1/comments/<comment_id>', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "comment": "On my way, there by 14:00."
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.put(
    'https://app.fam.services/api/v1/comments/<comment_id>',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "comment": "On my way, there by 14:00."
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "id": "comment_241d4ddb405190758c14ce5d8c85",
  "membership": "joined",
  "alert_text": "Anna and 2 others were reminded."
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Comments

Delete a comment

DELETE/comments/{id}

Deletes a comment of the caller's own (never one the system wrote): the timeline keeps a mark that it was deleted, by whom and when. A comment already deleted changes nothing. It cannot be undone.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:write (or all); a key without it is refused insufficient_scope.

Path parameters

idcomment id or planned ticket comment idrequired

Response

okbooleanrequired

true.

idcomment id or planned ticket comment id

The record's id.

membershipenum

Whether the ticket left or joined the list the caller is looking at (left | joined), when the action changed it.

Values: left joined

alert_textstring

The sentence to show for what happened, in the caller's language.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X DELETE \
  'https://app.fam.services/api/v1/comments/<comment_id>' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/comments/<comment_id>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.delete(
    'https://app.fam.services/api/v1/comments/<comment_id>',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "id": "comment_241d4ddb405190758c14ce5d8c85",
  "membership": "joined",
  "alert_text": "Anna and 2 others were reminded."
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Files

Upload a file

POST/files

Stages a file to attach with a later write: send it as multipart/form-data with one file part (up to 200 MB). Answers the file's id; name it in the attachments of a comment within a day, once, or it is dropped. The bytes are stored in the organization's own file storage (no_bucket when it has none).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs files:write (or all); a key without it is refused insufficient_scope.

Body multipart/form-data

filestringrequired

The file itself: the one multipart/form-data part of the request, its file name and media type read from the part.

Response

okbooleanrequired

true.

idfile id

The record's id.

namestring

The record's name as people read it.

bytesinteger

The file's size in bytes.

content_typestring

The file's media type as it was sent (image/jpeg, application/pdf).

Errors

This endpoint's own error words:

file_too_large413

The file is over the cap (200 MB).

no_bucket409

The organization has no file storage set up, so attachments cannot be posted.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/files' \
  -H 'Authorization: Bearer <api key>' \
  -F 'file=@roof-photo.jpg'

const form = new FormData();
form.append('file', file);   // a File or a Blob

const res = await fetch('https://app.fam.services/api/v1/files', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
  },
  body: form,
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/files',
    headers={'Authorization': 'Bearer <api key>'},
    files={'file': open('roof-photo.jpg', 'rb')},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "id": "file_93733d5513f3bdd593733d5513f3",
  "name": "roof-photo.jpg",
  "bytes": 184320,
  "content_type": "image/jpeg"
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Locations

List locations

GET/locations

Returns the locations the caller may see, by organization and name (50 a page, limit up to 200). q keeps the ones whose name, reference, address or city matches.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs locations:read (or all); a key without it is refused insufficient_scope.

Query parameters

qstring

The search text: a number, a name, a few words.

limitinteger

How many rows to return at most (the row says its default and its ceiling).

cursorstring

Where the page starts: the next_cursor of the previous reply. Opaque; leave it out for the first page.

Response

okbooleanrequired

true.

locationsarray of objects

Locations, by organization and name (a search: the matches).

Each element

idlocation id

The record's id.

namestring

The record's name as people read it.

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

organization_idorganization id

The organization's id.

addressstring

The street address, as one line.

citystring

The city.

postcodestring

The postal code.

country_codestring

The country, ISO 3166-1 alpha-2.

time_zonestring

The location's time zone (an IANA name).

latitudenumber,null

The location's latitude; null when it is not geocoded.

longitudenumber,null

The location's longitude; null when it is not geocoded.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

has_moreboolean

Whether a next page exists.

next_cursorstring,null

The cursor of the next page; null when this is the last page.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/locations' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/locations', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/locations',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "locations": [
    {
      "id": "location_bfa88cf22cff5365bfa88cf22cff",
      "name": "Warsaw, Marszałkowska 1",
      "reference": "WAW-01",
      "organization_id": "organization_e76c2a2c00fe7837b9339f212b28",
      "address": "Marszałkowska 1",
      "city": "Warsaw",
      "postcode": "00-624",
      "country_code": "PL",
      "time_zone": "Europe/Warsaw",
      "latitude": 52.2297,
      "longitude": 21.0122,
      "active": true
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoxNzU4NDQ1MjAwMDAwLCJpIjoiYm9va2luZ18wMWEwYjRjNyJ9"
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Locations

Get a location

GET/locations/{id}

Returns one location the caller may see, by its id.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs locations:read (or all); a key without it is refused insufficient_scope.

Path parameters

idlocation idrequired

Response

okbooleanrequired

true.

locationobject

The location.

Its words

idlocation id

The record's id.

namestring

The record's name as people read it.

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

organization_idorganization id

The organization's id.

addressstring

The street address, as one line.

citystring

The city.

postcodestring

The postal code.

country_codestring

The country, ISO 3166-1 alpha-2.

time_zonestring

The location's time zone (an IANA name).

latitudenumber,null

The location's latitude; null when it is not geocoded.

longitudenumber,null

The location's longitude; null when it is not geocoded.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/locations/<location_id>' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/locations/<location_id>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/locations/<location_id>',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "location": {
    "id": "location_bfa88cf22cff5365bfa88cf22cff",
    "name": "Warsaw, Marszałkowska 1",
    "reference": "WAW-01",
    "organization_id": "organization_e76c2a2c00fe7837b9339f212b28",
    "address": "Marszałkowska 1",
    "city": "Warsaw",
    "postcode": "00-624",
    "country_code": "PL",
    "time_zone": "Europe/Warsaw",
    "latitude": 52.2297,
    "longitude": 21.0122,
    "active": true
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Locations

List what may be requested at a location

GET/locations/{id}/requests

Returns the requests the caller may raise at the location (POST /tickets takes one of their ids), each with its level: a location request is raised on the location, an asset request names one of its assets (GET /assets?location_id=…).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs locations:read (or all); a key without it is refused insufficient_scope.

Path parameters

idlocation idrequired

Response

okbooleanrequired

true.

requestsarray of objects

What may be requested at the location, by the person the key acts as: each request with its level (a location request is raised on the location, an asset request names one of its assets).

Each element

idrequest id

The record's id.

namestring

The record's name as people read it.

levelenum

What a request is raised on: the location itself, or one asset of it (asset_id on the create).

Values: location asset form

categorystring,null

The record's category, as the organization names it; null when none.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/locations/<location_id>/requests' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/locations/<location_id>/requests', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/locations/<location_id>/requests',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "requests": [
    {
      "id": "request_53029dd8f5e0dc0edb4c49e8f90d",
      "name": "Plumbing",
      "level": "asset",
      "category": "Plumbing"
    }
  ]
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Me

Get the caller

GET/me

Returns the person the key acts as: their id, name, email, title, seat and organization.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestring

Any live key: no scope is asked.

Response

okbooleanrequired

true.

userobject

The person.

Its words

iduser id

The record's id.

namestring

The record's name as people read it.

emailstring · email

The person's email address.

titlestring

The record's title: a ticket's description as one line, a page's heading.

seatenum

The user's seat: an operator works tickets, a requester raises them, an integration is a system acting through its keys (what GET /me answers for an integration's key; the people lists never carry one).

Values: operator requester integration

organization_idorganization id

The organization's id.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/me' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/me', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/me',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "user": {
    "id": "user_063659e14af21d2d8ebed169c27a",
    "name": "Anna Kowalska",
    "email": "anna.kowalska@example.com",
    "title": "Facility manager",
    "seat": "operator",
    "organization_id": "organization_e76c2a2c00fe7837b9339f212b28",
    "active": true
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Notifications

List notifications

GET/notifications

Returns the caller's notifications a page at a time (30 by default, 100 at most), by tab (all, mentions: what addressed the caller, mine: on their own records, watching: on the records they watch) and view (active, or the snoozed ones), newest first or unread first, with the counts beside them. Page on: send the reply's next_cursor as cursor while has_more is true.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs notifications:read (or all); a key without it is refused insufficient_scope.

Query parameters

tabenum

Which notifications: all, mentions, mine, watching.

Values: all mentions mine watching

viewenum

active notifications or the snoozed ones.

Values: active snoozed

sortenum

newest_first or unread_first.

Values: newest_first unread_first

limitinteger

How many rows to return at most (the row says its default and its ceiling).

cursorstring

Where the page starts: the next_cursor of the previous reply. Opaque; leave it out for the first page.

Response

okbooleanrequired

true.

itemsarray of objects

The page's notifications, newest first.

Each element

idnotification id

The record's id.

unreadboolean

Whether the notification is still unread.

created_atstring · date-time

When the record was created.

snooze_untilstring,null · date-time

Until when the notification is snoozed, null when it is not.

hrefstring,null · uri

The page in the app the record opens on.

countsobject

How many unread notifications wait, by tab (all, mentions, mine, watching), and how many are snoozed right now.

has_moreboolean

Whether a next page exists.

next_cursorstring,null

The cursor of the next page; null when this is the last page.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/notifications' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/notifications', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/notifications',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "items": [
    {
      "id": "notification_1d119fe8c432064608bb17a9d1dd",
      "unread": true,
      "created_at": "2026-09-18T09:12:00.000Z",
      "snooze_until": null,
      "href": "https://app.fam.example/tickets/ticket_3f9a1c7e2b4d5f60718293a4b5c6d7e8"
    }
  ],
  "counts": {
    "all": 12,
    "mentions": 4,
    "mine": 5,
    "watching": 3,
    "snoozed": 1
  },
  "has_more": true,
  "next_cursor": "eyJzIjoxNzU4NDQ1MjAwMDAwLCJpIjoiYm9va2luZ18wMWEwYjRjNyJ9"
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Notifications

Mark notifications read

POST/notifications/mark-read

Marks the notifications named read and returns how many changed.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs notifications:write (or all); a key without it is refused insufficient_scope.

Body application/json

notification_idsarray of notification idsrequired

The notifications' ids.

Response

okbooleanrequired

true.

changedinteger

How many notifications the write changed.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/notifications/mark-read' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"notification_ids":["<notification_id>"]}'

const res = await fetch('https://app.fam.services/api/v1/notifications/mark-read', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "notification_ids": [
      "<notification_id>"
    ]
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/notifications/mark-read',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "notification_ids": [
        "<notification_id>"
      ]
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "changed": 3
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Notifications

Mark notifications unread

POST/notifications/mark-unread

Marks the notifications named unread again and returns how many changed.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs notifications:write (or all); a key without it is refused insufficient_scope.

Body application/json

notification_idsarray of notification idsrequired

The notifications' ids.

Response

okbooleanrequired

true.

changedinteger

How many notifications the write changed.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/notifications/mark-unread' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"notification_ids":["<notification_id>"]}'

const res = await fetch('https://app.fam.services/api/v1/notifications/mark-unread', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "notification_ids": [
      "<notification_id>"
    ]
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/notifications/mark-unread',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "notification_ids": [
        "<notification_id>"
      ]
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "changed": 3
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Notifications

Mark notifications done

POST/notifications/mark-done

Marks the notifications named done: they leave the active view. Returns how many changed.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs notifications:write (or all); a key without it is refused insufficient_scope.

Body application/json

notification_idsarray of notification idsrequired

The notifications' ids.

Response

okbooleanrequired

true.

changedinteger

How many notifications the write changed.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/notifications/mark-done' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"notification_ids":["<notification_id>"]}'

const res = await fetch('https://app.fam.services/api/v1/notifications/mark-done', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "notification_ids": [
      "<notification_id>"
    ]
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/notifications/mark-done',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "notification_ids": [
        "<notification_id>"
      ]
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "changed": 3
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Notifications

Undo done

POST/notifications/undo-done

Brings done notifications back to the active view and returns how many changed.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs notifications:write (or all); a key without it is refused insufficient_scope.

Body application/json

notification_idsarray of notification idsrequired

The notifications' ids.

Response

okbooleanrequired

true.

changedinteger

How many notifications the write changed.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/notifications/undo-done' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"notification_ids":["<notification_id>"]}'

const res = await fetch('https://app.fam.services/api/v1/notifications/undo-done', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "notification_ids": [
      "<notification_id>"
    ]
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/notifications/undo-done',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "notification_ids": [
        "<notification_id>"
      ]
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "changed": 3
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Notifications

Snooze notifications

POST/notifications/snooze

Snoozes the notifications named until an instant (until); with until null or absent, unsnoozes them. Returns how many changed.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs notifications:write (or all); a key without it is refused insufficient_scope.

Body application/json

notification_idsarray of notification idsrequired

The notifications' ids.

untilstring,null · date-time

Snooze until this instant; null to unsnooze.

Response

okbooleanrequired

true.

changedinteger

How many notifications the write changed.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/notifications/snooze' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"notification_ids":["<notification_id>"]}'

const res = await fetch('https://app.fam.services/api/v1/notifications/snooze', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "notification_ids": [
      "<notification_id>"
    ]
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/notifications/snooze',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "notification_ids": [
        "<notification_id>"
      ]
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "changed": 3
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Notifications

Mark all read

POST/notifications/mark-all-read

Marks every notification of a tab read and returns how many changed.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs notifications:write (or all); a key without it is refused insufficient_scope.

Body application/json

tabenum

Which notifications: all, mentions, mine, watching.

Values: all mentions mine watching

Response

okbooleanrequired

true.

changedinteger

How many notifications the write changed.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/notifications/mark-all-read' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"tab":"all"}'

const res = await fetch('https://app.fam.services/api/v1/notifications/mark-all-read', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "tab": "all"
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/notifications/mark-all-read',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "tab": "all"
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "changed": 3
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Search

GET/search

Searches what the caller may see and returns the matches grouped by kind, the best first (5 per kind by default, limit up to 20): hub pages, organizations, people, locations, tickets (with planned tickets) and costs, a person, a location or a ticket as its own read answers it; type narrows to one kind. The text is a reference, a name or a few words (two characters at least). key:value tokens in it narrow the tickets (status:open, type:planned, priority:high), the costs (status:) and the people (admin:yes, online:yes); a kind that cannot honour a token is left out. The reply says which tokens it read (filters) and the text that remained (q_clean).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs search:read (or all); a key without it is refused insufficient_scope.

Query parameters

qstring

The search text: a number, a name, a few words.

typeenum

Which kind of record to search: all (the default), or one kind.

Values: all page organization user location ticket cost

limitinteger

How many rows to return at most (the row says its default and its ceiling).

Response

okbooleanrequired

true.

qstring

The search text: a number, a name, a few words.

q_cleanstring

The search text as the engine read it, its key:value tokens removed.

typeenum

Which kind of record to search: all (the default), or one kind.

Values: all page organization user location ticket cost

filtersobject

The key:value tokens the search text carried, by key (status, type, priority …).

resultsobject

The matches, one list per kind: pages, organizations, users, locations, tickets, costs.

Its words

pagesarray of objects

The matching hub pages and sections.

Each element

idpage id

The record's id.

titlestring

The record's title: a ticket's description as one line, a page's heading.

organizationsarray of objects

The matching organizations.

Each element

idorganization id

The record's id.

namestring

The record's name as people read it.

usersarray of objects

People, by name (a search: the matches). email is answered for the caller's own organization only.

Each element

iduser id

The record's id.

namestring

The record's name as people read it.

emailstring · email

The person's email address.

titlestring

The record's title: a ticket's description as one line, a page's heading.

seatenum

The user's seat: an operator works tickets, a requester raises them, an integration is a system acting through its keys (what GET /me answers for an integration's key; the people lists never carry one).

Values: operator requester integration

organization_idorganization id

The organization's id.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

locationsarray of objects

Locations, by organization and name (a search: the matches).

Each element

idlocation id

The record's id.

namestring

The record's name as people read it.

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

organization_idorganization id

The organization's id.

addressstring

The street address, as one line.

citystring

The city.

postcodestring

The postal code.

country_codestring

The country, ISO 3166-1 alpha-2.

time_zonestring

The location's time zone (an IANA name).

latitudenumber,null

The location's latitude; null when it is not geocoded.

longitudenumber,null

The location's longitude; null when it is not geocoded.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

ticketsarray of objects

Tickets and planned tickets, newest first (a search: the matches; on GET /tickets/search, costs among them).

Each element

idticket id or planned ticket id or cost id

The record's id.

kindenum

Which kind of record: on a ticket, whether it is a ticket, a planned_ticket or (among search matches) a cost; on a file's address, the record the file hangs off.

Values: ticket planned_ticket cost

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

titlestring

The record's title: a ticket's description as one line, a page's heading.

descriptionstring

The ticket's description.

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: new upcoming rejected not_scheduled in_progress scheduled on_hold canceled completed

prioritystring,null

The ticket's priority, as the organization names it; null when none is set.

categorystring,null

The record's category, as the organization names it; null when none.

location_idlocation id

The location's id.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

request_idrequest id

The request's id: what the ticket is raised for (GET /locations/{id}/requests).

requester_iduser id

The id of the person who raised the ticket.

assignee_typeenum

What the assignee is: an organization (anyone of theirs may act), one user, or a team (a named group of people).

Values: organization team user

assignee_idany id

The assignee's id: an organization's, a team's or a person's, as assignee_type says.

field_operator_iduser id

The id of the field operator (the person doing the work on site).

scheduled_atstring,null · date-time

When the visit is scheduled; null until it is.

completed_atstring,null · date-time

When the work was completed; null until it is.

created_atstring · date-time

When the record was created.

updated_atstring · date-time

When the record last changed.

hrefstring,null · uri

The page in the app the record opens on.

costsarray of objects

The matching costs and cost proposals.

Each element

idcost id

The record's id.

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

titlestring

The record's title: a ticket's description as one line, a page's heading.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/search' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/search', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/search',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "q": "roof",
  "q_clean": "roof",
  "type": "all",
  "filters": {},
  "results": {
    "pages": [
      {
        "id": "page_fd8aaa19314e6e5d75022291b9c6",
        "title": "How to report a leak"
      }
    ],
    "organizations": [
      {
        "id": "organization_e76c2a2c00fe7837b9339f212b28",
        "name": "Roast n' Toast"
      }
    ],
    "users": [
      {
        "id": "user_063659e14af21d2d8ebed169c27a",
        "name": "Anna Kowalska",
        "email": "anna.kowalska@example.com",
        "title": "Facility manager",
        "seat": "operator",
        "organization_id": "organization_e76c2a2c00fe7837b9339f212b28",
        "active": true
      }
    ],
    "locations": [
      {
        "id": "location_bfa88cf22cff5365bfa88cf22cff",
        "name": "Warsaw, Marszałkowska 1",
        "reference": "WAW-01",
        "organization_id": "organization_e76c2a2c00fe7837b9339f212b28",
        "address": "Marszałkowska 1",
        "city": "Warsaw",
        "postcode": "00-624",
        "country_code": "PL",
        "time_zone": "Europe/Warsaw",
        "latitude": 52.2297,
        "longitude": 21.0122,
        "active": true
      }
    ],
    "tickets": [
      {
        "id": "ticket_3108be4ef78579c8760ebf45b188",
        "kind": "ticket",
        "reference": "RNT-37",
        "title": "Leak under the sink, kitchen 2",
        "description": "Leak under the sink in kitchen 2; water on the floor since this morning.",
        "status": "new",
        "priority": "High",
        "category": "Plumbing",
        "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
        "asset_id": "asset_ca15f1c8f67d6a0abb4946917dcc",
        "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
        "request_id": "request_53029dd8f5e0dc0edb4c49e8f90d",
        "requester_id": "user_063659e14af21d2d8ebed169c27a",
        "assignee_type": "user",
        "assignee_id": "ticket_3108be4ef78579c8760ebf45b188",
        "field_operator_id": "user_063659e14af21d2d8ebed169c27a",
        "scheduled_at": "2026-09-22T07:00:00.000Z",
        "completed_at": null,
        "created_at": "2026-09-18T09:12:00.000Z",
        "updated_at": "2026-09-18T11:40:00.000Z",
        "href": "https://app.fam.example/tickets/ticket_3f9a1c7e2b4d5f60718293a4b5c6d7e8"
      }
    ],
    "costs": [
      {
        "id": "cost_24f8d50960bc914dac705d81e834",
        "reference": "RNT-37-1",
        "title": "Replace the tap"
      }
    ]
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

Update a ticket

PATCH/tickets/{id}

Changes one or more of a ticket's attributes: its description, its finance references (the purchase order, the invoice and its date, the cost center, the nominal code) and an organization's own reference for it (requestor_internal_id by the requesting organization, assignee_internal_id by the assigned one). Words not sent are left as they are; a word the ticket does not have is refused (invalid_body, the reason unknown_field), an empty body too (no_fields); the reply names what changed (updated). On a planned ticket, visit_id aims a finance reference at one visit and apply_all at every visit.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:write (or all); a key without it is refused insufficient_scope.

Path parameters

idticket id or planned ticket idrequired

Body application/json

At least one of each: description or purchase_order or invoice or cost_center or nominal_code or invoice_date or requestor_internal_id or assignee_internal_id.

descriptionstring

The ticket's description.

purchase_orderstring

The purchase order the organization keys this ticket by.

invoicestring

The invoice reference.

cost_centerstring

The cost center the ticket is booked to.

nominal_codestring

The nominal (ledger) code.

invoice_datestring · date

The invoice's date.

requestor_internal_idstring

The requesting organization's own reference for the record.

assignee_internal_idstring

The assigned organization's own reference for the record.

visit_idvisit id

The id of one visit of a planned ticket.

apply_allboolean

On a planned ticket, whether to apply the reference to every visit rather than only the one named.

Response

okbooleanrequired

true.

idticket id or planned ticket id

The record's id.

membershipenum

Whether the ticket left or joined the list the caller is looking at (left | joined), when the action changed it.

Values: left joined

alert_textstring

The sentence to show for what happened, in the caller's language.

updatedarray of strings

The attributes the write changed, by name.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X PATCH \
  'https://app.fam.services/api/v1/tickets/<ticket_id>' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"description":"Leak under the sink in kitchen 2; water on the floor since this morning."}'

const res = await fetch('https://app.fam.services/api/v1/tickets/<ticket_id>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "description": "Leak under the sink in kitchen 2; water on the floor since this morning."
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.patch(
    'https://app.fam.services/api/v1/tickets/<ticket_id>',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "description": "Leak under the sink in kitchen 2; water on the floor since this morning."
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "id": "ticket_3108be4ef78579c8760ebf45b188",
  "membership": "joined",
  "alert_text": "Anna and 2 others were reminded.",
  "updated": [
    "description"
  ]
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

Get a ticket

GET/tickets/{id}

Returns one ticket or planned ticket the caller may see, by its id.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:read (or all); a key without it is refused insufficient_scope.

Path parameters

idticket id or planned ticket idrequired

Response

okbooleanrequired

true.

ticketobject

The ticket.

Its words

idticket id or planned ticket id or cost id

The record's id.

kindenum

Which kind of record: on a ticket, whether it is a ticket, a planned_ticket or (among search matches) a cost; on a file's address, the record the file hangs off.

Values: ticket planned_ticket cost

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

titlestring

The record's title: a ticket's description as one line, a page's heading.

descriptionstring

The ticket's description.

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: new upcoming rejected not_scheduled in_progress scheduled on_hold canceled completed

prioritystring,null

The ticket's priority, as the organization names it; null when none is set.

categorystring,null

The record's category, as the organization names it; null when none.

location_idlocation id

The location's id.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

request_idrequest id

The request's id: what the ticket is raised for (GET /locations/{id}/requests).

requester_iduser id

The id of the person who raised the ticket.

assignee_typeenum

What the assignee is: an organization (anyone of theirs may act), one user, or a team (a named group of people).

Values: organization team user

assignee_idany id

The assignee's id: an organization's, a team's or a person's, as assignee_type says.

field_operator_iduser id

The id of the field operator (the person doing the work on site).

scheduled_atstring,null · date-time

When the visit is scheduled; null until it is.

completed_atstring,null · date-time

When the work was completed; null until it is.

created_atstring · date-time

When the record was created.

updated_atstring · date-time

When the record last changed.

hrefstring,null · uri

The page in the app the record opens on.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/tickets/<ticket_id>' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/tickets/<ticket_id>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/tickets/<ticket_id>',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "ticket": {
    "id": "ticket_3108be4ef78579c8760ebf45b188",
    "kind": "ticket",
    "reference": "RNT-37",
    "title": "Leak under the sink, kitchen 2",
    "description": "Leak under the sink in kitchen 2; water on the floor since this morning.",
    "status": "new",
    "priority": "High",
    "category": "Plumbing",
    "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
    "asset_id": "asset_ca15f1c8f67d6a0abb4946917dcc",
    "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
    "request_id": "request_53029dd8f5e0dc0edb4c49e8f90d",
    "requester_id": "user_063659e14af21d2d8ebed169c27a",
    "assignee_type": "user",
    "assignee_id": "ticket_3108be4ef78579c8760ebf45b188",
    "field_operator_id": "user_063659e14af21d2d8ebed169c27a",
    "scheduled_at": "2026-09-22T07:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-09-18T09:12:00.000Z",
    "updated_at": "2026-09-18T11:40:00.000Z",
    "href": "https://app.fam.example/tickets/ticket_3f9a1c7e2b4d5f60718293a4b5c6d7e8"
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

Create a comment

POST/tickets/{id}/comments

Writes a comment on a ticket (or on one visit of a planned ticket, visit_id), with files (attachments, as attachment_type says) and @-mentions in the text, in reply to another comment (reply_to_id) or asking a person for feedback (awaiting_feedback_id). An operator (never a requester) may ride an action beside it: a new status (status_id, with the completion_date it sets, or one completion_date_suggested for the requester to confirm), a schedule_date, an assignee_id (a person) or a field_operator_id. A comment with no text, no file and no action is refused (comment_required).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:write (or all); a key without it is refused insufficient_scope.

Path parameters

idticket id or planned ticket idrequired

Body application/json

commentstringrequired

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

reply_to_idany id

The id of the comment this one replies to.

attachmentsarray of file ids

The files to attach: the ids of files uploaded through POST /files, each spent by the write that names it (a spent or unknown id is refused, file_not_found).

attachment_typeenum

What the files are: worksheet, certificate, purchase_order_attachment, invoice_attachment, or empty for plain attachments.

Values: "" worksheet certificate purchase_order_attachment invoice_attachment

awaiting_feedback_iduser id

The id of the person whose feedback the ticket now waits on.

status_idstatus id

The id of the status to set (one of the organization's statuses).

completion_datestring · local-date-time

When the work was completed, as the comment states it: local wall-clock time in the location's zone, YYYY-MM-DD HH:mm.

completion_date_suggestedstring · local-date-time

A completion date proposed for confirmation rather than set, the same way.

schedule_datestring · local-date-time

When the visit is scheduled: local wall-clock time in the location's zone, YYYY-MM-DD HH:mm.

assignee_idany id

The assignee's id: an organization's, a team's or a person's, as assignee_type says.

field_operator_iduser id

The id of the field operator (the person doing the work on site).

visit_idvisit id

The id of one visit of a planned ticket.

Response

okbooleanrequired

true.

idticket id or planned ticket id

The record's id.

membershipenum

Whether the ticket left or joined the list the caller is looking at (left | joined), when the action changed it.

Values: left joined

alert_textstring

The sentence to show for what happened, in the caller's language.

Errors

This endpoint's own error words:

comment_required400

The comment's text is empty.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/tickets/<ticket_id>/comments' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"comment":"On my way, there by 14:00."}'

const res = await fetch('https://app.fam.services/api/v1/tickets/<ticket_id>/comments', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "comment": "On my way, there by 14:00."
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/tickets/<ticket_id>/comments',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "comment": "On my way, there by 14:00."
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "id": "ticket_3108be4ef78579c8760ebf45b188",
  "membership": "joined",
  "alert_text": "Anna and 2 others were reminded."
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

List a ticket's attachments

GET/tickets/{id}/attachments

Returns every file posted on a ticket's timeline (or on one visit of a planned ticket, visit_id), newest entry first: each with its stored name (file_name), its name, its size, who posted it and when, whether the caller may delete it (an admin, the person who posted it, or the grant to edit attachments), plus the address (s3) a signed URL for its bytes is asked with and, for a caller who may confirm documents, the labels of the document types. A ticket with no files answers 404 no_attachments.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:read (or all); a key without it is refused insufficient_scope.

Path parameters

idticket id or planned ticket idrequired

Query parameters

visit_idvisit id

The id of one visit of a planned ticket.

Response

okbooleanrequired

true.

attachmentsarray of objects

The files posted: each with its stored name (file_name, what a signed URL is asked with), its name, its size and the timeline entry it was posted in.

Each element

file_namestring

The file's stored name, as an attachment reply hands it out.

namestring

The record's name as people read it.

bytesinteger

The file's size in bytes.

captionstring

The line under the file: who posted it, when.

entry_idany id

The timeline entry's id.

can_editboolean

Whether the caller may delete the file.

s3object

Where the files' bytes are: the address a signed URL is asked with (kind, record_id, location_id).

Its words

kindenum

Which kind of record: on a ticket, whether it is a ticket, a planned_ticket or (among search matches) a cost; on a file's address, the record the file hangs off.

Values: page ticket planned_ticket cost cost_proposal recurrence asset area_connection location connection time_off_request

record_idany id

The id of the record the attachment hangs off (a ticket, a cost, an asset, a location …); kind says which family.

location_idlocation id

The location's id.

doc_labelsobject,null

The labels of the document types (worksheet, certificate, purchase_order_attachment, invoice_attachment) in the caller's language; null when the caller may not confirm them.

Errors

This endpoint's own error words:

no_attachments404

The record has no attachments.

purged410

The attachments were purged: the record's files are no longer retained.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/tickets/<ticket_id>/attachments' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/tickets/<ticket_id>/attachments', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/tickets/<ticket_id>/attachments',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "attachments": [
    {
      "file_name": "a1b2c3d4-roof-photo.jpg",
      "name": "Anna Kowalska",
      "bytes": 184320,
      "caption": "Anna Kowalska · 18 Sep 2026",
      "entry_id": "ticket_3108be4ef78579c8760ebf45b188",
      "can_edit": true
    }
  ],
  "s3": {
    "kind": "ticket",
    "record_id": "ticket_3108be4ef78579c8760ebf45b188",
    "location_id": "location_bfa88cf22cff5365bfa88cf22cff"
  },
  "doc_labels": {
    "worksheet": "Worksheet",
    "certificate": "Certificate",
    "purchase_order_attachment": "Purchase order",
    "invoice_attachment": "Invoice"
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

List mentionable people

GET/tickets/{id}/mentions

Returns who a comment on this ticket may @-mention: everyone who can post on it, minus the caller (the requester who raised it included), widened by a person the comment is about to name as its assignee (assignee_id with assignee_type) or field operator (field_operator_id) before that is saved. Two group rows come first when the ticket has them: A, the assigned organization, and T, everyone at the location.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:read (or all); a key without it is refused insufficient_scope.

Path parameters

idticket id or planned ticket idrequired

Query parameters

field_operator_iduser id

The id of the field operator (the person doing the work on site).

assignee_idany id

The assignee's id: an organization's, a team's or a person's, as assignee_type says.

assignee_typeenum

What the assignee is: an organization (anyone of theirs may act), one user, or a team (a named group of people).

Values: organization team user

Response

okbooleanrequired

true.

mentionsarray of objects

Who a comment on the ticket may @-mention: each person by id and name, plus T (everyone at the location) and A (the assigned organization) when the ticket has them; id is the person's id, or T / A.

Each element

idany

The record's id.

namestring

The record's name as people read it.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/tickets/<ticket_id>/mentions' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/tickets/<ticket_id>/mentions', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/tickets/<ticket_id>/mentions',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "mentions": [
    {
      "id": "T",
      "name": "Everyone at the location"
    }
  ]
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

Search tickets

GET/tickets/search

Returns the tickets, planned tickets and costs the caller may see that match a reference (RNT-37) or a few words of the description, the best matches first (12 by default, limit up to 50): a ticket as GET /tickets/{id} answers it, a cost with its id, reference and title. exclude leaves one record out (the one asking).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:read (or all); a key without it is refused insufficient_scope.

Query parameters

qstring

The search text: a number, a name, a few words.

excludeany

The id of a ticket to leave out of the results (the ticket asking).

limitinteger

How many rows to return at most (the row says its default and its ceiling).

Response

okbooleanrequired

true.

ticketsarray of objects

Tickets and planned tickets, newest first (a search: the matches; on GET /tickets/search, costs among them).

Each element

idticket id or planned ticket id or cost id

The record's id.

kindenum

Which kind of record: on a ticket, whether it is a ticket, a planned_ticket or (among search matches) a cost; on a file's address, the record the file hangs off.

Values: ticket planned_ticket cost

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

titlestring

The record's title: a ticket's description as one line, a page's heading.

descriptionstring

The ticket's description.

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: new upcoming rejected not_scheduled in_progress scheduled on_hold canceled completed

prioritystring,null

The ticket's priority, as the organization names it; null when none is set.

categorystring,null

The record's category, as the organization names it; null when none.

location_idlocation id

The location's id.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

request_idrequest id

The request's id: what the ticket is raised for (GET /locations/{id}/requests).

requester_iduser id

The id of the person who raised the ticket.

assignee_typeenum

What the assignee is: an organization (anyone of theirs may act), one user, or a team (a named group of people).

Values: organization team user

assignee_idany id

The assignee's id: an organization's, a team's or a person's, as assignee_type says.

field_operator_iduser id

The id of the field operator (the person doing the work on site).

scheduled_atstring,null · date-time

When the visit is scheduled; null until it is.

completed_atstring,null · date-time

When the work was completed; null until it is.

created_atstring · date-time

When the record was created.

updated_atstring · date-time

When the record last changed.

hrefstring,null · uri

The page in the app the record opens on.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/tickets/search' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/tickets/search', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/tickets/search',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "tickets": [
    {
      "id": "ticket_3108be4ef78579c8760ebf45b188",
      "kind": "ticket",
      "reference": "RNT-37",
      "title": "Leak under the sink, kitchen 2",
      "description": "Leak under the sink in kitchen 2; water on the floor since this morning.",
      "status": "new",
      "priority": "High",
      "category": "Plumbing",
      "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
      "asset_id": "asset_ca15f1c8f67d6a0abb4946917dcc",
      "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
      "request_id": "request_53029dd8f5e0dc0edb4c49e8f90d",
      "requester_id": "user_063659e14af21d2d8ebed169c27a",
      "assignee_type": "user",
      "assignee_id": "ticket_3108be4ef78579c8760ebf45b188",
      "field_operator_id": "user_063659e14af21d2d8ebed169c27a",
      "scheduled_at": "2026-09-22T07:00:00.000Z",
      "completed_at": null,
      "created_at": "2026-09-18T09:12:00.000Z",
      "updated_at": "2026-09-18T11:40:00.000Z",
      "href": "https://app.fam.example/tickets/ticket_3f9a1c7e2b4d5f60718293a4b5c6d7e8"
    }
  ]
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

Nudge a ticket

POST/tickets/{id}/nudge

Reminds up to 25 people who have access to the ticket that it waits on them, with a reason, and returns how many were reached (sent): the caller themself, people without access and fam. admins are left out. At most 20 nudges a minute per caller.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:write (or all); a key without it is refused insufficient_scope.

Path parameters

idticket id or planned ticket idrequired

Body application/json

user_idsarray of user idsrequired

The people's ids.

reasonenum

Why the people are nudged: input (their input is needed), review (something waits for their review), blocked (the work is blocked on them), fyi (for their information).

Values: input review blocked fyi

Response

okbooleanrequired

true.

sentinteger

How many people were nudged (or emailed).

alert_textstring

The sentence to show for what happened, in the caller's language.

Errors

This endpoint's own error words:

no_recipients400

No user_ids were named.

no_valid_recipients403

None of the people named may be nudged about this ticket (they are not in its audience).

too_many_recipients400

More people were named than a nudge may reach at once (25).

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/tickets/<ticket_id>/nudge' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"user_ids":["<user_id>"]}'

const res = await fetch('https://app.fam.services/api/v1/tickets/<ticket_id>/nudge', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "user_ids": [
      "<user_id>"
    ]
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/tickets/<ticket_id>/nudge',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "user_ids": [
        "<user_id>"
      ]
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "sent": 2,
  "alert_text": "Anna and 2 others were reminded."
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

List tickets

GET/tickets

Returns the tickets the caller may see, newest first (50 a page, limit up to 200; a planned ticket is read by its id). status keeps one state, location_id one location, requester_id one person's; updated_since keeps the ones changed at or after an instant, for a sync (keep the newest updated_at you saw and ask again).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:read (or all); a key without it is refused insufficient_scope.

Query parameters

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: new upcoming rejected not_scheduled in_progress scheduled on_hold canceled completed

location_idlocation id

The location's id.

requester_iduser id

The id of the person who raised the ticket.

updated_sincestring · date-time

Only records changed at or after this instant (for a sync: keep the newest updated_at you saw).

limitinteger

How many rows to return at most (the row says its default and its ceiling).

cursorstring

Where the page starts: the next_cursor of the previous reply. Opaque; leave it out for the first page.

Response

okbooleanrequired

true.

ticketsarray of objects

Tickets and planned tickets, newest first (a search: the matches; on GET /tickets/search, costs among them).

Each element

idticket id or planned ticket id or cost id

The record's id.

kindenum

Which kind of record: on a ticket, whether it is a ticket, a planned_ticket or (among search matches) a cost; on a file's address, the record the file hangs off.

Values: ticket planned_ticket cost

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

titlestring

The record's title: a ticket's description as one line, a page's heading.

descriptionstring

The ticket's description.

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: new upcoming rejected not_scheduled in_progress scheduled on_hold canceled completed

prioritystring,null

The ticket's priority, as the organization names it; null when none is set.

categorystring,null

The record's category, as the organization names it; null when none.

location_idlocation id

The location's id.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

request_idrequest id

The request's id: what the ticket is raised for (GET /locations/{id}/requests).

requester_iduser id

The id of the person who raised the ticket.

assignee_typeenum

What the assignee is: an organization (anyone of theirs may act), one user, or a team (a named group of people).

Values: organization team user

assignee_idany id

The assignee's id: an organization's, a team's or a person's, as assignee_type says.

field_operator_iduser id

The id of the field operator (the person doing the work on site).

scheduled_atstring,null · date-time

When the visit is scheduled; null until it is.

completed_atstring,null · date-time

When the work was completed; null until it is.

created_atstring · date-time

When the record was created.

updated_atstring · date-time

When the record last changed.

hrefstring,null · uri

The page in the app the record opens on.

has_moreboolean

Whether a next page exists.

next_cursorstring,null

The cursor of the next page; null when this is the last page.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/tickets' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/tickets', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/tickets',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "tickets": [
    {
      "id": "ticket_3108be4ef78579c8760ebf45b188",
      "kind": "ticket",
      "reference": "RNT-37",
      "title": "Leak under the sink, kitchen 2",
      "description": "Leak under the sink in kitchen 2; water on the floor since this morning.",
      "status": "new",
      "priority": "High",
      "category": "Plumbing",
      "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
      "asset_id": "asset_ca15f1c8f67d6a0abb4946917dcc",
      "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
      "request_id": "request_53029dd8f5e0dc0edb4c49e8f90d",
      "requester_id": "user_063659e14af21d2d8ebed169c27a",
      "assignee_type": "user",
      "assignee_id": "ticket_3108be4ef78579c8760ebf45b188",
      "field_operator_id": "user_063659e14af21d2d8ebed169c27a",
      "scheduled_at": "2026-09-22T07:00:00.000Z",
      "completed_at": null,
      "created_at": "2026-09-18T09:12:00.000Z",
      "updated_at": "2026-09-18T11:40:00.000Z",
      "href": "https://app.fam.example/tickets/ticket_3f9a1c7e2b4d5f60718293a4b5c6d7e8"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoxNzU4NDQ1MjAwMDAwLCJpIjoiYm9va2luZ18wMWEwYjRjNyJ9"
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Tickets

Create a ticket

POST/tickets

Raises a ticket at a location (location_id) for one of its requests (request_id; GET /locations/{id}/requests lists what the caller may raise there): an asset request names the asset (asset_id), any request may name the area (area_connection_id). The description, a priority the caller may pick (priority_id), an emergency confirmation and files (attachments, uploaded through POST /files) ride beside. The ticket is routed, assigned and given its SLA the way the app does it; the reply is the ticket as GET /tickets/{id} answers it.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs tickets:write (or all); a key without it is refused insufficient_scope.

Body application/json

location_idlocation idrequired

The location's id.

request_idrequest idrequired

The request's id: what the ticket is raised for (GET /locations/{id}/requests).

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

descriptionstring

The ticket's description.

priority_idpriority id

The id of the priority to set, when the caller may pick one; the request's default otherwise.

emergencyboolean

Whether the caller confirms an emergency: when the request's priority is flagged as one, true raises the ticket as an emergency (its callout), false (the default) keeps the priority without the flag.

attachmentsarray of file ids

The files to attach: the ids of files uploaded through POST /files, each spent by the write that names it (a spent or unknown id is refused, file_not_found).

Response

okbooleanrequired

true.

idticket id

The record's id.

ticketobject

The ticket.

Its words

idticket id or planned ticket id or cost id

The record's id.

kindenum

Which kind of record: on a ticket, whether it is a ticket, a planned_ticket or (among search matches) a cost; on a file's address, the record the file hangs off.

Values: ticket planned_ticket cost

referencestring

The record's reference as people read it (RNT-37, RNT-37-1; an organization's own reference for a location or an asset).

titlestring

The record's title: a ticket's description as one line, a page's heading.

descriptionstring

The ticket's description.

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: new upcoming rejected not_scheduled in_progress scheduled on_hold canceled completed

prioritystring,null

The ticket's priority, as the organization names it; null when none is set.

categorystring,null

The record's category, as the organization names it; null when none.

location_idlocation id

The location's id.

asset_idasset id

The asset's id.

area_connection_idarea connection id

The id of the area at a location (an area connection).

request_idrequest id

The request's id: what the ticket is raised for (GET /locations/{id}/requests).

requester_iduser id

The id of the person who raised the ticket.

assignee_typeenum

What the assignee is: an organization (anyone of theirs may act), one user, or a team (a named group of people).

Values: organization team user

assignee_idany id

The assignee's id: an organization's, a team's or a person's, as assignee_type says.

field_operator_iduser id

The id of the field operator (the person doing the work on site).

scheduled_atstring,null · date-time

When the visit is scheduled; null until it is.

completed_atstring,null · date-time

When the work was completed; null until it is.

created_atstring · date-time

When the record was created.

updated_atstring · date-time

When the record last changed.

hrefstring,null · uri

The page in the app the record opens on.

Errors

This endpoint's own error words:

no_assignment409

Nothing at the location answers that request for the caller: no active assignment matches the request (and the asset, for an asset request), or the caller may not raise it there.

asset_required400

The request is raised on an asset (level: asset) and none was named: send asset_id.

asset_no_category409

The asset has no category, so no request can be routed by it.

floor_inactive409

The area named is on a floor that is no longer available.

checklist_required409

The request asks for a checklist to be answered when the ticket is raised, which the API does not take: raise it in the app.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/tickets' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"location_id":"<location_id>","request_id":"<request_id>"}'

const res = await fetch('https://app.fam.services/api/v1/tickets', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "location_id": "<location_id>",
    "request_id": "<request_id>"
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/tickets',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "location_id": "<location_id>",
      "request_id": "<request_id>"
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "id": "ticket_3108be4ef78579c8760ebf45b188",
  "ticket": {
    "id": "ticket_3108be4ef78579c8760ebf45b188",
    "kind": "ticket",
    "reference": "RNT-37",
    "title": "Leak under the sink, kitchen 2",
    "description": "Leak under the sink in kitchen 2; water on the floor since this morning.",
    "status": "new",
    "priority": "High",
    "category": "Plumbing",
    "location_id": "location_bfa88cf22cff5365bfa88cf22cff",
    "asset_id": "asset_ca15f1c8f67d6a0abb4946917dcc",
    "area_connection_id": "area_connection_cde4d183f90d8eacaab56447ec6c",
    "request_id": "request_53029dd8f5e0dc0edb4c49e8f90d",
    "requester_id": "user_063659e14af21d2d8ebed169c27a",
    "assignee_type": "user",
    "assignee_id": "ticket_3108be4ef78579c8760ebf45b188",
    "field_operator_id": "user_063659e14af21d2d8ebed169c27a",
    "scheduled_at": "2026-09-22T07:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-09-18T09:12:00.000Z",
    "updated_at": "2026-09-18T11:40:00.000Z",
    "href": "https://app.fam.example/tickets/ticket_3f9a1c7e2b4d5f60718293a4b5c6d7e8"
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Time off

Create a time-off request

POST/time-off/requests

Requests time off of one type for the caller: the days from … to, or on one day a half (part) or hours (from_min, to_min) when the type allows it, with a comment and proof (attachments) when the type asks for them and who covers (substitute_id). A request that needs no approver, or is short enough for the policy's automatic approval, is approved at once (auto); otherwise it is pending. Refused as invalid_field with the reason: note_required, document_required, nothing (no working day in the span), overlap, notice (asked too late), max_run, per_year, insufficient.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs time_off:write (or all); a key without it is refused insufficient_scope.

Body application/json

time_off_type_idtime off type idrequired

The id of the time-off type (one of the organization's types).

fromstring · daterequired

The first day of the span, YYYY-MM-DD.

tostring · daterequired

The last day of the span, YYYY-MM-DD.

partenum

For a half-day request: the morning (am) or the afternoon (pm).

Values: am pm

from_mininteger

For an hours request: the start, in minutes from midnight.

to_mininteger

For an hours request: the end, in minutes from midnight.

substitute_iduser id

The id of who covers while away.

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

attachmentsarray of file ids

The files to attach: the ids of files uploaded through POST /files, each spent by the write that names it (a spent or unknown id is refused, file_not_found).

Response

okbooleanrequired

true.

idtime off request id

The record's id.

statusenum

The record's status. A ticket's is its state (new, in_progress, on_hold, completed, canceled, rejected; a planned ticket's upcoming, scheduled, not_scheduled). A time-off request's is pending until an approver decides, then approved or rejected; cancelled when the person took it back.

Values: pending approved rejected cancelled

autoboolean

Whether the request was approved on its own (no approver needed).

countednumber

How many days the request counts against the allowance (a half day counts 0.5).

Errors

This endpoint's own error words:

no_country409

The person has no country set, so no holidays and no time-off policy apply to them yet.

no_policy409

No time-off policy of the organization covers the person for this type.

no_approver409

Nobody is in place to approve: the request needs an approver and the organization has not named one for the person.

no_bucket409

The organization has no file storage set up, so attachments cannot be posted.

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/time-off/requests' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"time_off_type_id":"<time_off_type_id>","from":"2026-09-21","to":"2026-09-25"}'

const res = await fetch('https://app.fam.services/api/v1/time-off/requests', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "time_off_type_id": "<time_off_type_id>",
    "from": "2026-09-21",
    "to": "2026-09-25"
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/time-off/requests',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "time_off_type_id": "<time_off_type_id>",
      "from": "2026-09-21",
      "to": "2026-09-25"
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "id": "time_off_request_31a4d5fa74118074085964c701a0",
  "status": "pending",
  "auto": false,
  "counted": 3
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Time off

Cancel a time-off request

DELETE/time-off/requests/{id}

Cancels a time-off request of the caller's own, pending or approved, as long as it has not started. The days return to the allowance (returned). A request already cancelled changes nothing (already); one rejected, or already started, is refused (invalid_state, the reason decided or started).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs time_off:write (or all); a key without it is refused insufficient_scope.

Path parameters

idtime off request idrequired

Response

okbooleanrequired

true.

alreadyboolean

Whether nothing changed because the record was already in that state.

returnednumber

The days returned to the allowance by the cancellation.

Errors

This endpoint's own error words:

invalid_state409

The request is not in a state this operation may change: reason says which (decided, started).

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X DELETE \
  'https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.delete(
    'https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "already": false,
  "returned": 3
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Time off

Approve a time-off request

POST/time-off/requests/{id}/approve

Approves a pending time-off request the caller may decide (an admin of the organization, or the person's approver), with a comment for the person when there is one. A request no longer pending changes nothing (already).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs time_off:write (or all); a key without it is refused insufficient_scope.

Path parameters

idtime off request idrequired

Body application/json

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

Response

okbooleanrequired

true.

alreadyboolean

Whether nothing changed because the record was already in that state.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>/approve' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"comment":"On my way, there by 14:00."}'

const res = await fetch('https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>/approve', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "comment": "On my way, there by 14:00."
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>/approve',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "comment": "On my way, there by 14:00."
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "already": false
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Time off

Reject a time-off request

POST/time-off/requests/{id}/reject

Rejects a pending time-off request the caller may decide (an admin of the organization, or the person's approver), with a comment that tells the person why. A request no longer pending changes nothing (already).

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs time_off:write (or all); a key without it is refused insufficient_scope.

Path parameters

idtime off request idrequired

Body application/json

commentstring

The comment's text. A mention is [@<user_id>@]@<name>[/] in the text (T for everyone at the location, A for the assigned organization); GET /tickets/{id}/mentions lists who may be named.

Response

okbooleanrequired

true.

alreadyboolean

Whether nothing changed because the record was already in that state.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight. This write takes Idempotency-Key.

Request

curl -X POST \
  'https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>/reject' \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{"comment":"On my way, there by 14:00."}'

const res = await fetch('https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>/reject', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "comment": "On my way, there by 14:00."
  }),
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.post(
    'https://app.fam.services/api/v1/time-off/requests/<time_off_request_id>/reject',
    headers={'Authorization': 'Bearer <api key>'},
    json={
      "comment": "On my way, there by 14:00."
    },
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "already": false
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Time off

Get the day grid

GET/time-off/days

Returns the caller's day grid for a span: each day by date with its state (open, past, off, closed, shut), the label of what closes or holds it, and what is already held on an open day (taken: a half, or hours). Empty when the person has no country on their employment, so no policy applies.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs time_off:read (or all); a key without it is refused insufficient_scope.

Query parameters

fromstring · daterequired

The first day of the span, YYYY-MM-DD.

tostring · daterequired

The last day of the span, YYYY-MM-DD.

Response

okbooleanrequired

true.

daysobject

Each day of the span by date (YYYY-MM-DD): its state and, when something is held on it, what.

Its words

stateenum

The day's state: open (may be requested), past, off (a whole day already held), closed (a holiday or a closure the organization set), shut (a weekend).

Values: open past off closed shut

labelstring

The label, in the caller's language.

takenany

What is already held on an open day: am or pm when a half day is, or the hour windows ([{ from_min, to_min }]) when hours are.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/time-off/days?from=2026-09-21&to=2026-09-25' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/time-off/days?from=2026-09-21&to=2026-09-25', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/time-off/days?from=2026-09-21&to=2026-09-25',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "days": {
    "2026-09-21": {
      "state": "open",
      "label": "Annual leave",
      "taken": "am"
    }
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Users

List people

GET/users

Returns the people the caller may see, by name (50 a page, limit up to 200): their own organization's and, for an operator, the organizations connected to it; q keeps the ones whose name or email matches. email is answered for the caller's own organization only.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs users:read (or all); a key without it is refused insufficient_scope.

Query parameters

qstring

The search text: a number, a name, a few words.

limitinteger

How many rows to return at most (the row says its default and its ceiling).

cursorstring

Where the page starts: the next_cursor of the previous reply. Opaque; leave it out for the first page.

Response

okbooleanrequired

true.

usersarray of objects

People, by name (a search: the matches). email is answered for the caller's own organization only.

Each element

iduser id

The record's id.

namestring

The record's name as people read it.

emailstring · email

The person's email address.

titlestring

The record's title: a ticket's description as one line, a page's heading.

seatenum

The user's seat: an operator works tickets, a requester raises them, an integration is a system acting through its keys (what GET /me answers for an integration's key; the people lists never carry one).

Values: operator requester integration

organization_idorganization id

The organization's id.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

has_moreboolean

Whether a next page exists.

next_cursorstring,null

The cursor of the next page; null when this is the last page.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/users' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/users', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/users',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "users": [
    {
      "id": "user_063659e14af21d2d8ebed169c27a",
      "name": "Anna Kowalska",
      "email": "anna.kowalska@example.com",
      "title": "Facility manager",
      "seat": "operator",
      "organization_id": "organization_e76c2a2c00fe7837b9339f212b28",
      "active": true
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoxNzU4NDQ1MjAwMDAwLCJpIjoiYm9va2luZ18wMWEwYjRjNyJ9"
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

Users

Get a person

GET/users/{id}

Returns one person the caller may see, by their id.

Authorization

Authorizationstringrequired

Bearer fam_…, a key minted on Console › API. It acts as its owner (a person, or an integration) and carries scopes; the operation names the scope it wants.

scopestringrequired

The key needs users:read (or all); a key without it is refused insufficient_scope.

Path parameters

iduser idrequired

Response

okbooleanrequired

true.

userobject

The person.

Its words

iduser id

The record's id.

namestring

The record's name as people read it.

emailstring · email

The person's email address.

titlestring

The record's title: a ticket's description as one line, a page's heading.

seatenum

The user's seat: an operator works tickets, a requester raises them, an integration is a system acting through its keys (what GET /me answers for an integration's key; the people lists never carry one).

Values: operator requester integration

organization_idorganization id

The organization's id.

activeboolean

Whether the record is live: a location that is open, an asset in service, a person with a live seat, an endpoint that receives events.

Errors

Every endpoint may also answer the doors' refusals: not_signed_in api_key_invalid api_key_expired insufficient_scope forbidden not_found invalid_field invalid_body missing_field plan_required rate_limited idempotency_key_reused idempotency_in_flight.

Request

curl -X GET \
  'https://app.fam.services/api/v1/users/<user_id>' \
  -H 'Authorization: Bearer <api key>'

const res = await fetch('https://app.fam.services/api/v1/users/<user_id>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <api key>',
  },
});
const data = await res.json();   // { ok: true, … } or { ok: false, error, field, alert_text }

import requests

res = requests.get(
    'https://app.fam.services/api/v1/users/<user_id>',
    headers={'Authorization': 'Bearer <api key>'},
)
data = res.json()   # {'ok': True, …} or {'ok': False, 'error': …}

Response

{
  "ok": true,
  "user": {
    "id": "user_063659e14af21d2d8ebed169c27a",
    "name": "Anna Kowalska",
    "email": "anna.kowalska@example.com",
    "title": "Facility manager",
    "seat": "operator",
    "organization_id": "organization_e76c2a2c00fe7837b9339f212b28",
    "active": true
  }
}

{
  "ok": false,
  "error": "too_soon",
  "message": "The window starts sooner than the type allows.",
  "doc_url": "…/developers#errors:param-too_soon",
  "call_id": "call_5f0c3a9e2b7d4c1e8a6f0b3d",
  "param": "start_at"
}

The fam. API

Three steps

Resources

Authentication

Header

Whose key

Scopes

The words

Schemes

Envelope

2xx Done

4xx Refused

Headers on every reply

Errors

Every endpoint may answer

An endpoint's own

Ids

The kinds this document uses

Pagination

A list

Time

Rate limits

The headers

More

When you hit it

Idempotency

The rule

Versioning

The rule

Changelog

Webhooks

A delivery

The signature

Events

SDKs and tools

Clients

Assets

Endpoints

Attachments

Endpoints

Bookings

Endpoints

Comments

Endpoints

Files

Endpoints

Locations

Endpoints

Me

Endpoints

Notifications

Endpoints

Search

Endpoints

Tickets

Endpoints

Time off

Endpoints

Users

Endpoints

List assets

Authorization

Query parameters

Response 2004xx

Errors

Get an asset

Authorization

Path parameters

Response 2004xx

Errors

Get a signed URL

Authorization

Query parameters

Response 2004xx

Errors

Create a booking

Authorization

Body application/json

Response 2004xx

Errors

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response