---
title: "Property Decision Check: Recent & Scheduled Changes"
method: POST
path: "/api/locus-property-update"
tags: ["data", "search", "real-estate", "property", "property-research", "due-diligence", "public-records", "x402", "async", "current-records", "pdf", "video", "cloudflare-r2", "category:reports"]
---

# Property Decision Check: Recent & Scheduled Changes

`POST /api/locus-property-update`

## Request

- Base URL: `https://api.locus.report`
- URL: `https://api.locus.report/api/locus-property-update`
- Auth: API key in header `PAYMENT-SIGNATURE`

Surfaces recent and scheduled official-record changes, nearby activity, and physical comparability for one US address before spending more time or money. Starts a pollable job; its shareable decision report and animated map expire together. Thin results are charge-free. npx @velinussage/locus-agent-skill add.

## Request body

- object: One US street address. Returns quickly with a private, pollable async job only when the preflight finds enough time-sensitive official-record context to justify payment.
  - `address` string, required: One US street address. Locus preflights official-record coverage before payment.
  - `radiusMeters` number, required
  - `lookbackDays` integer, required
  - `focus` string[]: Emphasize these finding families in the video scene ordering. The aerial subject opening and report/QR closing scenes are unaffected.
  - `brand` object: Optional caller-authorized logo that replaces the visible Locus lockup in the property-update video, proof-gated HTML view, and PDF. It does not change the canonical JSON report or its hash.
    - `logo` object, required
      - `role` 'brand_logo', required: Declares a raster brand mark that replaces visible Locus branding in the requested flyer or video.
      - `url` string, required: HTTPS URL for a caller-authorized PNG, JPEG, or WebP logo. The API fetches and embeds it; renderers never fetch this URL.
      - `sourceName` string, required
      - `rightsConfirmed` true, required
      - `rightsBasis` 'owned_by_requester' | 'licensed_for_marketing' | 'public_domain', required
      - `rightsHolder` string, required
      - `permittedUse` 'commercial_marketing', required
      - `attestedAt` string, date-time, required
      - `privacyReviewed` true, required: Requester confirms the logo contains no unnecessary personal information.

## Response `200`

Free pre-charge insufficient_current_context diagnostic; no payment is captured.

- PropertyUpdateDiagnostic
  - `kind` 'property_update_diagnostic', required
  - `charged` false, required
  - `status` 'insufficient_current_context' | 'clarification_required', required
  - `message` string, required
  - `findingCount` integer, required
  - `recommendedRadiusMeters` number
  - `requestedAddress` string
  - `matchedAddress` string
  - `matchedParcelId` string
  - `recommendedAction` 'retry_with_larger_radius_or_choose_another_workflow' | 'confirm_subject_before_payment', required
  - `retryInput` object
    - `address` string, required: One US street address. Locus preflights official-record coverage before payment.
    - `radiusMeters` number, required
    - `lookbackDays` integer, required
    - `focus` string[]: Emphasize these finding families in the video scene ordering. The aerial subject opening and report/QR closing scenes are unaffected.
    - `brand` object: Optional caller-authorized logo that replaces the visible Locus lockup in the property-update video, proof-gated HTML view, and PDF. It does not change the canonical JSON report or its hash.
      - `logo` object, required
        - `role` 'brand_logo', required: Declares a raster brand mark that replaces visible Locus branding in the requested flyer or video.
        - `url` string, required: HTTPS URL for a caller-authorized PNG, JPEG, or WebP logo. The API fetches and embeds it; renderers never fetch this URL.
        - `sourceName` string, required
        - `rightsConfirmed` true, required
        - `rightsBasis` 'owned_by_requester' | 'licensed_for_marketing' | 'public_domain', required
        - `rightsHolder` string, required
        - `permittedUse` 'commercial_marketing', required
        - `attestedAt` string, date-time, required
        - `privacyReviewed` true, required: Requester confirms the logo contains no unnecessary personal information.
  - `alternativeTools` object[]
    - `tool` 'locus-local-trend-brief' | 'locus-place-report', required
    - `endpoint` '/api/locus-local-trend-brief' | '/api/locus-place-report', required
    - `requiresPayment` true, required
    - `reason` string, required
    - `availableForPlace` union, required: Shared lane-availability result for the resolved place; false means do not call this route here.
      - boolean
      - 'varies'
    - `coverageNote` string
    - `inputHint` union, required: Schema-safe request fields for the named alternative; preflight and authorize it as a separate paid call.
      - object
        - `place` string, required
        - `intent` 'homebuyer_due_diligence', required
        - `lookbackMonths` integer, required
      - object
        - `address` string, required
        - `radiusMeters` number, required
        - `lookbackDays` integer, required

## Other responses

- `202`: Accepted after one successful settlement. Poll statusUrl; the initial flyerReady value is false.
- `400`: Invalid request body.
- `402`: Payment Required. For x402 v2, repeat the identical request with a valid PAYMENT-SIGNATURE header (legacy X-PAYMENT is accepted for compatibility). MPP is disabled for this lifecycle-bound tool.
- `409`: Charge-free clarification_required diagnostic. If retryInput is present, confirm the matched subject and send retryInput as the next request; otherwise ask for a corrected exact address.

---

[API](https://skmtc.dev/locus/apis/locus-api.md) · [All operations](https://skmtc.dev/locus/apis/locus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/locus/apis/locus-api/revisions/ba7786b74adb?raw)