The NestWatch API

Authentication

Create an API key in Settings → API keys (you need the Business plan and an owner or admin role). The full key is shown once at creation. Send it as a bearer token on every request:

curl https://nestwatch.ai/api/v1/properties \
  -H "Authorization: Bearer nw_your_key_here"

A key reads and writes one workspace: the one it was created in. Revoking a key in Settings cuts off its access immediately. Keep keys out of client-side code and version control; if a key leaks, revoke it and create a new one.

Requests without a valid key get 401. Workspaces not on the Business plan get 402 with code: "upgrade_required".

Rate limits

Each key can make 120 requests per minute. Past that, requests return 429 with a Retry-After header. Back off and retry after the window resets. If you need a higher limit for a specific integration, contact hello@nestwatch.ai.

Errors

Every error is JSON with a human-readable error message and a stable code:

{
  "error": "Property not found",
  "code": "not_found"
}

Pagination

List endpoints take ?limit= (default 50, max 200) and ?offset=, and wrap results in a consistent envelope:

{
  "data": [ ... ],
  "pagination": { "total": 137, "limit": 50, "offset": 0 }
}

Properties

The homes you watch. Create bodies accept name (required), homeownerId, addressLine1, addressLine2, city, state, postalCode, propertyType, and notes.

List filters: status (active | inactive), homeownerId

Homeowners

Your clients. Create bodies accept name (required), email, phone, preferredContact (email | sms | both), and notes. SMS opt-in is not settable here: texting consent is recorded in-app so there's proof behind every opt-in.

Visits

Scheduled and completed home-watch visits. Create bodies accept propertyId (required), scheduledDate (YYYY-MM-DD), scheduledTime (HH:MM, 24-hour), and summary. API-created visits are routine visits; storm workflows and checklists stay in the app.

List filters: status (scheduled | in_progress | completed | report_sent), propertyId

Issues

Problems found at a property. Create bodies accept propertyId (required), title (required), description, severity (low | medium | high | urgent), and visitId to link the visit that surfaced it.

List filters: status (open | in_progress | resolved | dismissed), propertyId

Invoices

Billing records. Create bodies accept amountCents (required), propertyId, homeownerId, description, serviceDate, dueDate, and notes. When you pass a propertyId without a homeownerId, the property's homeowner is billed automatically. Created invoices start as drafts; sending and payment happen in the app.

List filters: status (draft | sent | paid | overdue | void), propertyId, homeownerId

Reports

Read-only summaries of visit reports: id, visitId, propertyId, type (ai | standard), status, and timestamps. Report content is delivered to homeowners through their portal, not the API.

List filters: status (draft | edited | sent)

A worked example

Schedule a visit at a property you already track:

curl -X POST https://nestwatch.ai/api/v1/visits \
  -H "Authorization: Bearer nw_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyId": "9b2f6c4e-1234-4abc-9def-0123456789ab",
    "scheduledDate": "2026-09-01",
    "scheduledTime": "09:30"
  }'

The response is the created visit:

{
  "id": "1f0e9d8c-5678-4abc-9def-0123456789ab",
  "propertyId": "9b2f6c4e-1234-4abc-9def-0123456789ab",
  "status": "scheduled",
  "visitType": "routine",
  "scheduledDate": "2026-09-01",
  "scheduledTime": "09:30",
  "startedAt": null,
  "completedAt": null,
  "summary": null,
  "createdAt": "2026-08-15T14:03:22.000Z",
  "updatedAt": "2026-08-15T14:03:22.000Z"
}

What's not in v1

v1 is a deliberately small surface: the records above, key auth, and nothing that belongs in the app (report content, payments, SMS consent, team management). Outbound webhooks and OAuth for third-party apps are on the roadmap. Tell us what your integration needs at hello@nestwatch.ai.