Portfolio Health

Use GET /teams/issues to read current open issues across accessible teams in one regional data partition. Use a partner API key for a managed portfolio or a team API key for that team's scope.

For an interactive partner UI, discover available partitions from GET /me at partnerContext.managedTeamRegions. Send x-data-region when reading a partition. The API does not merge multiple regions in one response; call each advertised regional API base URL independently when the screen needs the full portfolio.

Pagination and Filters

teamIds: optional comma-separated team UUIDs; omit for all accessible teams.
codes: optional comma-separated values from the Issue Catalog.
includeEmptyTeams: include teams with no open issues.
view=summary|detail: view=detail (default) includes each issue's code-specific context; view=summary omits it.
limit: 1 to 100.
cursor: opaque value returned by the previous page.

Pass cursors back unchanged. Cursors belong to one region and filter set, so reset them when switching region. Requested teams outside the credential's access scope are not disclosed.

Snapshot Contract

Each team result includes teamId, teamName, snapshotVersion, computedAt, issues[], and summary counts.

snapshotVersion increases only when normalized open issue content changes.
computedAt also changes after a no-op reconciliation and indicates freshness.
Issue id is stable for one team and code.
Issue feature is a stable grouping key for partner-native queues. Current values are accounting, banking, billing, connections, listings, reconciliation, reservations, statements, and team.
If a resolved issue later reopens, its ID is reused and version increases.
summary.total counts open codes; affectedTotal sums their affected values.

Never parse issue title or message. Branch on code, feature, severity, category, and context. Use each issue's generated documentationUrl to open its catalog entry in the public documentation.

Mutation responses do not wait for portfolio-health recomputation. A successful write persists its audit record, then marks and schedules only health checks that depend on the changed resource types. Deferred effect mutations use the same immediate scheduling path after their health state is durable. Re-read GET /teams/issues until computedAt advances when a workflow needs the refreshed health state.

Checks that can change because time passed or an external system changed are also reconciled within a 15-minute window. Teams are spread deterministically across that window, so a regional portfolio is not recomputed in one burst. Pending work is durable and is drained by recovery if the immediate wake-up is missed. These scheduling details do not change the snapshot or issue lifecycle contract returned by the API.

Initial Materialization

If any team in the request scope lacks its first materialized snapshot, the whole request fails with 503 SERVICE_UNAVAILABLE; no partial result is returned for the teams that do have snapshots. The structured context lists only the affected teams in pendingTeamIds, with a retryAfterSeconds hint. A pending team is not silently treated as healthy. To recover, retry the same request after retryAfterSeconds, or scope teamIds to exclude the pending teams and read the rest immediately. Alert if materialization remains unavailable.

Task Ownership and Lifecycle

The API owns issue state. There are no close, reopen, or snooze mutations:

an issue is open while its catalog trigger is true;
it resolves and disappears from the response when the source condition is corrected;
it reopens with the same id and a higher version if that condition later returns; and
Hostaway may snooze a task in its own UI, but snooze never changes the API state. Reconsider a local snooze whenever the issue version changes.

Use feature to build queue sections and the code-specific context or catalog fetch guidance to open a repair workflow. VRPlatform does not return a Hostaway application URL because the parent application owns its navigation. documentationUrl points to technical guidance, not an in-product action.

Calendar reminders, month-end checklists, and other scheduled work are not issue codes. The partner application owns their cadence and presentation. Add an issue code only when VRPlatform can detect a current source condition and automatically resolve it after correction.

For analytics, treat (teamId, issue.id, version) and snapshot changes as the event identity. For support assistants, use documentationUrl, the generated catalog guidance, and current issue context; no separate AI-specific issue payload is required.

UI Pattern

Use summary view for portfolio queues. Fetch detail when a user opens a repair workflow. Keep region identity on every queue row if the UI combines regional responses. Replace current team state after every newer snapshot; do not retain resolved codes.

Exact contract: List team issues.