PROPFIXLY · DEVELOPER DOCUMENTATION

Resolution API

Submit a property problem. Track the decisions, execution record, evidence, and operator-recorded outcome under one persistent resolution_id.

Controlled internal alpha. This release does not dispatch contractors, spend money, contact residents, accept an SLA, or independently inspect repairs. A submitted request still needs human operations.

OpenAPI specification · Service health

Authentication

Agents use short-lived, property-scoped bearer tokens issued by a PropFixly operator. The operator credential is never placed in an agent or browser. The MCP endpoint rejects it. OAuth consent and public app-directory installation are not enabled.

Start with an authorized property

GET /v1/properties
Authorization: Bearer <scoped-client-token>

Use the property UUID returned by discovery; never infer one from a street address or reuse a property outside the credential's scope.

Submit a request

POST /v1/resolutions
Authorization: Bearer <scoped-client-token>
Content-Type: application/json
Idempotency-Key: your-stable-request-id

{
  "property_id": "<authorized-property-uuid>",
  "problem": {
    "description": "Kitchen sink leaks under the cabinet",
    "category": "plumbing"
  },
  "urgency": "high",
  "constraints": { "max_spend_cents": 30000 }
}

The response contains a durable ID and starts in new for human review. The amount is a requested USD-cent cap, not permission to charge it. Requested deadlines are not accepted service guarantees.

Request and tracking endpoints

Endpoint	Purpose
`GET /v1/properties`	Authorized property discovery
`POST /v1/resolutions`	Create with safe retries
`GET /v1/resolutions`	Scoped request queue
`GET /v1/resolutions/{id}`	Current snapshot and version
`GET /v1/resolutions/{id}/events`	Ordered, versioned API event feed
`POST /v1/resolutions/{id}/cancel`	Cancel or request cancellation follow-up

Operator actions

The operator alone records diagnosis, quote selection, actual human approval references, externally arranged execution, consented evidence, verification, and confirmed cancellation. Each action requires its own idempotency key and the expected current version.

new → diagnosing → waiting_owner_approval → approved
    → scheduled → in_progress → completed after verification

A work-order completion report is not a verified resolution. Verification requires a completed work-order record and same-resolution final-test evidence. The result is an operator attestation, not proof of media authenticity or an automated inspection.

Retry and budget rules

Retry an uncertain request with the identical normalized payload and idempotency key. A changed payload under the same key returns 409 IDEMPOTENCY_CONFLICT. Stale versions return 409 VERSION_CONFLICT. Changing a quote invalidates its prior approval. The hard cap includes amounts committed across recorded execution attempts; cancellation does not automatically release budget or issue a refund.

MCP

The adapter is mounted at /mcp after the SDK-locked release passes verification. It provides five tools: list_properties, resolve_issue, get_resolution, list_resolutions, and cancel_resolution. Only property-scoped client credentials are accepted. Use the host's secure credential store.

Boundaries

Test requests are explicitly marked and excluded from the normal queue. API events do not audit direct database edits or legacy workers. There is no outbound webhook delivery service in this release; callers can poll the event feed. This API is not an emergency response service.