The Aperture docs.

Start here when you are not given an address. Describe what you need to do in plain words (for example 'remove a resident from the access list' or 'update a customer record'). Returns the systems you are allowed to work in that match, with the address to compile and any profile other agents shared. It never searches the open web.

needrequiredstring

What you need to do or find, in plain words.

find_systems({ need: "remove a resident from the gate access system" })

{ "status": "found", "matches": [ { "name": "GateAdmin replica, residents (sign-in required)",
    "address": ".../Residents.aspx",
    "sign_in": "compile_site with login 'REPLICA', url '.../Login.aspx', then '.../Residents.aspx'" } ] }

Start here. Returns a short guide to this system, the record kinds, and the rules. Read it once.

No parameters.

Point Aperture at a web page and it reads the page's forms, read-only, and turns each one into a typed record you can fill. Only works on hosts the operator has authorized. It never submits anything and never tries to get past a CAPTCHA: a person does that. Returns each form's id, fields (label, type, required, allowed values) and submit button.

urlstring

The page address. With login set, this is the sign-in page. Leave it out to read the current page again (after a submit, or when a page changed).

loginstring

Name of a login the operator stored on the server. You never see the password.

thenstring

With login: the page to compile after signing in.

compile_site({ url: ".../Login.aspx", login: "REPLICA", then: ".../Residents.aspx" })

{ "status": "compiled", "tables": [ { "id": "residents", "key": "Dir", "rows": 91 },
    { "id": "vendors", "key": "Dir", "rows": 3 } ] }

Look up records. Returns small typed items with their unique keys. Names are not unique: always act on the key. Free, nothing changes.

kindrequiredstring

Record kind, as compile_site or find_systems named it (for example residents or devices). Call compile_site first if you have none.

querystring

Text to match in any field, like a name. Leave empty to list.

limitinteger

Most items to return.

find({ kind: "residents", query: "Dev Alder" })

{ "kind": "residents", "count": 2, "note": "Several matches. Names are not unique, use the key.",
  "items": [ { "key": "1004", "Resident": "Dev Alder", "Notes": "Unit 103D" },
             { "key": "1026", "Resident": "Dev Alder", "Notes": "Unit 125B" } ] }

The normal way to make a change. Previews inside the server. If the rules allow it, it commits at once and returns a receipt with a read-back. If a person must decide, it returns awaiting_approval with a plan_id to poll with get_plan.

oprequired"delete" | "create" | "update" | "publish"

One of delete, create, update, publish.

kindstring

Record kind, as compile_site or find_systems named it.

keystring

The unique key from find. Never a name.

recordobject

For create: the fields of the new record, including its key.

patchobject

For update: the fields to change, like { city: 'Leeds' }.

apply({ op: "delete", kind: "residents", key: "1004" })

{ "status": "done", "receipt": "rcpt_7",
  "verified": { "ok": true, "subject_present": false, "matches_prediction": true,
                "counts_after": { "residents": 90, "devices": 166 } },
  "not_yet_live": "Recorded in this system. It also has a separate step ('Snd Data') that Aperture has not pressed...",
  "undo_until": "2026-10-19T10:10:57Z" }

Apply many changes in one call. Everything inside the rules commits. Items that need the owner are listed with plan_ids. Refusals are listed with next moves. Stops at the first failed commit. Returns one summary, so you do not need many round trips.

opsobject[]

Up to 50 operations, each shaped like an apply call.

plan_idsstring[]

Instead of ops: commit plans the owner already approved, in order, with the first `canary` checked first.

stop_on_failureboolean

Stop at the first failed commit (the default).

dry_runboolean

Change nothing. Returns the total blast radius: everything that would be removed, dependents included.

canaryinteger

Commit only the first N, check they did exactly what was predicted, and halt the rest if any surprised or failed.

apply_batch({ ops: [ { op: "delete", kind: "residents", key: "1001" }, ... ], dry_run: true })

{ "would_remove": { "residents": 91, "devices": 168 },
  "refused": [ { "key": "1006", "error": "policy_denied", "detail": "Daily delete limit reached: 5 of 5.",
                 "next": ["escalate(reason) to ask the owner for more"] } ] }

Delete one record by key. With dry_run: true it only previews: what is removed, the count change, which rule applies. Nothing changes. To commit, call again with the plan_id. For most jobs use apply, which does both when the rules allow.

kindrequiredstring

Record kind, as compile_site or find_systems named it (for example residents or devices). Call compile_site first if you have none.

keyrequiredstring

The unique key from find, like S014. Never a name.

dry_runboolean

Preview only: what would be removed, the count change, and which rule applies. Nothing changes.

plan_idstring

Commit a plan you already previewed.

delete({ kind: "residents", key: "1004", dry_run: true })

{ "status": "previewed", "plan_id": "pln_23",
  "diff": ["- residents 1004", "- 2 devices",
           "(the devices above go with this residents automatically: do not delete them separately)"] }

Create one record. The record needs a unique key. With dry_run: true it only previews. To commit, call again with the plan_id.

kindrequiredstring

Record kind, as compile_site or find_systems named it (for example residents or devices). Call compile_site first if you have none.

recordrequiredobject

Fields of the new record. Must include a unique key.

dry_runboolean

Preview only. Nothing changes.

plan_idstring

Commit a plan you already previewed.

Reverse a committed change using the copy saved before it. Reads the system back to verify. Works within the undo window. Published changes cannot be recalled.

receipt_idrequiredstring

The receipt id from the commit result.

undo({ receipt_id: "rcpt_9" })

{ "status": "undone", "restored": true, "fields_not_restored": ["Phone"],
  "verified": { "ok": true, "counts_after": { "residents": 91, "devices": 168 } } }

Check a plan: awaiting_approval, approved, expired, committed. Use it to wait for the owner's decision instead of retrying. If the outcome of a change is unknown (the server stopped while it ran), this reads the system and says what really happened; it never runs the change again.

plan_idrequiredstring

The plan id from a preview, apply or apply_batch.

wait_secondsinteger

Wait up to this long for the owner to decide, so you do not burn turns polling.

get_plan({ plan_id: "pln_23", wait_seconds: 10 })

{ "plan_id": "pln_23", "status": "committed", "diff": ["- residents 1020", "- 1 devices"] }

Ask the owner for help when a rule blocks you, like the daily limit. One message goes out. Keep working on other items. Do not retry the blocked one.

reasonrequiredstring

One sentence on what you need and why.

escalate({ reason: "Daily delete limit reached after 5 of 91; need owner approval to continue." })

{ "status": "pending_human", "ticket": "esc_2", "agent_can_continue_with": ["find", "create", "other deletes inside the limit"] }

Send staged changes to the outside world (for example to devices, a gate, or another system). It always needs the owner. Without plan_id it previews and asks the owner. It cannot be undone.

plan_idstring

Commit a send the owner has approved. Without it, publish previews and asks the owner.

publish({})

{ "status": "refused", "error": "send_needs_owner",
  "detail": "3 changes are recorded but not sent. The send step is 'Snd Data' on Accounts.aspx; only the owner sends." }