Landlord API — Move-in Handover (v1, read + draft)
A landlord's AI agent can read the move-in Handover Report in every state, including the tenant's dispute threads, and build the draft's areas, entries, and photos through the Landlord Rental API v1. Submitting the Baseline, replying to the tenant, and AI consent stay the landlord's own acts in the portal, and a server-computed readiness block tells the agent when to send the landlord to submit.
- Predecessor Landlord API slices 1–3; Enquiries & Offers; Rent & Payments; Agreements (2026-10-03-landlord-api-agreements-design.md); Slice 5 (2026-08-28-rental-platform-slice5-move-in-handover-design.md)
- ADRs 0062
- Status Approved
A landlord's AI agent gets read access to the move-in Handover Report, including the tenant's dispute threads, and can build the draft: areas, entries, and photos. Submitting the Baseline, replying to the tenant, and AI consent stay the landlord's own acts in the portal. A server-computed readiness block tells the agent when to send the landlord to submit.
- Predecessors
- Landlord API slices 1–3; Enquiries & Offers; Rent & Payments; Agreements (
2026-10-03-landlord-api-agreements-design.md); Slice 5 (2026-08-28-rental-platform-slice5-move-in-handover-design.md) - Related ADRs
- 0062 (shared notification events)
- Glossary
CONTEXT.md— Handover Report, Baseline, Acceptance (of a Handover Report), Tenancy
1. Goal
A landlord's AI agent can take the move-in handover chore off the landlord through the Landlord Rental API v1, with a key holding the Money, agreements, tenants bundle (handover:[read,write]). This is the third of four sub-projects for the bundle; Contacts follows.
The agent can
v1- Read the tenancy's move-in Handover Report in any state, including the tenant's dispute threads, and tell the landlord what needs attention and by when.
- Build the draft: areas, entries, and photos.
- Tell the landlord when the draft is ready, so the landlord submits it in the portal.
Portal only
landlord's act- Submit the Baseline
- Reply to or resolve a thread
- AI consent and AI analysis
2. Decisions
D1 · Scope
Read the report in every state. Create the draft; create, update, and delete areas and entries; upload, attach, and delete photos. Submit, responses, acceptance, the final PDF, AI consent, and AI analysis stay in the portal.
Drafting is the real chore: turning a walkthrough into areas, entries, and photos. A listing can be withdrawn; a submitted Baseline cannot.
Rejected: read only (no chore removed); agent submit after confirmation; agent dispute replies.
D2 · Tenant content
Full threads: opening action, target, every comment, actor role, timestamps, and both parties' reply photos. No user ids, names, IPs, user agents, AI fields, or acceptance audit data.
Dispute comments are the review's substance and the landlord must answer them in the portal within seven days. The landlord already sees them. The v1 rule is "nothing the landlord cannot see, and no identity data". Unlike the agreement void_reason (closing text on a dead deal), the agent needs this to brief the landlord. Tenant photos show the unit, not the tenant.
Rejected: thread text without tenant photos; thread state only.
D3 · Assistant marker
created_via = 'api' on areas, entries, and media. The portal draft editor shows "Added by your assistant". Not in the Baseline, the final snapshot, their hashes, or the PDF.
Keeping submit in the portal only protects the landlord if they can see what to check. The landlord owns the content by submitting, and the Baseline records only what each party actually did; adding a second author claim would also change the canonical snapshot behind the hash.
Rejected: no marker; marker in the Baseline and PDF.
D4 · Photo input
Multipart upload only. Idempotency-Key maps onto upload_request_id. No URL import.
Handover photos are deposit evidence. A URL import invites listing photos or old albums and adds server-side fetches of arbitrary URLs. The agent already holds the files the landlord shared.
Rejected: import from URL.
D5 · Editing
The agent creates anything, but updates or deletes only items with created_via = 'api', and only while draft.
The danger in a draft is the agent deleting a photo the landlord took on site after the keys changed hands. Own-items-only removes it and still lets the agent fix its own mistakes.
Rejected: full draft control; create only. Agent-proposed edits to landlord items with landlord approval is deferred (§10).
D6 · Readiness
Server-computed readiness on the report body, from one domain function shared with submit.
Today the readiness check runs in the browser only (handover.go:1271-1302 is the server's submit check). Rules restated in the guide would drift.
Rejected: agent derives readiness from raw rows.
D7 · Empty report
A draft with no areas is not ready, and portal submit refuses it.
Submit currently passes with zero areas because no rule fails (handover.go:1271-1302). An empty Baseline is a trap for both parties. No live users, so nothing to migrate.
Rejected: report no_areas in readiness only.
- D8 · Test keys
- A report takes the mode of its tenancy's property. A mismatch reads as 404.
- D9 · Implementation
- Dedicated
v1_handover_handler.go. A scoped visibility check, then the existingHandoverUseCasemethod. Allowlisted DTOs built from live rows (draft) or the frozen Baseline (after submission); never the raw snapshot.
Lifecycle and who acts
draft; every transition out of it is a person's act.starts_on − 7 to starts_on + 3, Malaysian dates) and the seven-day tenant review, shown for a Baseline submitted on starts_on. Creation is refused after starts_on + 3.3. Endpoints
All under /api/v1/rental. Reads need handover:read; writes need handover:write.
| # | Method and path | Purpose |
|---|---|---|
| 1 | GET /tenancies/{id}/handover-report | The tenancy's move-in report, or 404 handover_report_not_found. |
| 2 | POST /tenancies/{id}/handover-report | Create the draft. 201 when created; 200 with the existing report on repeat. |
| 3 | GET /handover-reports/{id} | The report (§3.1). |
| 4 | POST /handover-reports/{id}/areas | Create an area {name, sort_order}. Idempotency-Key. |
| 5 | PATCH /handover-areas/{id} | Rename or reorder an agent-made area. |
| 6 | DELETE /handover-areas/{id} | Delete an agent-made area. |
| 7 | POST /handover-areas/{id}/entries | Create an entry. Idempotency-Key. |
| 8 | PATCH /handover-entries/{id} | Update an agent-made entry. |
| 9 | DELETE /handover-entries/{id} | Delete an agent-made entry. |
| 10 | POST /handover-reports/{id}/media | Multipart file, optional area_id or entry_id. Idempotency-Key is required and becomes upload_request_id. |
| 11 | PATCH /handover-media/{id} | Attach an agent-uploaded staged photo to an area or entry. |
| 12 | DELETE /handover-media/{id} | Delete an agent-uploaded photo while draft. |
| 13 | GET /handover-media/{id}/content | Image bytes. ?variant=thumbnail or original (default). Any photo in the report, including tenant reply photos. |
The response for writes 2, 4, 5, 7, 8, 10, 11 is the affected object in the §3.1 shape (the report, an area, an entry, or a media item). Deletes return 204.
Entry bodies follow Slice 5 §6.3: entry_type is condition | inventory | access_device | meter_reading, with the same required and forbidden fields per type. meter_value is a decimal string; meter_unit is kwh | m3.
3.1 Report
{
"id": "…",
"tenancy_id": "…",
"status": "draft",
"submitted_at": null,
"review_due_on": null,
"finalized_at": null,
"finalization_reason": null,
"baseline_sha256": null,
"readiness": {
"ready": false,
"problems": [{ "code": "area_without_photo", "area_id": "…" }],
"warnings": [{ "code": "staged_photo_unattached", "media_id": "…" }],
"baseline_images_remaining": 63,
"submit_window": { "opens_on": "2026-10-25", "closes_on": "2026-11-04" }
},
"areas": [{
"id": "…", "name": "Master bedroom", "sort_order": 1, "created_via": "api",
"media_ids": ["…"],
"entries": [{
"id": "…", "entry_type": "meter_reading", "label": "Electricity meter",
"condition_note": null, "quantity": null,
"meter_value": "10234.500", "meter_unit": "kwh",
"sort_order": 1, "created_via": null, "media_ids": ["…"]
}]
}],
"media": [{
"id": "…", "status": "ready", "stage": "attached",
"area_id": "…", "entry_id": null, "response_id": null,
"uploaded_by": "landlord", "created_via": "api",
"mime_type": "image/jpeg", "pixel_width": 3024, "pixel_height": 4032,
"quality_warnings": ["low_resolution"], "uploaded_at": "2026-10-26T03:00:00Z"
}],
"threads": [{
"id": "…", "target_type": "entry", "target_id": "…",
"status": "open", "opened_by": "tenant", "last_actor": "landlord",
"last_action": "reply", "awaiting": "tenant",
"events": [{
"id": "…", "actor": "tenant", "action": "dispute_entry",
"comment": "Aircon leaks onto the floor.", "media_ids": ["…"],
"created_at": "2026-10-27T09:00:00Z"
}]
}]
}
statusisdraft | tenant_review | finalized;finalization_reasonistenant_accepted | deadline_elapsed | null.- Source. While
draft, areas, entries, and media come from the live rows. After submission they come from the frozen Baseline; media are the Baseline's media plus response media. The snapshot'slandlord_display_name,tenant_display_name, andproperty_addressare never read. review_due_onandsubmit_windowdates are Malaysian calendar dates (YYYY-MM-DD).submit_windowisstarts_on − 7throughstarts_on + 3(Slice 5 §4.3). Timestamps are RFC 3339 UTC.readinessis present only whiledraft; otherwisenull.created_viais"api"ornull. Baseline items read it from the live row by id; it is not in the snapshot.uploaded_byis the uploader's role (landlord | tenant), derived from the uploader id against the tenancy parties.- Threads:
statusisopen | resolved;last_actionis one ofdispute_entry | report_omission | reply | resolve | withdraw(a withdrawn thread isresolvedwithlast_action: withdraw).opened_by,last_actor, andactorare roles.awaitingis the party who may act next on an open thread (replies alternate),nullwhen resolved. Threads are ordered by first event time; events oldest first. media_idson an area lists photos attached to the area itself; on an entry, photos attached to the entry; on an event, its reply photos.
4. Visibility
A report is visible when its tenancy is visible under the tenancy rule: landlord_user_id = key user and the property's is_test matches the key mode. Areas, entries, and media resolve through report → tenancy. Anything not visible reads as not found. A malformed id reads as not found. There is no tenant-side v1 access.
5. Writes
Each write runs the scoped visibility check, then the existing HandoverUseCase method (CreateMoveInReport, CreateArea, UpdateArea, DeleteArea, CreateEntry, UpdateEntry, DeleteEntry, UploadMedia, AttachMedia, DeleteMedia). Locking, budgets, entry-type validation, and the window rules are not duplicated.
created_via- A migration adds nullable
created_via TEXT CHECK (created_via IN ('api'))torental_handover_areas,rental_handover_entries, andrental_handover_media. The repositories set it to'api'whenmiddleware.GetActorTypeFromContext(ctx) == "api_key", asMessageRepositorysetssent_via. Existing rows stayNULL; no backfill. - Ownership
- The update and delete use-case methods gain an ownership rule: when the caller acts through an API key, the target must have
created_via = 'api', elseErrHandoverItemNotEditable. Portal callers are unaffected. Every write still requiresdraft(ErrHandoverNotDraft→ the same 409 code on v1). - Upload
Idempotency-Keyis required onPOST /handover-reports/{id}/mediaand is passed asupload_request_id. A replay returns the existing media lifecycle (Slice 5 §6.4), withIdempotent-Replay: true. Area and entry creates use the shared v1IdempotencyUseCase.Execute.
6. Readiness
New domain function entity.EvaluateBaselineReadiness(areas, entries, media, startsOn, now) returns all problems and warnings. SubmitBaseline calls it inside its locked transaction and returns the error for the first problem, so portal behaviour is unchanged except D7.
-
no_areasThe draft has no area. new (D7) Portal submit getsErrBaselineHasNoAreas. problem -
area_without_photoAn area (area_id) has no attached, ready photo of its own. existing rule problem -
meter_without_photoA meter-reading entry (entry_id) has no attached, ready photo. existing rule problem -
photo_not_readyAn attached photo (media_id) isuploadingorfailed. Slice 5 §10B requires every image ready; current code skips such photos instead of refusing. problem -
outside_submit_windowToday's Malaysian date is outsidesubmit_window. existing rule problem -
staged_photo_unattachedA ready photo (media_id) is staged. It is excluded from the Baseline. warning
ready is true when problems is empty. baseline_images_remaining is 100 minus the report's baseline photos counted against the existing budget.
7. Errors
New published codes: handover_report_not_found, handover_item_not_found, handover_item_not_editable, handover_window_not_open, handover_window_closed, handover_image_limit_reached, upload_expired.
| Case | Response |
|---|---|
| Report not visible, or the tenancy has no report | 404 handover_report_not_found |
| Area, entry, or media not visible or unknown | 404 handover_item_not_found |
Report not draft, or the item is not agent-made | 409 handover_item_not_editable |
Create before starts_on − 7 | 409 handover_window_not_open |
Create after starts_on + 3 | 409 handover_window_closed |
| 100-per-report or 10-per-target baseline budget | 409 handover_image_limit_reached |
| Not JPEG or PNG, HEIC, unsafe dimensions, over 5 MB | 400 validation_failed, fields: ["file"] |
Missing Idempotency-Key on upload | 400 validation_failed, fields: ["Idempotency-Key"] |
| Wrong fields for the entry type, negative meter, bad unit, duplicate area name, both or neither attach target | 400 validation_failed naming the field |
| Upload retry after the 24-hour staged sweep | 410 upload_expired |
Same Idempotency-Key, different body | 409 idempotency_conflict (existing) |
| Media store unavailable | 503 media_unavailable (existing) |
| Key without the scope | 403 insufficient_permission (existing) |
| Anything else | 500 internal_error, no internal text |
8. Frontend and API guide
Separate change: frontend/solidstart/openspec/changes/landlord-api-handover-ui.
- Draft editor
- Areas, entries, and photos with
created_via = 'api'show "Added by your assistant"; en/ms/zh via the Paraglide workflow. - Portal submit
- Copy for the empty-report refusal ("Add at least one area before submitting") and for a photo still processing; en/ms/zh.
- Key form
- The money bundle label becomes "no contacts yet".
- API guide
frontend/astro/apps/rental/src/docs/landlord-api-v1.md: new "Move-in handover" section — lifecycle, submit window, seven-day review; that the agent drafts and the landlord submits and replies in the portal; entry types and fields; meter values as decimal strings; upload, staging, attaching, budgets,Idempotency-Key;readiness; threads andawaiting; the own-items editing rule; error codes.
New agent rules:
- Upload only photos the landlord took for this handover. Never reuse listing photos.
- To correct a landlord's item, add a corrected one and ask the landlord to delete the original.
- When
readiness.readyis true, tell the landlord to submit in the portal beforesubmit_window.closes_on. - Report every open thread where
awaitingislandlord, withreview_due_on.
9. Contract and testing
openapi/rental-v1.yaml: the 13 operations with scopes; multipart upload body; binary content response;Idempotency-Keyon area create, entry create, and upload (required on upload); theHandoverReportschema; the seven new codes inErrorCode.- Contract-table rows for every route;
openapi_drift_test.gopasses in both directions.
Integration tests on pg-test (:55432), compared against a recorded rental baseline:
- Golden no-PII
- Report bodies in
draft,tenant_review, andfinalizedcontain none of the §3.1 "never returned" keys. Fixture: a submitted report whose snapshot has names and address, threads from both parties with photos, an AI suggestion, and an acceptance. Extend the NRIC golden test to these routes. - Isolation
- Other landlord, wrong mode, key user as tenant → 404 on the report and every child route; unknown and malformed ids → 404.
- Draft vs frozen
- After submission the body equals the Baseline; a live row changed directly in the database after submission does not appear.
- Ownership
- The agent updates and deletes its own area, entry, and photo; landlord-made items → 409
handover_item_not_editable; any write after submission → 409. created_via- Set by API writes,
NULLfrom portal writes; the Baseline hash of a fixed fixture is unchanged by the column. - Readiness
- One case per problem and warning, window boundaries in Malaysia time,
baseline_images_remaining. - Submit refactor
- Existing submit tests pass unchanged; portal submit of an empty report and of a report with a processing photo now fail.
- Upload
Idempotency-Keyreplay returns the same media withIdempotent-Replay: true; missing key → 400; budget → 409; bad file → 400; after the sweep → 410; content returns original and thumbnail for baseline and tenant reply photos.- Not routed
- Submit, responses, accept, document, AI routes → 404
route_not_found. - Scope
- A key with
handover:readonly → 403 on writes.
10. Deferred
Proposed edits
laterAgent-proposed edits to landlord items, applied after landlord approval in the portal.
Agent submit
laterAgent submit of the Baseline after explicit landlord confirmation.
Replies
laterAgent dispute replies and resolve.
URL import
laterPhoto import from URL.
11. Risks
12. Assumptions
- Thread reduction (
entity.ReduceThreads) is the source ofstatus,last_action, andawaiting; the v1 layer adds no thread rules. - No new ADR; the decisions are reversible API-layer choices plus two submit-validation tightenings already required by Slice 5.