Referencia de la API

Every phone this key can reach. Paginated: pass next_cursor back as ?cursor= until it comes back null. A phone no relay reports any more is left out, so this page is the list the dashboard shows rather than a count of everything the agency is billed for: GET /agency reports that one as phones_held, and reachable_devices on GET /usage still sizes your budget by it. GET /devices/{id} still reads one, so an id you already hold resolves, but every action on it answers device_unprovisioned until a relay reports the handset again.

The two labels a customer owns: what the phone is called, and the sticker on the back of the handset. The sticker is unique across the fleet, which is what lets it be used in place of a public_id anywhere a device is named. null clears it, and a clash is refused rather than quietly moved off the phone that had it. Needs devices.write and phones.edit on the account that created the key, which is the same pair the dashboard asks for before it shows the field. A key that drives handsets all day cannot rename them.

The current screen as a JPEG. Coordinates you read off this image are the ones to send to /actions; the API scales them to the device. Rate limited harder than actions: each capture costs the box a full frame and a transcode. For continuous frames, stream instead of polling.

Connect with wss://. The server sends a JSON ready frame, then the screen as binary JPEG frames, one per message.

→ {"type":"ready","device":"ph_…","screen":{"width":405,"height":720},"max_fps":2}
→ <binary JPEG>  …
→ {"type":"closing","reason":"max_duration","reconnect":true}
← {"type":"ping"}   → {"type":"pong","t":…}
← {"type":"ack"}    optional; lets the device pace to what you actually render

Frame rate is capped at 5/s, default 2. This is not the rate the ALI console runs at: a person driving a pointer needs every frame, an integration checking a screen between actions does not, and the frames are relayed through us rather than served from the device directly. Reconnect. Connections are closed at a duration ceiling and on any upstream interruption. A closing frame with reconnect: true precedes an expected close; reconnect with backoff. Limits. 10 concurrent streams per key, and every minute open costs 20 credits from the daily pool, charged a minute at a time and reported under stream_minutes in GET /usage. A device that is not casting is refused: send a recast action first.

A fresh public address, scored. Mobile data: an airplane-mode cycle. Proxy Wi-Fi: the router's link, which rotates every device on it, unscored. ALI Wi-Fi: 409 rotation_unavailable. Answers 202; poll GET on this path until status leaves running. One rotation per device at a time.

This device's rotations, newest first.

Perform one action. The body is a single object discriminated by type. Every response carries device_ack. 200 with device_ack: true means the device confirmed it accepted the command. 202 with device_ack: false means the command was handed over and the outcome could not be confirmed, because the hardware serving that phone is mid-update; verify with a snapshot. What `device_ack: true` is worth. It is the device saying it accepted the command. It is *not* a claim that the screen changed, and nothing can observe that for you. For a gesture it is worth noticeably less, and this document used to say the opposite. A tap either lands or is refused. A swipe, a drag, a swipe_direction, a scroll and the flick inside app_close are each a press, a walk and a release, and every one of those can be accepted in full while the screen does not move at all: the phone has one pointer, it is shared with whatever else is driving that handset, and how far a walk actually travels is decided by hardware we can ask but not watch. So every gesture answers effect_observed: false beside its acknowledgement, and that field is the honest one. Read the screen back with `GET /devices/{id}/snapshot` when a gesture matters, rather than treating a 200 as movement. For anything whose work continues after the call returns the acknowledgement is weaker still, and recast is the clear example: it answers device_ack: true in under a second while the phone may take another minute to come back, or never come back. One thing an ack cannot tell you is *where* a tap landed. It is uncommon, but some handsets occasionally place one away from where it was aimed, and an unattended run that carries on from the wrong screen is the expensive version of that. If you see it, send calibrate and repeat the tap. On a fleet where every box reports outcomes a 200 always carries device_ack: true. The field earns its place by being false on a 202, and by giving you one thing to branch on rather than two status codes to remember. An action against a phone that is not casting is refused with 503 device_offline rather than accepted. A phone that has stopped mirroring will still take a command and report success for work that never happened, so this endpoint checks first. Send recast, then retry. Some verbs need a helper that runs on the phone, and some do not. This is the single most useful thing to know about failures here. Taps, gestures, buttons, snapshots, calibrate and recast are driven through the handset's pointer and work on any phone that is casting. These verbs instead go through a small helper installed on the phone itself: text (beyond short plain ASCII, which goes over the keyboard), clipboard_get, clipboard_set, open_url, wifi, cellular, airplane, torch, brightness and device_ip. They are slower (several seconds is normal) and they can fail on a phone where everything else works. When the helper does not answer in time you get 409 device_not_provisioned_for_action. The name is misleading and we are stuck with it for now (it is a published code that clients branch on): it reports a *timeout*, not a provisioning state. Read it as "the helper did not answer", not as "this key lacks a permission" and not as "this phone needs enabling for this one verb". There is no per-verb provisioning, no scope that unlocks it, and nothing on the key-creation screen that affects it: a key with devices.control can already send every verb on this list. Tell the two cases apart by trying once more, a minute later: - It succeeds. The helper was busy, often with something else driving the same phone. Nothing is wrong. - It refuses again. Stop, and send us the X-Request-Id and the phone's inventory_id. Retrying will not clear it and nothing on your key affects it. Do not build a retry loop around this code. A phone whose helper is down answers the same way every time, and an unattended loop against a live account is exactly where this becomes expensive. Two attempts is the whole strategy. ⚠️ `open_url` has a first-run cost per phone and per destination, and this is worth understanding before you build on it. iOS asks the person holding the phone to approve each destination the first time that phone is asked to open it (*Allow "ALI Remote" to open "Instagram"?*). Until that prompt is answered the request simply waits, and at thirty seconds the box gives up and answers device_not_provisioned_for_action. Measured on a live handset: first call to a new destination 30 s, refused; once approved, the same call is about 2 s and stays that way. The approval is remembered per phone and per destination, so a phone that opens Instagram in two seconds will still spend thirty being refused the first time you ask it for TikTok. Boxes on current builds answer that prompt themselves, so the first open_url to a new destination just runs a few seconds longer than every later one. On a box that has not picked that up yet the first call is still refused at thirty seconds; if the same phone and link keep refusing, tell us both and we will approve it at the rack. In the meantime press home plus a tap read off a snapshot reaches any app on the home screen in about a second, with no first-run cost. A practical consequence worth planning for: because these verbs share one dependency, one of them failing predicts the rest. If you need to know whether a phone's helper is answering before you drive an account with it, send a clipboard_get first: it reads and changes nothing on the phone. It speaks for the helper, not for any one verb: open_url carries its per-destination approval on top, so a passing preflight promises the tier open_url runs on, not open_url itself. send_binding_key is not part of the control surface and is listed here only because the catalogue is generated from the schema that validates it. It is a one-time step in preparing a handset, performed by ALI staff while somebody is watching that phone: it answers 403 forbidden on any customer credential, whatever scopes that credential holds, because the check is against the account behind it rather than against the key. There is nothing to reach for here in any case, since everything it prepares a phone for already has a verb of its own (text, the clipboard pair, the radio switches). Swipes are one gesture, drawn the way a hand draws it. Every gesture here is the one the dashboard's arrows send: the finger is placed, pressed, rested, walked in sixteen steps and released at the end point, a little over half a second in all. swipe and drag take the finger from (x1,y1) to (x2,y2), and differ only in whether the content is allowed to keep moving afterwards. swipe_direction names where the finger goes: up drags from the bottom of the screen towards the top, which scrolls the content down. It runs from 80 % to 20 % of the axis by default, centred on the other one; distance shortens or lengthens that, as a fraction of the axis or as { "px": N } in snapshot pixels, always centred on the screen and never within 5 % of an edge; it needs the phone to have reported its screen size, and is refused rather than quietly drawn at the default page while it has not. scroll names where the view goes: it starts the finger at x,y and moves it against dy, so a positive dy scrolls down and a negative one scrolls up, by exactly that many snapshot pixels. Anchored close to an edge the whole line slides inwards rather than being cut short, so the finger always travels the full dy. A dy of 0 is refused rather than treated as a no-op: a finger that presses and lifts without travelling is a tap on whatever is under x,y. `precise` decides whether that line is drawn twice the same way. A hand does not scroll a phone from the same pixel at the same speed sixty times in a row, so a swipe we lay out ourselves is varied: the whole line sits 5 to 15 % off to one side of where it would have been (sideways for an up or down swipe, up or down for a sideways one), each end moves along the axis by 5 to 15 % of the travel, and the walk runs 5 to 15 % faster or slower. The shape does not change: same direction, same sixteen steps, both ends still at least 5 % clear of the edges iOS owns. Only where it is drawn, and how quickly. The default follows one rule: if you gave us the numbers we draw them, and if you only asked us for a page we draw it like a hand. So swipe, drag and scroll are exact, because their coordinates are yours and an icon has to land where you put it, and so is a swipe_direction carrying a distance, because that is a measurement you gave us and one we refuse to guess at without a screen. A swipe_direction with no distance names nothing but a direction, so the whole line is ours and it is varied. precise: true turns the variation off, precise: false turns it on, on any of the four. Varying a swipe is measured against the phone's screen size, so precise: false is refused with 503 device_offline on a phone that has not reported one yet, exactly as distance is; the default silently draws the box's own page instead, since that is a swipe drawn a little differently rather than one that did not happen. The dashboard varies every swipe it sends and offers no switch: nobody driving a phone by hand is trying to hit a coordinate. Deprecated: `duration_ms`, `span`, `steps`, `step_ms`, `stepping`, `step_sleep` and `brake`. These pacing and sizing knobs are still accepted on swipe, drag and swipe_direction for one release so existing scripts keep working, and they are ignored: every gesture takes the walk described above, which is the one that measurably lands, varied only as precise decides. They will be refused in the release after this one. Use distance on swipe_direction where span was used. calibrate puts the phone's pointer back in a known place. It is the one verb here that fixes a class of problem rather than doing something: a tap that lands off-target takes an unattended run somewhere it cannot recover from, and re-centring is the remedy. Send it when you see that happening, or once at the top of a sequence that will tap a lot. Not before every tap. It is a round trip of its own, about a second, and one action off the budget, so a tap-calibrate pair doubles both for a fault most handsets do not have. It changes nothing on screen, so a screenshot either side of it is identical, and it is one of only two verbs that work on a phone that is not casting. app_close force-closes the app in front, the way a person does it: it opens the App Switcher and flicks that app's card up off the screen. Open the app you mean first, then call it; it closes whatever is in front and does not choose, so do not send it from a screen you have not read. It takes no fields at all, and is the one verb here that refuses a body carrying any: {"type":"app_close","url":"instagram://"} comes back as invalid_action rather than being read as "close whatever is in front" and answered with a 200 for the wrong app. It is pointer-driven and does not use the on-device helper, so it works on any casting phone even where that helper is not answering, which is the point of it. You can do the same by hand with press appswitcher and then a swipe from the card up past the top of the screen, but the card you have to hit is not where most people assume: with more than one app open the front app's card is at the right of the switcher and the middle holds the app *before* it, so a flick up the centre line force-closes a bystander. app_close is that sequence done correctly. Both the switcher and lock ride a spare mouse button iOS binds to the system action rather than a keyboard combination, so they no longer depend on Full Keyboard Access being on, which it is not across the fleet. It takes a few seconds and it checks its own work: it reads the screen again before answering, so a 200 means the app that was in front is no longer the one showing. How firm that is depends on the app. The check is a comparison of the whole frame, so an app that is animating anyway - a video, an autoplaying feed, a spinner - satisfies it whether or not its card went, and on those a 200 is worth about what a gesture's is. On a still screen it is the real thing. Read the screen back with GET /devices/{id}/snapshot when the close matters and the app was moving. It still carries effect_observed: false like every other gesture, because "no longer in front" is what can be seen and "terminated" is not. It is refused rather than reported as closed in two cases, both arriving as command_rejected: a phone whose App Switcher has never been bound, where nothing was touched, and a close that ran and left the same app on screen. Neither is a retry, whatever the generic detail on that answer says: with more than one app open the first flick may already have thrown a different app's card, and sending it again throws another. Read the screen back with GET /devices/{id}/snapshot instead. recast re-establishes dropped screen mirroring and is the fix for a phone that is online but not casting. It is expensive: on a phone that is already casting the session is bounced, and the screen is gone while it reconnects. Budget up to two minutes and poll casting rather than assuming a fixed wait; 15 to 30 seconds is the good case and 75 seconds has been measured on a healthy phone. Never call it speculatively. It answers as soon as the request has been accepted, so a 200 here says the reconnect *started*. Poll GET /devices/{id} until casting is true before driving the phone, and treat a phone still dark after two minutes as needing a look rather than another recast. Retrying safely. Send an Idempotency-Key header, any string up to 255 characters, unique per action you intend to perform. A retry carrying the same key replays the first response instead of tapping the phone again, and comes back with Idempotent-Replay: true. Reusing a key for a different body is refused with idempotency_key_reused rather than answered from the cache, and a retry that arrives while the first is still running gets idempotency_in_flight. Keys are honoured for 24 hours and scoped to your API key. times sends a press more than once inside one request. If the sequence stops early, because a press failed or because the request ran out of time, repeated reports how many actually landed and only those are charged. On a failure the same count is in the error detail, so a retry can pick up where it stopped.

Whether the phone is free, held by a person, or held by an automation, and since when. The read that makes the rest of this section usable. Without it, the only way to learn a phone was busy was to be refused mid-run, which is late: a scheduler wants to skip a busy handset and come back to it, not fail a step halfway through a sequence and unwind what it already did. yours is true when this key is the holder, so a caller can tell somebody-else-has-it from I-have-it without comparing names.

Tells the dashboard a script has this phone, and what to call it. Anyone who opens the device sees the label and starts as a spectator. Every control call already takes a lease lasting about 30 seconds, so an integration that never calls this is still protected from somebody typing over it. Declare a session for the two things that lease cannot do: give the automation a name a person can act on, and hold the phone through the gaps when the script is thinking rather than tapping. It is not a lock. A person can take the phone deliberately, from a dialog naming this session, and the next control call then answers device_in_use, which is how the automation learns to stop instead of tapping into somebody's work. Release it when done; it also expires on its own.

Lets people back on immediately rather than when the lease lapses. A no-op if somebody has already taken the phone.

Take a phone that somebody else is currently driving. Control of a phone is a lease: one holder at a time, everybody else watches. Until this endpoint existed an automation that found a phone busy could only give up, and the commonest reason a phone is busy is a console somebody left open on a second monitor, which nothing will ever clear. What happens depends on who is holding it. - Nobody, or this same key. Taken straight away. - Another automation. Taken straight away. This mirrors the rule the dashboard already applies in the other direction, where a person may take a phone off a script without asking. - A person. They are asked. Their console shows the request and they have about three seconds to refuse; silence is a yes, which is what stops an open tab holding a phone all afternoon. This request blocks for those three seconds, so allow for it in your client timeout. - The account this key belongs to. Taken straight away, and nobody is asked. A credential is not somebody else, and asking would leave an automation stuck behind its own owner's open tab with no way through. This is the one case where asked is false and taken_from.kind is person. A refusal answers 409 device_in_use, and asking again immediately is refused for longer each time: five seconds, then fifteen, then a minute. The four refusals share that one code and are told apart by detail: a person who said no, a cooldown still running, somebody else already mid-ask, and an ask that did not settle. Treat any of them as a phone somebody needs and move on to another one. Who does the asking. The account that created the API key, so the dialog names a colleague rather than a credential nobody recognises. If that account has left the agency the request answers key_orphaned: mint a replacement key under somebody who is still there. It is not a lock in the other direction either. Whoever was taken off keeps watching and can take the phone straight back, at which point your next control call answers device_in_use. That is the signal to stop rather than to retry. Call GET /devices/{id}/control-session first if you would rather skip a busy phone than interrupt one.

Uploading is three steps, and the bytes never pass through the API: 1. POST /devices/{id}/media with the file's filename, mime and size_bytes → 201 with an upload_url. 2. PUT the raw bytes to upload_url before upload_expires_at (curl -X PUT --data-binary @photo.jpg "$upload_url"). If you set a Content-Type, it must be the one you declared. 3. POST /devices/{id}/media/{asset_id}/complete → 202. Storage is checked for what actually arrived, and the delivery to the phone is queued. The upload URL points directly at storage, which is what makes the 100 MB limit real: a body routed through the API itself would be capped at 4.5 MB by the platform, regardless of what this document promised. Delivery then runs on a queue: putting a file onto a physical handset takes minutes rather than milliseconds. Poll GET /devices/{id}/media/{asset_id} for the outcome, and read error_code beside error when it ends failed if you want something stable to branch on.

Call after PUTting the bytes to upload_url. The vault verifies what actually arrived: size and type against what was declared, then queues the delivery to the phone. Answers 202; poll GET /devices/{id}/media/{asset_id} for the outcome. Calling it again re-queues the delivery, so it doubles as the retry.

Remove a file this API put on the phone. Asynchronous, for the same reason the upload is: the work happens on the handset itself. Answers 202 with removing; poll GET on this path until removed. A removal is confirmed by reading the phone's album back afterwards, never by trusting the result of the delete itself. A removal that cannot be confirmed is reported as still delivered rather than quietly marked clean. Removing something already gone answers 404 not_found, which makes a repeat safe. A removal asked for while the file is still on its way to the phone answers command_rejected: wait for the delivery to settle first. One-time consent. The first removal on a handset can hang and fail until somebody answers Apple's "Delete Always" prompt on that phone once. Until then the file stays put, and the error says so rather than reporting a clean removal.

An automation is a flow of steps that drives phones on a schedule, on an event, or when you start one. Until now these scopes had nothing behind them over HTTP: the feature was reachable from the dashboard canvas and from an assistant, and a customer reading automations.read in the scope list was being shown a promise this API did not keep. These endpoints are the same store both of those call, so a flow built here is the flow the canvas draws and the scheduler runs. How a flow is built. 1. POST /automations for an empty one. It starts turned off and unpublished, so creating it can never start anything. 2. GET /automation-blocks for the steps that exist, with their settings and the ports their edges leave by. Do not guess these. 3. PATCH /automations/{id} with the whole graph. A draft is saved even when it is not yet valid, and the answer lists every problem at once rather than the first, so a flow can be built over several calls. 4. POST /automations/{id}/publish to make the draft the version that runs. This is the step that refuses a broken flow, which is what keeps a half-built automation off a schedule. 5. POST /automations/{id}/triggers to say when it should run, then PATCH with enabled: true. What a run reaches. A run acts with the standing of the account that created the API key, so it drives the phones that person drives and no others. Everything it does spends the same credits the same actions would over /devices. Watching one. Starting a run answers 202 and a run_id; it does not finish while you wait, because it drives physical phones. GET /automation-runs/{id} reports every step in order, which phone each acted on, and why any was skipped.

Creates an empty automation with a name. It starts turned off and unpublished, so nothing runs until you save steps with PATCH and then publish it. name is capped at 120 characters and description at 2000.

Its published steps, its unpublished draft if there is one, its triggers and its version history. Read this before changing a flow, so you edit what is actually there.

graph replaces the draft rather than merging into it, so send the whole flow; read GET /automation-blocks first. A draft is saved even when it is not yet valid. The answer carries draft.problems, every problem at once rather than the first, and publishable. Nothing saved here runs until you publish it. enabled: true is refused until something has been published, because a switch that reports on and does nothing is worse than a refusal.

Deletes it and everything it recorded: versions, triggers and run history. This cannot be undone. To stop it running, PATCH with enabled: false instead.

Makes the draft the version that runs. This is the step that checks the whole flow and refuses if anything is wrong, so a broken automation can never end up on a schedule. Runs already in progress keep the version they started with.

Newest first, with how each one ended.

Answers 202 with a run_id as soon as the run is created. It does not finish while you wait, because it drives physical phones: poll GET /automation-runs/{id}. The run acts with the standing of the account behind the key, so it reaches the phones that person reaches and no others.

manual for by hand only, schedule with a five-field cron such as 0 2 * * * read in the agency's timezone unless you name one, or event with an event_type for when a phone changes state. An automation with no trigger can still be started with POST /automations/{id}/runs.

Stops the automation being started that way. Its other triggers are left alone.

Every kind of step, with what it does, what settings it takes and which ports its edges may leave by. Read this before writing a graph: it is the only way to know what exists, and it is filtered to what this key's account is allowed to use, so a step listed here is one you may actually publish.

Across every automation, newest first. The one call that answers whether last night worked.

Every step in order, which phone each acted on, and why any was skipped or failed. This is what to read when somebody asks why an automation did not do what they expected.

Stops a run that is still going. It stops at its next step rather than mid-action, so a phone is never left half way through something. A run that has already finished answers not_found rather than pretending to stop.

Groups are your own filing of your own phones: a label, and the phones in it. There is no create, rename or delete endpoint, and that is the product rather than a gap. A group is created by naming it on a phone (new_group_name) and swept away when the last phone leaves it, which is what stops an agency accumulating empty groups somebody made once. The dashboard works the same way. Counts are of every phone in the group, including ones this key cannot reach.

The complete set, never a delta: whatever you send is what the phone ends up in, so a client working from a stale read cannot silently drop a group it never knew about. {"group_ids": []} takes it out of everything. new_group_name is the only way to create a group. A group left with no phones stops existing, which is how they are cleaned up. There is no delete. Answers with the agency's whole group list, because one write can both create a group and empty another away, so every count may have moved.

What the agency did over the period: worked minutes, how many people and phones were active, gestures sent, and a point per day. Figures come from the same rollups the dashboard reads, so the two always agree. Days are drawn on the agency's timezone rather than UTC (period.timezone says which), and the retention window bounds how far back days can reach.

Per-person desk minutes, worked minutes, phones touched, sittings and gestures, with the last time each was active. presence_minutes is desk time, with overlaps merged so six phones driven at once is one minute; active_minutes is the part of it that carried a gesture. An agency paying by the hour and an agency measuring effort want different ones, and neither can be derived from the other. untrusted_minutes is the part of active_minutes that arrived too late to corroborate against a second signal. It is included in the total, and reported separately so a payroll integration knows which part is soft. ?include=devices adds a devices array to each member: which phones their minutes were spent on, from a daily rollup kept for years. Off by default because it multiplies the response by the rack rather than by the team. That half is limited to the phones this key reaches, since it names handsets, and its active_minutes are phone-minutes: they legitimately sum to more than the member's own, because driving two handsets in one minute is one minute worked and two phones used. For the times rather than the totals, read GET /analytics/sessions. Figures come from the same rollups the dashboard reads, so the two always agree. Days are drawn on the agency's timezone rather than UTC (period.timezone says which), and the retention window bounds how far back days can reach.

Per-phone activity, plus untouched, the phones you hold that nobody used in the period. That is the line item that costs money. Limited to the phones this key reaches, unlike the other analytics endpoints. Those report agency totals and name no phone; this one is an inventory listing with numbers attached, so a key scoped to three handsets sees three. Figures come from the same rollups the dashboard reads, so the two always agree. Days are drawn on the agency's timezone rather than UTC (period.timezone says which), and the retention window bounds how far back days can reach.

One row per person per phone per stretch: username was on device_name from started_at to ended_at. The grain the other reports aggregate away, published raw so you can roll it up whichever way your business asks. This is the report to reach for when something has gone wrong on one handset and the question is who was driving it. /analytics/members says somebody touched ten phones and /analytics/devices says a phone carried an hour; neither says which ten, or whose hour. Limited to the phones this key reaches, like GET /analytics/devices and unlike the agency totals: it names handsets. Paginated, newest first. A sitting is written every time somebody opens a phone, so a busy agency produces thousands a week. Pass next_cursor back as ?cursor= until it comes back null. Two retention lines, and they are different. Sittings themselves are kept for retention_days. The per-minute grain that active_minutes and gestures are computed from is kept for 8 days, so a sitting that started before activity_from reports both as null rather than as zero. For totals older than that, read GET /analytics/members?include=devices, which comes from a daily rollup kept for years. `active_minutes` can exceed `minutes` on a short sitting, and that is not a bug: the minute is the grain, so a stretch from 09:29:50 to 09:30:10 touches two buckets and rounds to zero wall-clock minutes. A minute shared by two sittings is counted once, against the later one, so the sessions never sum to more than the day. A sitting by ALI support carries support: true with a null member_id and username. That somebody from ALI was on your phone is yours to know; which of us it was is not. Figures come from the same rollups the dashboard reads, so the two always agree. Days are drawn on the agency's timezone rather than UTC (period.timezone says which), and the retention window bounds how far back days can reach.

cells[day][hour], Monday first, always 7 rows of 24, so a quiet hour is a zero rather than a missing entry and you can index it without bounds checks. peak is the busiest cell, for scaling a colour ramp in one pass. The week is the agency's local one. Figures come from the same rollups the dashboard reads, so the two always agree. Days are drawn on the agency's timezone rather than UTC (period.timezone says which), and the retention window bounds how far back days can reach.

Everybody with an account in this agency, and the roles each of them holds. Unpaginated, unlike GET /devices: an agency's seat count is capped in the low tens by its plan, so there is no second page to fetch.

Set the complete list of roles somebody holds. Never a delta: whatever you send is what they end up with, so a client working from a stale read cannot silently drop a role it never knew about. An empty array leaves the account able to do nothing. The only write in this API that changes what a person can do, and three things bound it: - A key never outranks its creator. It acts as whoever minted it, so it can only hand out a role that person could hand out by hand: at or below their own standing, carrying nothing they do not already hold. Read assignable on GET /roles. - It cannot act on somebody at or above that standing. A member who outranks the key's creator, a peer of theirs, and the creator themselves all read back as 404: the same answer as an id that does not exist, because a refusal that explained itself would confirm which ids are senior accounts. - So an agency cannot be left without an owner through this endpoint, since taking the last owner's role away would mean acting on a peer or on yourself. Changing an owner is a dashboard operation. Nothing else about a member is writable here. Usernames, addresses and two-factor belong to the person, not to the agency, and are theirs to change.

Every role, what it allows, and whether this key may hand it out. Read assignable before inviting somebody: a key carries the standing of whoever created it, so it can only grant a role that person could grant. Checking here is the difference between choosing a role you can use and finding out from a 403 after you have already picked an address. Read-only. Creating a role means choosing a set of permissions, which is a decision for a screen that explains what each one does.

Every invitation this agency has issued, including the settled ones: accepted, expired, withdrawn. "Did that invitation ever land" is the question this list answers, and one that hid everything but the live ones would answer it with silence.

Invite somebody into your agency. The account is created when they accept, never here. This writes an invitation and sends a link, so no password is chosen, and no seat is taken until somebody takes it. The invitation names a role, from GET /roles. A key can only hand out a role its creator could, so check assignable before choosing one. An address that already signs in anywhere is refused with invalid_request: a person belongs to exactly one agency, and moving somebody between agencies is a separate, deliberate operation. So is a second live invitation to an address that already has one: withdraw or resend the first instead. The link expires. POST /invitations/{id}/resend issues a fresh one and invalidates the old. Retrying safely. Send an Idempotency-Key. It matters less here than on an action, because a duplicate invitation is already refused by a uniqueness rule; what it buys is that a client retrying a timeout gets the original 201 and the invitation back, rather than an error about a pending invitation whose id it cannot see.

The link stops working; the record stays, because it happened and this list is a history as much as a queue. An invitation somebody already accepted cannot be withdrawn. They have an account now, and PATCH /members/{id} with an empty role set is the operation that means what withdrawing would have meant.

Mints a new token and restarts the clock, so the previous link stops working. That is deliberate: a link forwarded to the wrong address, or sitting in a mailbox somebody else now reads, is dead the moment you resend. Not idempotent. Each call is meant to produce a fresh link, and replaying a stored response would hand back one that had already been superseded.

What a provisioning script reads before it orders anything: phones_held against phone_limit answers "may I add another", and timezone is the clock every analytics figure is drawn on, so you can align your own day boundaries instead of guessing at UTC. Read-only. Renaming an agency, moving its timezone or turning on its two-factor requirement all change what every member sees, and the last changes whether they can sign in at all. Those stay in the dashboard.

Connect with wss://. Pushes transitions, not state: use GET /devices for the current picture and this to learn what changed. Event types: device.online, device.offline, device.casting, device.not_casting, media.delivered, media.failed.

→ {"type":"ready","devices":12,"events":[…],"poll_interval_ms":5000}
→ {"type":"device.offline","device":"ph_…","at":"…"}
→ {"type":"media.delivered","device":"ph_…","asset_id":"…","at":"…"}
← {"type":"ping"}   → {"type":"pong","t":…}

The devices count on ready is what this socket is watching, which is every phone the key reaches. That is wider than GET /devices lists, deliberately: a handset dropping off its relay leaves the list and you are still told it went offline. Exists so you do not have to poll GET /devices on a timer, which costs you latency and both of us a full authenticated request per tick.

What the current UTC day has spent and what is left: the free allowance, the purchased balance, what each kind of work costs, and where the credits went, by kind and by phone. This call is free.