Connections API

Generate appliance maintenance guides and recognize photos you supply. Connected tools require an active CasaCaddy Pro plan, verified by the server on every request. Your editable home library, task schedule, local photos and maintenance history stay on your iPhone.

OpenAPI specification

Requires CasaCaddy 1.0.1 or later. Version 1.0 does not include Assistant pairing. The 1.0.1 update has been submitted to Apple review and ordinary customer onboarding remains pending until it is approved and released. Update the app before following these pairing instructions.

Use https://api.casacaddy.com/mcp with an OAuth-capable assistant. In the updated CasaCaddy app, open Settings → Connected tools → Assistant pairing. Create a one-use code and enter it only in the CasaCaddy consent page the assistant opens. Do not send it in a chat. Pairing requires the current installation credential and an active server-verified Pro entitlement. The code expires after five minutes; it does not confer Pro or spend allowance.

After pairing, approve the exact permissions. Three individual tools identify the connected installation, request a maintenance guide from appliance details you supply, and recover your own MCP guide requests. No on-device inventory, task schedule, photos, billing, subscription changes or deletion is exposed. The separate photo-recognition API below is not exposed through MCP.

Before a guide call, confirm the appliance details and use of existing Pro allowance. Send a fresh UUID request_key and use_existing_allowance=true. Reuse that same key when recovering a lost response. An identical replay returns the persisted result without another provider call; changed inputs under the same key are rejected. A processing or failed result is not a reason to automatically submit a new key. Keep every safety warning, step caution and professional-help boundary intact.

OAuth supports public-client registration and exact-resource S256 PKCE. Access credentials last one hour; rotating refresh credentials expire within 30 days. Request results are recoverable for 30 days. Revoke access in the native Connected tools screen or the linked browser’s Connections page. UserInfo provides the actual anonymous installation subject; verified-email Enterprise domain restrictions are unsupported because ordinary CasaCaddy installations have no email account. A live endpoint does not imply directory review or approval.

Private app-reviewer credentials open a clearly labeled synthetic installation with two stored example guides. This fixture contains no customer home data, real purchase or usable fresh paid-provider path. Use either exact input below with a fresh request key, then recover the same request to test persisted results and replay. Ordinary users link their own Pro installation through native pairing.

[
  {
    "item": {
      "category": "gutter",
      "brand": "Synthetic fixture",
      "model": "Review-only visual inspection"
    },
    "question": "Synthetic reviewer: safe visual check from the ground"
  },
  {
    "item": {
      "category": "smoke_co_detector",
      "brand": "Synthetic fixture",
      "model": "Review-only label inspection"
    },
    "question": "Synthetic reviewer: check the device label without disassembly"
  }
]

1. Open CasaCaddy → Settings → Connected tools.
2. Name the tool and choose an expiry of 7 or 30 days. Guide generation starts selected; photo recognition starts off.
3. Read the access disclosure. Photo recognition additionally requires acknowledging photo and serial/model sharing.
4. Create the connection and copy its key once into the chosen tool’s secret storage.

Use the x-api-key header with your cck_ key. Never share the native device JWT, place a key in a URL or prompt, or send it to support. Keys can be revoked in the same native settings screen. Revocation stops future access but cannot remove information a tool has already received.

A key belongs to the installation that created it. Normal device-token renewal preserves it; replacing the device identity does not transfer its management. Deleting that installation’s server data removes its keys. Expired or revoked keys cannot authenticate.

POST https://api.casacaddy.com/api/guide requires guides:generate. Send JSON containing item with its category, optional brand/model/specs, and an optional question.

{
  "item": {
    "category": "refrigerator",
    "brand": "Example",
    "model": "User-confirmed model"
  },
  "question": "What routine inspection can I do safely?"
}

The response includes guide, cached and quota. Always display safety warnings, step cautions and when to call a professional. Do not turn inspection-only gas, high-voltage, refrigerant or roof guidance into repair instructions.

POST https://api.casacaddy.com/api/recognize requires the optional recognition:analyze scope. Send imageBase64, an optional imageBase64Plate close-up, and an optional hint. Each decoded image is limited to 2MB and the request body to 4MB. Photos use the same protected image-processing/model pipeline as the app.

Results include category, brand, model, serial, confidence, specifications and suggested maintenance tasks. Ask the owner to confirm uncertain details. A 422 response may contain low-confidence partial results; never silently treat them as confirmed. The API returns suggestions and does not add an item or schedule to the iPhone’s local database.

A cached recognition requires the same installation, primary photo, optional plate photo and exact hint. Changing any of these requires a fresh recognition and its allowance.

Pro allows up to 30 recognitions and 60 fresh guides daily for the same installation, shared by the app and its connections. Exact cached responses do not consume a fresh allowance. Global spending controls and the kill switch remain in force. The API does not buy, restore, change or cancel a subscription.

Each key permits 60 requests per minute. A transport-limit 429 includes Retry-After: 60. Device quota exhaustion also returns 429 with quota details. Do not retry repeatedly. HTTP 401 means a key is invalid, expired, revoked or missing a permission; 402 means Pro is inactive; 403 means the action is unavailable; 503 means budget or service availability prevents the operation.

There are no connector operations for local inventory/history, device registration/refresh/deletion, purchase verification, Apple notifications or connection management. Use the app for those actions.

• “Draft a routine inspection guide for this user-confirmed refrigerator model, including every safety warning.”
• “Identify this appliance from the photo I selected. Ask me to confirm its model and serial before using the result.”

Privacy · Support