{ "openapi": "3.1.0", "info": { "title": "OpenApp agent API", "description": "Subset of the OpenApp HTTP API for agents: entity resolve, physical actions (preview + execute), invites, and audit. Do not expose scripting_execute.", "license": { "name": "Proprietary", "url": "https://openapp.house/" }, "version": "v1" }, "servers": [ { "url": "/api/v1", "description": "API v1 base path" } ], "paths": { "/agents": { "get": { "tags": [ "Agents" ], "operationId": "list_agents", "parameters": [ { "name": "limit", "in": "query", "description": "Number of items per page. Default from config, max 200.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 50 }, { "name": "offset", "in": "query", "description": "Number of items to skip. Default 0.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 0 } ], "responses": { "200": { "description": "Agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_AgentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Agents" ], "operationId": "create_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }, "required": true }, "responses": { "201": { "description": "Agent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/agents/{id}": { "get": { "tags": [ "Agents" ], "operationId": "get_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Agents" ], "operationId": "revoke_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoked" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Agents" ], "operationId": "update_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/agents/{id}/credentials": { "post": { "tags": [ "Agents" ], "operationId": "create_agent_credential", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentCredentialRequest" } } }, "required": true }, "responses": { "201": { "description": "Credential minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentCredentialResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/entities/{id}/actions/{action_id}": { "post": { "tags": [ "Entities" ], "summary": "Execute an entity action using the integration engine.", "description": "Execute an entity action. Quota: a `switchable.open` (door open) consumes 1 from `door_opens` (unit: count, per day and per month); when invoked via an API key it additionally consumes 1 from `voice_invocations` (unit: count, per day). When the org is over capacity, a degraded open may be delayed (the response carries a `degradation` warning) but is never blocked. An applicable `require_step_up` policy requires a prior authenticated preview or confirmation response; retry the same org, principal, entity, action, and JSON payload with its short-lived, single-use value in `X-OpenApp-Confirm`. The proof expires after 10 minutes and is not a separate second factor. Agents should also send `Idempotency-Key`. Success JSON includes `correlation_id`.", "operationId": "execute_entity_action", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "Action result (JSON)" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "409": { "description": "Confirmation required or idempotency conflict" }, "429": { "description": "Provider min_interval_ms between opens has not elapsed" }, "501": { "description": "Not implemented for provider" } }, "security": [ { "bearer_auth": [] } ] } }, "/entities/{id}/actions/{action_id}/preview": { "post": { "tags": [ "Entities" ], "summary": "Preview an entity action (Cedar + policies, no hardware call).", "operationId": "preview_entity_action", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "Preview decision (JSON). When confirmation is required, the response includes a short-lived, single-use `preview_token` bound to the authenticated principal, entity, action, and exact JSON payload; send it as `X-OpenApp-Confirm` on the matching execute request." } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites": { "get": { "tags": [ "Integrations" ], "summary": "List access invites for an integration.", "operationId": "list_integration_access_invites", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/PaginationQuery" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Paginated list of access invites", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_AccessInviteListItem" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Integrations" ], "summary": "Create an access invite granting portal_open on one or more portals.", "operationId": "create_integration_access_invite", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Created invite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessInviteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}": { "put": { "tags": [ "Integrations" ], "summary": "Update an access invite (portals, validity, max_uses). Only active invites can be updated.", "operationId": "update_integration_access_invite", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccessInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated invite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInviteListItem" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Integrations" ], "summary": "Delete an access invite (permanently).", "operationId": "delete_integration_access_invite", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invite deleted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/message-media": { "post": { "tags": [ "Integrations" ], "operationId": "post_access_invite_message_media", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Body image uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInviteMessageMediaResponse" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/message-media/{slot}": { "get": { "tags": [ "Integrations" ], "operationId": "get_access_invite_message_media", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Message media URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceImageUrlResponse" } } } }, "204": { "description": "No image for slot" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/photo": { "get": { "tags": [ "Integrations" ], "operationId": "get_access_invite_photo", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invite photo URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceImageUrlResponse" } } } }, "204": { "description": "No photo uploaded" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Integrations" ], "operationId": "post_access_invite_photo", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Photo uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceImageUrlResponse" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Integrations" ], "operationId": "delete_access_invite_photo", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Photo cleared" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/renewal-requests": { "get": { "tags": [ "Integrations" ], "summary": "List pending renewal requests for an access invite.", "operationId": "list_integration_access_invite_renewal_requests", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pending renewal requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccessInviteRenewalRequestsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/renewal-requests/{request_id}": { "delete": { "tags": [ "Integrations" ], "summary": "Dismiss a pending renewal request for an access invite.", "description": "Renewal requests have no binary approve/reject outcome — an admin may adjust\nthe schedule, issue a new invite, or take no action. Dismissing simply clears\nthe request from the pending list so it does not linger forever.", "operationId": "dismiss_integration_access_invite_renewal_request", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Renewal request dismissed" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/restore": { "post": { "tags": [ "Integrations" ], "summary": "Restore (un-revoke) an access invite.", "operationId": "restore_integration_access_invite", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Restored invite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInviteListItem" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/usage": { "get": { "tags": [ "Integrations" ], "summary": "`GET /integrations/{id}/access-invites/{invite_link_id}/usage`", "operationId": "list_integration_access_invite_usage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent uses of this invitation (last 30 days)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessUsageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/mcp": { "post": { "tags": [ "Agents" ], "operationId": "mcp_jsonrpc", "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/me/access-invites": { "get": { "tags": [ "Me" ], "operationId": "get_me_access_invites", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Access invites created by the current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeAccessInvitesResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/me/access-invites/{invite_id}": { "delete": { "tags": [ "Me" ], "operationId": "delete_me_access_invite", "parameters": [ { "name": "invite_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" } }, "security": [ { "bearer_auth": [] } ] } }, "/me/access-invites/{invite_id}/keep": { "post": { "tags": [ "Me" ], "operationId": "post_me_access_invite_keep", "parameters": [ { "name": "invite_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Kept" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/aliases": { "get": { "tags": [ "Agents" ], "operationId": "list_aliases", "parameters": [ { "name": "resource_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "resource_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aliases" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Agents" ], "operationId": "create_alias", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAliasRequest" } } }, "required": true }, "responses": { "201": { "description": "Alias created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/aliases/{id}": { "delete": { "tags": [ "Agents" ], "operationId": "delete_alias", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/audit/events": { "get": { "tags": [ "Audit" ], "operationId": "list_audit_events", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resource_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resource_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resource_name", "in": "query", "description": "Case-insensitive substring match on the resource's snapshotted display name\n(`details.resource_name`), e.g. `shelly`.", "required": false, "schema": { "type": "string" } }, { "name": "actor_user_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actor_guest_id", "in": "query", "description": "Filter to a single guest fingerprint. Disjoint from `actor_user_id`.", "required": false, "schema": { "type": "string" } }, { "name": "actor_kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "correlation_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "occurred_after", "in": "query", "description": "RFC 3339 lower bound (inclusive). Must be within the 30-day hot window.", "required": false, "schema": { "type": "string" } }, { "name": "occurred_before", "in": "query", "description": "RFC 3339 upper bound (inclusive).", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous page's `next_cursor`.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 50, max 200).", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Cursor-paginated audit events (last 30 days)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventsPage" } } } }, "400": { "description": "Range exceeds the 30-day hot window; use exports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/audit/exports": { "get": { "tags": [ "Audit" ], "operationId": "list_audit_exports", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export jobs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditExportJob" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Audit" ], "operationId": "create_audit_export", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuditExportRequest" } } }, "required": true }, "responses": { "202": { "description": "Export job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditExportJob" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/audit/exports/{job_id}": { "get": { "tags": [ "Audit" ], "operationId": "get_audit_export", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditExportJob" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/resolve": { "post": { "tags": [ "Agents" ], "operationId": "resolve_org_query", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } }, "required": true }, "responses": { "200": { "description": "Ranked candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "AccessInviteGrantedPortal": { "type": "object", "required": [ "id", "public_id", "name", "is_linked" ], "properties": { "id": { "type": "string" }, "is_linked": { "type": "boolean", "description": "Whether the portal currently resolves to a live door device. When false the portal\nis misconfigured/unlinked and the invite UI shows it in a warning state." }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "public_id": { "type": "string" } } }, "AccessInviteKind": { "type": "string", "enum": [ "invitation", "share" ] }, "AccessInviteListItem": { "type": "object", "required": [ "id", "state", "is_enabled", "schedule_kind", "schedule_combined", "schedule_entries", "schedule", "uses", "location_mode", "granted_portals" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "created_by_user_id": { "type": [ "string", "null" ], "description": "User who created this invite or share. Omitted when the row has no creator." }, "creation_justification": { "type": [ "string", "null" ] }, "curfew_exempt": { "type": "boolean", "description": "Admin-only emergency exception: skip invitation curfew at redemption." }, "devices_count": { "type": [ "integer", "null" ], "format": "int32" }, "disabled_justification": { "type": [ "string", "null" ] }, "granted_portals": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteGrantedPortal" } }, "id": { "type": "string" }, "invite_recurrence": {}, "invitee_message": {}, "is_enabled": { "type": "boolean" }, "kind": { "$ref": "#/components/schemas/AccessInviteKind" }, "last_shared_at": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ] }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationResponse", "description": "Resolved event location for this invite (see `location_mode`): the invite's own\nlocation when `explicit`, the building location when `inherit`, or absent when `none`." } ] }, "location_mode": { "$ref": "#/components/schemas/LocationBindingMode", "description": "How the event location is resolved: `none`, `explicit`, or `inherit` (building)." }, "max_devices": { "type": [ "integer", "null" ], "format": "int32" }, "max_uses": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": [ "string", "null" ] }, "pending_renewal_count": { "type": [ "integer", "null" ], "format": "int32" }, "photo_url": { "type": [ "string", "null" ], "description": "Presigned URL for the invite's main photo (best-effort)." }, "revoked_at": { "type": [ "string", "null" ] }, "schedule": { "$ref": "#/components/schemas/InviteScheduleSnapshot" }, "schedule_combined": { "$ref": "#/components/schemas/InviteScheduleCombined" }, "schedule_entries": { "type": "array", "items": { "$ref": "#/components/schemas/InviteScheduleEntrySnapshot" } }, "schedule_kind": { "$ref": "#/components/schemas/InviteScheduleKind" }, "state": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] }, "uses": { "type": "integer", "format": "int32" }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] } } }, "AccessInviteMessageMediaResponse": { "type": "object", "required": [ "slot", "url", "expires_in_seconds" ], "properties": { "expires_in_seconds": { "type": "integer", "format": "int64", "minimum": 0 }, "slot": { "type": "string" }, "url": { "type": "string" } } }, "AccessInviteRenewalRequestItem": { "type": "object", "required": [ "id", "requester_user_id" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "requester_name": { "type": [ "string", "null" ] }, "requester_user_id": { "type": "string" } } }, "AccessPortalListItem": { "type": "object", "required": [ "id", "public_id", "name" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ], "description": "When set, the portal is soft-deleted (kept for restore)." }, "device_id": { "type": [ "string", "null" ], "description": "Door device id (virtual_access_portal in this integration). Canonical portal link key." }, "directory_id": { "type": [ "string", "null" ], "description": "Directory device id (virtual_access_directory in this integration)." }, "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "public_id": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } } }, "AccessUsageEntry": { "type": "object", "description": "One friendly usage row.", "required": [ "id", "occurred_at", "outcome", "actor" ], "properties": { "actor": { "$ref": "#/components/schemas/UsageActor" }, "door_name": { "description": "Localized door/action name (plain string or `{ locale: name }`). Set on invite-usage rows." }, "id": { "type": "string", "description": "Source audit event id (ULID)." }, "invite_name": { "description": "Localized invitation name. Set on door-usage rows opened via an invitation." }, "occurred_at": { "type": "string", "description": "RFC 3339 timestamp of the event." }, "outcome": { "type": "string", "description": "`succeeded` | `failed` | `denied`." } } }, "AccessUsageResponse": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AccessUsageEntry" }, "description": "Newest first." } } }, "AddApartmentResidentPayload": { "type": "object", "required": [ "user_id" ], "properties": { "date_of_birth": { "type": [ "string", "null" ], "description": "Parent-declared date of birth (`YYYY-MM-DD`). Required when `is_child` is true." }, "is_child": { "type": [ "boolean", "null" ], "description": "When true, this household member is a child; date of birth is required." }, "receives_calls": { "type": [ "boolean", "null" ], "description": "When omitted, defaults to false for minors and true for adults." }, "role": { "type": "string" }, "user_id": { "type": "string" } }, "additionalProperties": false }, "AddBillingMemberRequest": { "type": "object", "required": [ "user_id" ], "properties": { "can_charge": { "type": [ "boolean", "null" ] }, "user_id": { "type": "string" } }, "additionalProperties": false }, "AddBuildingUserPayload": { "type": "object", "required": [ "user_id", "role" ], "properties": { "role": { "type": "string" }, "user_id": { "type": "string" } }, "additionalProperties": false }, "AddMemberRequest": { "type": "object", "required": [ "user_id" ], "properties": { "display_name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString", "description": "Localized display name used to label the member's auto-created personal billing account." } ] }, "role": { "type": [ "string", "null" ] }, "user_id": { "type": "string" } }, "additionalProperties": false }, "AddRolesRequest": { "type": "object", "description": "Request type for adding/deleting roles (org_id -> list of role names).", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "propertyNames": { "type": "string" } }, "AffectedCounts": { "type": "object", "description": "Per-resource counts of the rows a transfer affects. Used both for the preview endpoint and to\ngate target-org quota before any write happens.", "required": [ "devices", "zones", "entities", "access_portals", "apartment_residents", "invite_links", "invite_claims", "renewal_requests", "sessions" ], "properties": { "access_portals": { "type": "integer", "format": "int64" }, "apartment_residents": { "type": "integer", "format": "int64" }, "devices": { "type": "integer", "format": "int64" }, "entities": { "type": "integer", "format": "int64" }, "invite_claims": { "type": "integer", "format": "int64", "description": "Ephemeral runtime rows; relevant to MOVE only (DUPLICATE does not clone them)." }, "invite_links": { "type": "integer", "format": "int64" }, "renewal_requests": { "type": "integer", "format": "int64" }, "sessions": { "type": "integer", "format": "int64" }, "zones": { "type": "integer", "format": "int64" } } }, "AgeClass": { "type": "string", "description": "Derived age class for call/portal limits. Not a marketing segment.", "enum": [ "under_13", "13_to_15", "adult" ] }, "AgentResponse": { "type": "object", "required": [ "id", "org_id", "owner_user_id", "name", "confirmation_mode" ], "properties": { "allowed_entity_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_portal_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_tool_names": { "type": [ "array", "null" ], "items": { "type": "string" } }, "confirmation_mode": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "org_id": { "type": "string" }, "owner_user_id": { "type": "string" }, "purpose": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "AliasResponse": { "type": "object", "required": [ "id", "org_id", "resource_type", "resource_id", "alias" ], "properties": { "alias": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "org_id": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" } } }, "ApartmentEnrichRequest": { "type": "object", "description": "Documented multipart body (`integration_id` plus `images`, `images[]`, or `file`).", "required": [ "integration_id", "images" ], "properties": { "images": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "One or more door / intercom photos." }, "integration_id": { "type": "string", "description": "Virtual access integration ULID." } } }, "ApartmentFloorListResponse": { "type": "object", "description": "Distinct apartment floors for a directory device (efficient SQL).", "required": [ "floors" ], "properties": { "floors": { "type": "array", "items": { "$ref": "#/components/schemas/ApartmentFloorSummary" } } } }, "ApartmentFloorSummary": { "type": "object", "description": "One distinct floor row for a directory device (apartment entities).", "required": [ "key", "floor" ], "properties": { "floor": {}, "floor_number": { "type": [ "integer", "null" ], "format": "int64" }, "key": { "type": "string" } } }, "ApartmentResidentResponse": { "type": "object", "required": [ "entity_id", "user_id", "org_id", "integration_id", "role", "receives_calls" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "entity_id": { "type": "string" }, "integration_id": { "type": "string" }, "org_id": { "type": "string" }, "receives_calls": { "type": "boolean" }, "role": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] }, "user_id": { "type": "string" } } }, "ApartmentResidentWithUserResponse": { "type": "object", "required": [ "resident" ], "properties": { "age_class": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgeClass", "description": "Derived age class. Only set for apartment managers." } ] }, "date_of_birth": { "type": [ "string", "null" ], "description": "Calendar date `YYYY-MM-DD`. Only set for apartment managers." }, "resident": { "$ref": "#/components/schemas/ApartmentResidentResponse" }, "user_email": { "type": [ "string", "null" ] }, "user_name": {} } }, "ApiErrorResponse": { "type": "object", "description": "A minimal, user-facing error body for public API responses.", "required": [ "message" ], "properties": { "correlationId": { "type": [ "string", "null" ], "description": "Server-generated correlation id that ties this error to the request trace and the\nmatching audit event (see the audit log). Present when the request carried one." }, "error_code": { "type": [ "string", "null" ], "description": "Optional stable code for clients to branch on (e.g. \"door_unreachable\")." }, "message": { "type": "string" }, "preview_token": { "type": [ "string", "null" ], "description": "Present when `error_code` is `confirmation_required` (retry with `X-OpenApp-Confirm`)." } } }, "ApiKeyListItem": { "type": "object", "description": "Response for API key list item (no token).", "required": [ "id", "name", "token_suffix", "base_url", "expires_at" ], "properties": { "base_url": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ] }, "scoped_entity_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scoped_roles": { "type": [ "array", "null" ], "items": { "type": "string" } }, "token_suffix": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } } }, "ApprovalDecisionResponse": { "type": "object", "required": [ "id", "status" ], "properties": { "approve_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "id": { "type": "string" }, "required_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "status": { "type": "string" } } }, "ApprovalRequestResponse": { "type": "object", "required": [ "id", "policy_id", "org_id", "requester_user_id" ], "properties": { "approve_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "created_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "policy_id": { "type": "string" }, "requester_user_id": { "type": "string" }, "required_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "status": { "type": [ "string", "null" ] }, "subject_kind": { "type": [ "string", "null" ], "description": "What the request is about, e.g. `invite`." }, "subject_label": { "type": [ "string", "null" ], "description": "Human-readable subject (invite name), not the raw kind/ref." }, "subject_ref": { "type": [ "string", "null" ], "description": "Id of the subject (e.g. the disabled invite link awaiting approval)." } } }, "ApprovalThresholdPolicyConfig": { "type": "object", "description": "Typed `config` shape for `approval_threshold`.", "required": [ "count", "scope" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "Number of distinct organization-admin approve votes required.", "minimum": 1 }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Optional provider-derived output/channel selector." } ] }, "scope": { "$ref": "#/components/schemas/ApprovalThresholdScope", "description": "Only `org_admins` is currently supported." } } }, "ApprovalThresholdScope": { "type": "string", "enum": [ "org_admins" ] }, "AuditEventsPage": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditRecord" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next (older) page, or null when the last page was returned." } } }, "AuditExportJob": { "type": "object", "required": [ "id", "org_id", "status", "format" ], "properties": { "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "download_url": { "type": [ "string", "null" ], "description": "Signed download URL, present only when `status = completed`." }, "error_message": { "type": [ "string", "null" ] }, "format": { "type": "string" }, "id": { "type": "string" }, "occurred_after": { "type": [ "string", "null" ] }, "occurred_before": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "row_count": { "type": [ "integer", "null" ], "format": "int64" }, "status": { "type": "string" } } }, "AuditOutcome": { "type": "string", "description": "Outcome of an audited action. `denied` (permission/quota refusal) is recorded too —\nit is critical for security investigations.", "enum": [ "succeeded", "failed", "denied" ] }, "AuditRecord": { "type": "object", "description": "A persisted audit event. Serialized shape doubles as the webhook payload and the pull-API\nresponse item.", "required": [ "id", "occurred_at", "org_id", "actor_kind", "event_type", "outcome", "source", "details" ], "properties": { "actor_agent_id": { "type": [ "string", "null" ] }, "actor_api_key_id": { "type": [ "string", "null" ] }, "actor_guest_id": { "type": [ "string", "null" ], "description": "Stable, client-supplied per-device guest fingerprint (ULID). Deliberately kept in its own\nfield, NEVER `actor_user_id`: a guest id is spoofable and must never be readable as a\ntrusted (registered) user identity, nor collide with the user-id population." }, "actor_kind": { "type": "string" }, "actor_user_id": { "type": [ "string", "null" ] }, "correlation_id": { "type": [ "string", "null" ] }, "details": {}, "event_type": { "type": "string" }, "id": { "type": "string", "description": "ULID; also the webhook idempotency key." }, "occurred_at": { "type": "string", "format": "date-time" }, "org_id": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/AuditOutcome" }, "resource_id": { "type": [ "string", "null" ] }, "resource_type": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/AuditSource" } } }, "AuditSource": { "type": "string", "description": "Surface that originated the action.", "enum": [ "api", "dashboard", "public_access", "smarthome", "scripting", "system" ] }, "BackendStatus": { "type": "object", "required": [ "environment", "version" ], "properties": { "environment": { "type": "string", "description": "Runtime environment (e.g. development, production)." }, "version": { "type": "string", "description": "Application version from Cargo." } } }, "BillingAccount": { "type": "object", "description": "The billable entity for purchases. By default each member has a personal account; grouping\nmultiple users into one account lets one user be billed to another's account.", "required": [ "id", "org_id", "name" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "org_id": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } } }, "BillingAccountMember": { "type": "object", "description": "A user attached to a billing account. `can_charge` allows charging the account.", "required": [ "account_id", "user_id", "can_charge" ], "properties": { "account_id": { "type": "string" }, "can_charge": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "user_id": { "type": "string" } } }, "BillingEvent": { "type": "object", "description": "Provider-emitted event after webhook validation. Handlers translate this into\ninternal state (e.g. `billing_subscriptions` rows, tier_id changes on the org).", "required": [ "kind", "provider", "raw" ], "properties": { "external_customer_id": { "type": [ "string", "null" ] }, "external_subscription_id": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/BillingEventKind" }, "provider": { "type": "string" }, "raw": {}, "status": { "type": [ "string", "null" ] }, "tier_slug": { "type": [ "string", "null" ] } } }, "BillingEventKind": { "type": "string", "enum": [ "subscription_created", "subscription_updated", "subscription_canceled", "invoice_paid", "invoice_failed", "other" ] }, "BillingPlanResponse": { "type": "object", "required": [ "org_id" ], "properties": { "org_id": { "type": "string" }, "subscription": {}, "tier_id": { "type": [ "string", "null" ] } } }, "BuildingUserResponse": { "type": "object", "required": [ "user_id", "role", "apartments" ], "properties": { "apartments": { "type": "array", "items": { "type": "string" } }, "role": { "type": "string" }, "user_email": { "type": [ "string", "null" ] }, "user_id": { "type": "string" }, "user_name": {} } }, "CapacityResource": { "type": "string", "description": "A capacity-tracked resource type that participates in the lifecycle. (Org members are\nintentionally excluded — they are never auto-deleted.)", "enum": [ "integrations", "devices", "zones", "entities", "api_keys" ] }, "CheckoutRequest": { "type": "object", "required": [ "tier_slug" ], "properties": { "tier_slug": { "type": "string" } }, "additionalProperties": false }, "ConflictingInviteResponse": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "CopilotChatRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "CopilotChatResponse": { "type": "object", "required": [ "replies", "proposed_actions", "correlation_id" ], "properties": { "correlation_id": { "type": "string" }, "proposed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/CopilotProposedAction" } }, "replies": { "type": "array", "items": { "type": "string" } } } }, "CopilotCommitRequest": { "type": "object", "required": [ "actions" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/CopilotProposedAction" } } } }, "CopilotCommitResponse": { "type": "object", "required": [ "results", "correlation_id" ], "properties": { "correlation_id": { "type": "string" }, "results": { "type": "array", "items": {} } } }, "CopilotProposedAction": { "type": "object", "required": [ "tool", "args" ], "properties": { "args": { "type": "object" }, "preview": { "type": [ "string", "null" ] }, "tool": { "type": "string" } } }, "CopyDeviceImageRequest": { "type": "object", "required": [ "source_device_id" ], "properties": { "source_device_id": { "type": "string" } }, "additionalProperties": false }, "CopyEntityImageRequest": { "type": "object", "required": [ "source_entity_id" ], "properties": { "source_entity_id": { "type": "string" } }, "additionalProperties": false }, "CopyIntegrationImageRequest": { "type": "object", "required": [ "source_integration_id" ], "properties": { "source_integration_id": { "type": "string" } }, "additionalProperties": false }, "CreateAccessInviteRequest": { "type": "object", "required": [ "portal_ids" ], "properties": { "creation_justification": { "type": [ "string", "null" ], "description": "Why this invitation is being created (required when `invitation_require_justification` applies)." }, "curfew_exempt": { "type": [ "boolean", "null" ], "description": "Admin-only emergency exception: skip invitation curfew at redemption." }, "expires_in": { "type": [ "string", "null" ], "description": "Duration per [RFC 5545 §3.3.6](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.6) (ISO 8601 `P1D`, `PT1H`, …; no months/years) or compact tokens `s`/`m`/`h`/`d`/`w` (`M` is minutes). Max 3650d (10 years). `1y` is rejected. Measured from resolved start (including now when `valid_from` is omitted). Mutually exclusive with `valid_to`." }, "has_photo": { "type": [ "boolean", "null" ], "description": "True when the client will upload a photo immediately after create (media is a follow-up POST)." }, "invite_recurrence": {}, "invitee_message": {}, "invitee_phone": { "type": [ "string", "null" ], "description": "Invitee E.164 phone. Required when `invitation_require_identity.require_verified_phone`.\nJSON `null` means no phone." }, "is_enabled": { "type": [ "boolean", "null" ] }, "kind": { "$ref": "#/components/schemas/AccessInviteKind" }, "location_id": { "type": [ "string", "null" ], "description": "Reusable org-scoped location id to bind, only consumed when `location_mode` is `explicit`.\nCreate the location first via the locations API (which can geocode it), then reference it here." }, "location_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationBindingMode", "description": "How the event location is resolved. Defaults to `inherit` (use the building location) when\nomitted. `explicit` binds to the reusable org location referenced by `location_id`; `none`\nshows no event location." } ] }, "max_devices": { "type": [ "integer", "null" ], "format": "int32", "description": "Virtual keycard limit: max unique devices allowed to redeem/use this invite. JSON `null` or omitted means unlimited." }, "max_uses": { "type": [ "integer", "null" ], "format": "int32", "description": "Omit to apply the share default (or leave invitations unlimited). JSON `null` means unlimited." }, "name": { "type": [ "string", "null" ] }, "pin": { "type": [ "string", "null" ], "description": "Host-chosen PIN (stored hashed). Required when `invitation_require_identity.require_pin`.\nJSON `null` means no PIN; omission leaves the create default unchanged." }, "portal_ids": { "type": "array", "items": { "type": "string" }, "description": "Portal ULIDs to grant. Array order is the display order on the public invite page." }, "schedules": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/InviteScheduleEntryInput" }, "description": "When set (non-empty), defines one or more schedule entries; legacy `valid_from` /\n`valid_to` / `invite_recurrence` are ignored for scheduling." }, "valid_from": { "type": [ "string", "null" ], "description": "[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) window start (UTC). When omitted, the window opens at request time." }, "valid_to": { "type": [ "string", "null" ], "description": "[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) window end (UTC). Mutually exclusive with `expires_in`." } }, "additionalProperties": false }, "CreateAccessInviteResponse": { "type": "object", "required": [ "invite_link_id", "invite_token", "invite_url", "valid_from", "valid_to", "is_enabled", "schedule_kind", "schedule_combined", "schedule_entries", "schedule", "uses", "location_mode", "granted_portals" ], "properties": { "creation_justification": { "type": [ "string", "null" ] }, "curfew_exempt": { "type": "boolean", "description": "Admin-only emergency exception: skip invitation curfew at redemption." }, "curfew_windows": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CurfewWindowResponse" }, "description": "Effective forbidden hour windows (informational; invites are never mutated)." }, "devices_count": { "type": [ "integer", "null" ], "format": "int32" }, "granted_portals": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteGrantedPortal" } }, "invite_link_id": { "type": "string" }, "invite_recurrence": {}, "invite_token": { "type": "string" }, "invite_url": { "type": "string", "description": "Guest-facing invite URL (shareable link for SMS/email)." }, "invitee_message": {}, "is_enabled": { "type": "boolean" }, "kind": { "$ref": "#/components/schemas/AccessInviteKind" }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationResponse", "description": "Resolved event location for this invite (see `location_mode`)." } ] }, "location_mode": { "$ref": "#/components/schemas/LocationBindingMode", "description": "How the event location is resolved: `none`, `explicit`, or `inherit` (building)." }, "max_devices": { "type": [ "integer", "null" ], "format": "int32" }, "max_uses": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": [ "string", "null" ] }, "pending_approval": { "type": "boolean", "description": "True when a `user_sharing` policy required admin approval: the invite was created disabled\nand an approval request is pending. The invite activates once an admin approves it." }, "schedule": { "$ref": "#/components/schemas/InviteScheduleSnapshot" }, "schedule_combined": { "$ref": "#/components/schemas/InviteScheduleCombined" }, "schedule_entries": { "type": "array", "items": { "$ref": "#/components/schemas/InviteScheduleEntrySnapshot" } }, "schedule_kind": { "$ref": "#/components/schemas/InviteScheduleKind" }, "timezone": { "type": [ "string", "null" ], "description": "Org IANA timezone used to evaluate invitation curfews." }, "uses": { "type": "integer", "format": "int32" }, "valid_from": { "type": "string" }, "valid_to": { "type": "string" } } }, "CreateAccessPortalRequest": { "type": "object", "required": [ "name" ], "properties": { "device_id": { "type": [ "string", "null" ], "description": "Door device id (virtual_access_portal device in this integration). Links the portal to a door." }, "directory_id": { "type": [ "string", "null" ], "description": "Directory device id (virtual_access_directory in this integration)." }, "name": { "$ref": "#/components/schemas/LocalizedString", "description": "Portal display name (localized). Accepts string or object e.g. { \"en\": \"Lobby\", \"he\": \"לובי\" }." } }, "additionalProperties": false }, "CreateAccessPortalResponse": { "type": "object", "required": [ "id", "public_id", "name" ], "properties": { "device_id": { "type": [ "string", "null" ] }, "directory_id": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "public_id": { "type": "string" } } }, "CreateAgentCredentialRequest": { "type": "object", "properties": { "expires_at": { "type": [ "string", "null" ] }, "expires_in": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "CreateAgentCredentialResponse": { "type": "object", "required": [ "agent_id", "api_key_id", "token", "token_suffix", "expires_at" ], "properties": { "agent_id": { "type": "string" }, "api_key_id": { "type": "string" }, "expires_at": { "type": "string" }, "token": { "type": "string" }, "token_suffix": { "type": "string" } } }, "CreateAgentRequest": { "type": "object", "required": [ "name" ], "properties": { "allowed_entity_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_portal_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_tool_names": { "type": [ "array", "null" ], "items": { "type": "string" } }, "confirmation_mode": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "expires_in": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "purpose": { "type": [ "string", "null" ] } } }, "CreateAliasRequest": { "type": "object", "required": [ "resource_type", "resource_id", "alias" ], "properties": { "alias": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "expires_at": { "type": [ "string", "null" ], "description": "[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) absolute expiration timestamp (UTC). Mutually exclusive with `expires_in`." }, "expires_in": { "type": [ "string", "null" ], "description": "Duration per [RFC 5545 §3.3.6](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.6) (ISO 8601 `P1D`, `PT1H`, …; no months/years) or compact tokens `s`/`m`/`h`/`d`/`w` (`M` is minutes). Max 3650d (10 years). `1y` is rejected. Mutually exclusive with `expires_at`." }, "name": { "type": "string" }, "scoped_entity_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scoped_roles": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "CreateApiKeyResponse": { "type": "object", "description": "Response for API key creation (token shown once).", "required": [ "id", "name", "token_suffix", "base_url", "expires_at" ], "properties": { "base_url": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "scoped_entity_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scoped_roles": { "type": [ "array", "null" ], "items": { "type": "string" } }, "token": { "type": [ "string", "null" ] }, "token_suffix": { "type": "string" } } }, "CreateAuditExportRequest": { "type": "object", "properties": { "format": { "type": [ "string", "null" ], "description": "Output format: `jsonl` (default) or `csv`." }, "occurred_after": { "type": [ "string", "null" ], "description": "RFC 3339 lower bound (inclusive). Defaults to the start of retention." }, "occurred_before": { "type": [ "string", "null" ], "description": "RFC 3339 upper bound (inclusive). Defaults to now." } }, "additionalProperties": false }, "CreateBillingAccountRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "$ref": "#/components/schemas/LocalizedString" } }, "additionalProperties": false }, "CreateDeviceRequest": { "type": "object", "required": [ "org_id", "name", "integration_id" ], "properties": { "device_metadata": {}, "external_id": { "type": [ "string", "null" ] }, "integration_id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "org_id": { "type": "string" } }, "additionalProperties": false }, "CreateEntityRequest": { "type": "object", "required": [ "device_id", "entity_type" ], "properties": { "channel_index": { "type": [ "integer", "null" ], "format": "int32" }, "device_id": { "type": "string" }, "entity_type": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "description": "Arbitrary, persisted entity metadata (integration-specific).\n\nFor example, MQTT entities can store:\n- `command_topic`\n- `toggle_payload`\n\nValues are converted to strings (non-strings are JSON-stringified) to match `domain::Metadata`.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "Optional friendly name for the entity." }, "zone_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CreateIntegrationRequest": { "type": "object", "required": [ "org_id", "provider_type" ], "properties": { "config": {}, "enabled": { "type": "boolean" }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString", "description": "Human-friendly name for this integration (optional; defaults server-side).\nAccepts string or LocalizedString map, e.g. { \"en\": \"Name\", \"he\": \"שם\" }." } ] }, "non_admin_acknowledgment": { "description": "Required when `linked_account_admin` is `warn_and_ack` and the PalGate probe is non-admin." }, "org_id": { "type": "string" }, "provider_type": { "type": "string" }, "secrets": {} }, "additionalProperties": false }, "CreateInventoryRequest": { "type": "object", "required": [ "product_id", "price_cents" ], "properties": { "is_active": { "type": [ "boolean", "null" ] }, "price_cents": { "type": "integer", "format": "int64" }, "product_id": { "type": "string" }, "stock_quantity": { "type": [ "integer", "null" ], "format": "int32" } }, "additionalProperties": false }, "CreateInvitationRequest": { "type": "object", "properties": { "default_roles": { "type": "array", "items": { "type": "string" }, "description": "Roles to assign on accept (within the inviting org)." }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "site_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvitationSiteAccessDto", "description": "Optional site (and apartment) access applied atomically when the invitation is redeemed." } ] } }, "additionalProperties": false }, "CreateInvitationResponse": { "type": "object", "required": [ "invitation", "redeem_url" ], "properties": { "invitation": { "$ref": "#/components/schemas/UserInvitationDto" }, "redeem_url": { "type": "string", "description": "Shareable redeem URL — surfaced once so the inviter can hand it off out-of-band\n(the PIN is never returned here)." } } }, "CreateLocationRequest": { "type": "object", "required": [ "kind" ], "properties": { "city": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "formatted_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "geocode": { "type": "boolean" }, "kind": { "$ref": "#/components/schemas/LocationKind" }, "lat": { "type": [ "number", "null" ], "format": "double" }, "lng": { "type": [ "number", "null" ], "format": "double" }, "locale": { "type": [ "string", "null" ], "description": "Preferred locale (app code or BCP-47) for geocoding: controls the language of geocoded\ntext and the locale key it is tagged under. Defaults to `en` when omitted." }, "notes": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "place_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CreateOrganizationRequest": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ], "description": "Optional ID parameter (admin-only, not documented in API docs)." }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "parent_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CreatePmsConnectorRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } } }, "CreatePmsConnectorResponse": { "type": "object", "required": [ "id", "name", "provider", "webhook_url_path", "webhook_secret" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "webhook_secret": { "type": "string" }, "webhook_url_path": { "type": "string" } } }, "CreatePolicyRequest": { "type": "object", "required": [ "policy_type", "config" ], "properties": { "capability": { "type": [ "string", "null" ], "description": "Optional capability scoping (e.g. `switchable`, `users_admin`)." }, "config": { "type": "object", "description": "Typed-per-`policy_type` configuration document. For the documented typed\nshapes, see `RequireStepUpPolicyConfig` and `ApprovalThresholdPolicyConfig`." }, "enabled": { "type": [ "boolean", "null" ], "description": "Defaults to true." }, "enforcement": { "type": [ "string", "null" ], "description": "`enforce` (default) | `require_approval` | `audit_only`." }, "policy_type": { "type": "string", "description": "e.g. `invitation_curfew`, `user_sharing`." } }, "additionalProperties": false }, "CreatePortalRequest": { "type": "object", "required": [ "name" ], "properties": { "branding_overrides": { "type": [ "object", "null" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" } }, "additionalProperties": false }, "CreateSkillRequest": { "type": "object", "required": [ "name", "agent_id", "trigger_event_types", "steps" ], "properties": { "agent_id": { "type": "string" }, "enabled": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SkillStep" } }, "trigger_event_types": { "type": "array", "items": { "type": "string" } } } }, "CreateStoreRequest": { "type": "object", "required": [ "name" ], "properties": { "branding_overrides": { "type": [ "object", "null" ] }, "currency": { "type": [ "string", "null" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "timezone": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CreateUserRequest": { "type": "object", "required": [ "name" ], "properties": { "email": { "type": [ "string", "null" ], "description": "Login email. Omit for phone-only provisioning (Kratos uses `traits.phone` only; OpenApp\nstores a synthetic `{id}@phone.openapp.local` placeholder in `users.email`)." }, "first_name": { "type": [ "string", "null" ], "description": "Given name stored on the Kratos identity (`traits.name.first`) when creating the account." }, "id": { "type": [ "string", "null" ], "description": "Optional ID parameter (admin-only, not documented in API docs)\nThis field is intentionally not included in OpenAPI documentation" }, "last_name": { "type": [ "string", "null" ], "description": "Family name stored on the Kratos identity (`traits.name.last`) when creating the account." }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "password": { "type": [ "string", "null" ], "description": "Optional password for Kratos identity (provisioning only; same permission as id).\nWhen set, the Kratos identity is created with this password so the user can log in immediately." }, "phone": { "type": [ "string", "null" ], "description": "E.164 phone (`+[country][digits]`). When set, must satisfy the same pattern as Kratos." }, "roles": { "type": [ "object", "null" ], "description": "Org ID (string) to list of role names. Optional." } }, "additionalProperties": false }, "CreateWebhookRequest": { "type": "object", "required": [ "url" ], "properties": { "description": { "type": [ "string", "null" ] }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Event-type filter; omit or empty for all events." }, "url": { "type": "string" } }, "additionalProperties": false }, "CreateWebhookResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "signing_secret" ], "properties": { "signing_secret": { "type": "string", "description": "The HMAC signing secret, returned exactly once at creation. Store it securely; it is used to\nverify the `X-OpenApp-Signature` header on every delivery and is never returned again." } } } ] }, "CreateZoneRequest": { "type": "object", "required": [ "integration_id", "name" ], "properties": { "external_id": { "type": [ "string", "null" ] }, "integration_id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "parent_zone_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CurfewWindowResponse": { "type": "object", "required": [ "start", "end" ], "properties": { "end": { "type": "string", "description": "Local clock `HH:MM`. Inclusive; may be earlier than `start` (midnight wrap)." }, "start": { "type": "string", "description": "Local clock `HH:MM`." } } }, "DecideRegistrationRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "description": "`approve` or `reject`." }, "display_name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString", "description": "Optional localized display name for the new member's personal billing account." } ] } }, "additionalProperties": false }, "DegradationStage": { "type": "string", "description": "Lifecycle position of an org's over-capacity remediation.", "enum": [ "none", "warned", "degraded", "marked_for_delete" ] }, "DegradationStatus": { "type": "object", "description": "Full degradation snapshot for an org. Powers the dashboard panel + non-admin friction.", "required": [ "org_id", "stage", "degradation_level", "over_capacity", "selection_policy", "overages", "flagged" ], "properties": { "degradation_level": { "type": "number", "format": "float" }, "flagged": { "type": "array", "items": { "$ref": "#/components/schemas/FlaggedResource" } }, "org_id": { "type": "string" }, "over_capacity": { "type": "boolean" }, "over_capacity_since": { "type": [ "string", "null" ] }, "overages": { "type": "array", "items": { "$ref": "#/components/schemas/KeyOverage" } }, "selection_policy": { "$ref": "#/components/schemas/SelectionPolicy" }, "stage": { "$ref": "#/components/schemas/DegradationStage" } } }, "DeleteRolesRequest": { "type": "object", "description": "Request type for deleting roles (org_id -> list of role names).", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "propertyNames": { "type": "string" } }, "DeletionRequestResponse": { "type": "object", "required": [ "status", "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "string" } } }, "Device": { "allOf": [ { "$ref": "#/components/schemas/ResourceLifecycle" }, { "type": "object", "required": [ "id", "org_id", "name", "integration_id" ], "properties": { "device_metadata": { "description": "Device-specific JSON metadata (stored in Postgres `devices.metadata` JSONB column)." }, "external_id": { "type": [ "string", "null" ], "description": "External ID from the integration provider." }, "id": { "type": "string", "description": "Unique identifier (ULID)." }, "integration_id": { "type": "string", "description": "Owning integration (e.g. Shelly Cloud account/connection)." }, "name": { "$ref": "#/components/schemas/LocalizedString", "description": "Human-readable name." }, "org_id": { "type": "string", "description": "Organization that owns this device." } } } ], "description": "A physical or virtual device belonging to an org and integration." }, "DeviceEntityMetadataDefinitionQuery": { "type": "object", "required": [ "entity_type" ], "properties": { "entity_type": { "type": "string" } } }, "DeviceMetadataDefinitionResponse": { "type": "object", "description": "Device metadata definition response (schema + current data) for schema-driven edit UI.", "required": [ "provider_type", "schema", "data" ], "properties": { "data": { "description": "Current `device_metadata` as a JSON object." }, "provider_type": { "type": "string" }, "schema": { "description": "JSON Schema describing `devices.device_metadata` shape for this provider." } } }, "DevicePhysicalStatusResponse": { "type": "object", "required": [ "provider_supports_steward", "has_steward", "is_steward", "can_claim", "is_primary_instance" ], "properties": { "admin_status": { "type": [ "string", "null" ], "description": "Verified hardware-admin status of the integration's linked account: `admin` | `non_admin` |\nnull (unknown / unverifiable / stale)." }, "can_claim": { "type": "boolean", "description": "Whether the requester may claim/keep stewardship (verified admin + provider supports it +\nnot held by someone else)." }, "hardware_id": { "type": [ "string", "null" ], "description": "Server-derived hardware identity of the device (controller-level), if any." }, "has_steward": { "type": "boolean", "description": "Whether some user currently holds the steward slot for this physical device." }, "is_primary_instance": { "type": "boolean", "description": "Whether this OpenApp device record is the canonical (primary) instance for the hardware." }, "is_steward": { "type": "boolean", "description": "Whether the requesting user currently holds the steward slot." }, "physical_device_id": { "type": [ "string", "null" ], "description": "The physical-device registry id, once the device has been registered/claimed." }, "provider_supports_steward": { "type": "boolean", "description": "Whether the provider supports the device-steward authority tier at all." } } }, "DeviceResponse": { "allOf": [ { "$ref": "#/components/schemas/Device" }, { "type": "object", "properties": { "is_primary_instance": { "type": [ "boolean", "null" ], "description": "Server-computed, read-only: true when this OpenApp device record is the canonical\n(primary) instance for its physical hardware in the global `physical_devices` registry.\nNever accepted from a request body. See `docs/POLICIES_HDD.md` §6.3." }, "stale": { "type": [ "boolean", "null" ], "description": "Present when `include_stale=true` was requested and the provider supports stale detection." } } } ] }, "DoorHoldResponse": { "type": "object", "required": [ "mixed", "include_lights", "openers", "lights", "timezone" ], "properties": { "hold": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HoldView" } ] }, "include_lights": { "type": "boolean" }, "lights": { "type": "array", "items": { "$ref": "#/components/schemas/EntityHoldItem" } }, "mixed": { "type": "boolean" }, "mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HoldMode" } ] }, "openers": { "type": "array", "items": { "$ref": "#/components/schemas/EntityHoldItem" } }, "timezone": { "type": "string", "description": "Organization IANA timezone used when authoring a new recurring hold." } } }, "DoorRestrictionsResponse": { "type": "object", "required": [ "apartment_entity_ids" ], "properties": { "apartment_entity_ids": { "type": "array", "items": { "type": "string" } } } }, "EffectiveLimit": { "type": "object", "description": "Resolved limit for `(subject, key, period)`, with provenance so the dashboard can\nexplain to admins which line of policy is in effect.", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/LimitSource", "description": "Where this value came from: an override, the org's tier, or the system default." }, "value": { "type": [ "integer", "null" ], "format": "int64", "description": "The effective cap. `None` means \"unlimited\".", "minimum": 0 } } }, "EffectivePoliciesResponse": { "type": "object", "required": [ "timezone", "curfew_windows", "user_sharing_mode" ], "properties": { "allowed_creator_roles": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_entry_kinds": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_portal_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Present on integration effective-policies when apartment-restrict binds this requester." }, "allowed_weekdays": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "blackout_dates": { "type": [ "array", "null" ], "items": { "type": "string" } }, "curfew_windows": { "type": "array", "items": { "$ref": "#/components/schemas/CurfewWindowResponse" } }, "max_active_per_user": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_doors": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_duration_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "max_uses": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "no_reshare": { "type": "boolean" }, "no_transitive_delegation": { "type": "boolean" }, "prohibited_master_door_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "require_expiry": { "type": "boolean" }, "require_justification": { "type": "boolean" }, "require_photo": { "type": "boolean" }, "require_pin": { "type": "boolean" }, "require_verified_phone": { "type": "boolean" }, "restrict_to_own_apartment_doors": { "type": "boolean" }, "share_allow_unlimited": { "type": "boolean" }, "share_default_max_uses": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "share_max_duration_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Share-specific TTL cap in seconds. `86400` (1 day) when `share_max_duration` is unset.\nOrg policy may raise this up to `31536000` (365d). Authoring uses the min of this and\n`max_duration_seconds`.", "minimum": 0 }, "share_max_uses": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "timezone": { "type": "string", "description": "IANA timezone used to evaluate curfews, or `\"UTC\"` when unset." }, "user_sharing_mode": { "type": "string", "description": "Effective `user_sharing` mode: `none` | `admin_only` | `approval_required` | `all`." } } }, "Entity": { "allOf": [ { "$ref": "#/components/schemas/ResourceLifecycle" }, { "type": "object", "required": [ "id", "device_id", "entity_type" ], "properties": { "device_id": { "type": "string", "description": "Parent device ID." }, "entity_type": { "$ref": "#/components/schemas/EntityType", "description": "Entity type (switch, light, sensor)." }, "external_id": { "type": [ "string", "null" ], "description": "External ID from the integration." }, "id": { "type": "string", "description": "Unique identifier (ULID)." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HashMap", "description": "Persisted, entity-specific metadata (e.g. integration-specific fields).\nStored in `entities.metadata` JSONB; serialized as `metadata`." } ] }, "name": { "type": [ "string", "null" ], "description": "Optional friendly name for the entity." }, "zone_id": { "type": [ "string", "null" ], "description": "Optional zone this entity belongs to." } } } ], "description": "The actual controllable \"button\" or \"sensor\".\n\nExamples: Relay 1, Temp Sensor, Light Switch." }, "EntityHoldItem": { "type": "object", "required": [ "entity_id", "hold" ], "properties": { "entity_id": { "type": "string" }, "hold": { "$ref": "#/components/schemas/HoldView" } } }, "EntityMetadataDefinitionResponse": { "type": "object", "required": [ "provider_type", "entity_type", "schema", "data" ], "properties": { "data": { "description": "Current `entity_metadata` as a JSON object (best-effort decoded from string values)." }, "entity_type": { "type": "string" }, "provider_type": { "type": "string" }, "schema": { "description": "JSON Schema describing `entities.entity_metadata` shape for this provider/entity type." } } }, "EntityResponse": { "allOf": [ { "$ref": "#/components/schemas/Entity" }, { "type": "object", "properties": { "entity_metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HashMap", "description": "Persisted, entity-specific metadata (integration-specific fields)." } ] }, "state": { "description": "Derived, read-only. When local provider config cannot run switchable\nopen/close/toggle, `{ \"status\": \"invalid\", \"reason\": \"\" }`." } } } ] }, "EntityType": { "type": "string", "description": "Entity type (apartment, switch, light, sensor...).", "enum": [ "apartment", "door", "light", "sensor", "switch" ] }, "ExecuteScriptingRequest": { "type": "object", "required": [ "script" ], "properties": { "script": { "type": "string" } }, "additionalProperties": false }, "ExecuteScriptingResponse": { "type": "object", "required": [ "result" ], "properties": { "result": {} } }, "FlaggedResource": { "type": "object", "description": "A resource currently flagged in the lifecycle (shown to admins so they can resolve).", "required": [ "resource", "id", "state" ], "properties": { "flagged_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "marked_at": { "type": [ "string", "null" ] }, "resource": { "$ref": "#/components/schemas/CapacityResource" }, "state": { "$ref": "#/components/schemas/ResourceState" } } }, "GetAccessPortalResponse": { "allOf": [ { "$ref": "#/components/schemas/AccessPortalListItem" }, { "type": "object", "required": [ "integration_id" ], "properties": { "integration_id": { "type": "string" } } } ], "description": "Response for get access portal by ID (includes integration_id for navigation)." }, "HashMap": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "HoldKind": { "type": "string", "enum": [ "permanent", "temporary", "recurring" ] }, "HoldMode": { "type": "string", "enum": [ "normal", "hold_open", "hold_closed" ] }, "HoldView": { "type": "object", "required": [ "mode", "kind", "timezone", "set_at", "entity_direct", "held_by_door_ids" ], "properties": { "entity_direct": { "type": "boolean" }, "held_by_door_ids": { "type": "array", "items": { "type": "string" } }, "kind": { "$ref": "#/components/schemas/HoldKind" }, "mode": { "$ref": "#/components/schemas/HoldMode" }, "next_window": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HoldWindowView" } ] }, "reason": { "type": [ "string", "null" ] }, "recurrence": { "type": [ "object", "null" ], "description": "Authored recurrence (always `freq: weekly` and an explicit ISO day list)." }, "set_at": { "type": "string" }, "set_by": { "type": [ "string", "null" ] }, "set_by_display_name": { "type": [ "string", "null" ] }, "timezone": { "type": "string", "description": "IANA timezone for authoring: the spec's zone when recurring, otherwise the org zone\n(`UTC` if the org has none). Never the caller's browser zone." }, "until": { "type": [ "string", "null" ] } } }, "HoldWindowView": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "HolidayCalendarPolicyConfig": { "type": "object", "description": "Typed `config` shape for `holiday_calendar`.", "required": [ "dates" ], "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "dates": { "type": "array", "items": { "type": "string" }, "description": "Organization-local ISO dates in `YYYY-MM-DD` format." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "ImageUploadForm": { "type": "object", "description": "Multipart form body for image uploads. Documents the `file` field for the\ngenerated OpenAPI spec / SDKs; the handler reads the multipart stream directly.", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Image file bytes (JPEG, PNG, or WebP)." } } }, "Integration": { "allOf": [ { "$ref": "#/components/schemas/ResourceLifecycle" }, { "type": "object", "required": [ "id", "org_id", "provider_type", "name", "enabled", "health" ], "properties": { "config": { "description": "Provider-specific non-secret configuration (JSON)." }, "enabled": { "type": "boolean", "description": "Pause switch for hardware connectors. Always true for site providers." }, "health": { "$ref": "#/components/schemas/IntegrationHealth", "description": "Backend-controlled health marker (ok/reduced/error)." }, "id": { "type": "string", "description": "Unique identifier (ULID)." }, "name": { "$ref": "#/components/schemas/LocalizedString", "description": "Human-friendly name for this integration (distinguishes multiple integrations of same provider)." }, "org_id": { "type": "string", "description": "Organization that owns this integration." }, "provider_type": { "$ref": "#/components/schemas/ProviderType", "description": "Provider type (e.g. homeassistant, shelly_cloud)." } } } ], "description": "Credential/Auth for a specific cloud instance.\n\nExample: Shelly account \"A\", HomeAssistant instance \"Home\"." }, "IntegrationDeviceMetadataSchemaResponse": { "type": "object", "description": "JSON Schema for `devices.device_metadata` for an integration's provider (no device instance required).", "required": [ "provider_type", "schema" ], "properties": { "provider_type": { "type": "string" }, "schema": { "description": "JSON Schema describing `devices.device_metadata` for this provider." } } }, "IntegrationHealth": { "type": "string", "description": "Integration health marker (backend-controlled).", "enum": [ "ok", "reduced", "error" ] }, "IntegrationResponse": { "allOf": [ { "$ref": "#/components/schemas/Integration" }, { "type": "object", "required": [ "provider_type_name" ], "properties": { "provider_type_name": { "$ref": "#/components/schemas/LocalizedString", "description": "Human-friendly provider type name(s), keyed by locale." } } } ] }, "IntegrationUserItem": { "type": "object", "required": [ "external_id", "status", "unmanaged" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "external_id": { "type": "string" }, "is_admin": { "type": [ "boolean", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "openapp_user_id": { "type": [ "string", "null" ], "description": "Present when `status == linked`. ULID string of the OpenApp user." }, "pending_invitation_id": { "type": [ "string", "null" ], "description": "Present when `status == invited`. ULID string of the matching `user_invitations` row." }, "phone": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`linked` | `invited` | `unlinked`." }, "unmanaged": { "type": "boolean", "description": "True when the vendor user is on the gate but not linked to an OpenApp user (flag only)." } } }, "IntegrationUsersResponse": { "type": "object", "required": [ "integration_id", "items", "unmanaged_count" ], "properties": { "directory_limited": { "type": [ "boolean", "null" ], "description": "When true, the upstream provider did not return the full user directory\n(e.g. linked credentials lack upstream admin rights). Provider-agnostic;\nsee provider-specific endpoints for role details." }, "integration_id": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationUserItem" } }, "unmanaged_count": { "type": "integer", "format": "int32", "description": "Count of vendor users not linked to OpenApp (status `unlinked`). Informational only." } } }, "InvitationAllowedDaysPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_allowed_days`.", "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "blackout_dates": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Organization-local ISO dates that invitations cannot use." }, "holiday_calendar": { "type": [ "boolean", "null" ], "description": "Include dates from applicable `holiday_calendar` rows." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] }, "weekdays": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Sunday is 0; Saturday is 6. Omit to leave weekdays unrestricted for this row." } } }, "InvitationAllowedEntryKindsPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_allowed_entry_kinds`.", "required": [ "kinds" ], "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationEntryKind" } }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "InvitationApartmentGrant": { "type": "object", "required": [ "entity_id", "role" ], "properties": { "entity_id": { "type": "string" }, "role": { "type": "string" } } }, "InvitationAuthoringPolicyConfig": { "type": "object", "description": "Typed `config` shape for empty invitation authoring policies.", "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "InvitationCountLimitPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_max_active_per_user` and `max_doors_per_invite`.", "required": [ "max" ], "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "max": { "type": "integer", "format": "int64", "minimum": 1 }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "InvitationEntryKind": { "type": "string", "enum": [ "door", "gate", "boom-gate" ] }, "InvitationIdentityPolicyConfig": { "type": "object", "description": "Typed `config` shape for invitation policies that prohibit or require a boolean behavior.", "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] }, "require_photo": { "type": [ "boolean", "null" ] }, "require_pin": { "type": [ "boolean", "null" ] }, "require_verified_phone": { "type": [ "boolean", "null" ] } } }, "InvitationMaxDurationPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_max_duration`.", "required": [ "max_seconds" ], "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "max_seconds": { "type": "integer", "format": "int64", "minimum": 1 }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "InvitationMaxUsesPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_max_uses`.", "required": [ "max_uses" ], "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "max_uses": { "type": "integer", "format": "int64", "minimum": 1 }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "InvitationPreviewRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } }, "additionalProperties": false }, "InvitationPreviewResponse": { "type": "object", "required": [ "org_id", "channel", "status", "target_masked", "expires_at" ], "properties": { "channel": { "type": "string" }, "expires_at": { "type": "string" }, "org_id": { "type": "string" }, "status": { "type": "string" }, "target_masked": { "type": "string", "description": "Masked destination so the redeem page can confirm \"we'll send the code to +9725…78\"." } } }, "InvitationSiteAccessDto": { "type": "object", "required": [ "integration_id", "role" ], "properties": { "apartment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvitationApartmentGrant" } ] }, "integration_id": { "type": "string" }, "role": { "type": "string" } } }, "InviteCreatorRolesPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invite_creator_roles`.", "required": [ "allowed_roles" ], "properties": { "allowed_roles": { "type": "array", "items": { "type": "string" } }, "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "InviteRecurrenceSeriesEnd": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "never" ] } } }, { "type": "object", "required": [ "at", "kind" ], "properties": { "at": { "type": "string" }, "kind": { "type": "string", "enum": [ "until" ] } } }, { "type": "object", "required": [ "total", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "count" ] }, "last_window_to": { "type": [ "string", "null" ] }, "total": { "type": "integer", "format": "int32", "minimum": 0 } } } ], "description": "How the recurring series ends (from `invite_recurrence`), for admin/public display." }, "InviteScheduleCombined": { "type": "object", "properties": { "open_ended_recurrence": { "type": "boolean" }, "since": { "type": [ "string", "null" ] }, "until": { "type": [ "string", "null" ] } } }, "InviteScheduleEntryInput": { "type": "object", "properties": { "expires_in": { "type": [ "string", "null" ], "description": "Duration per [RFC 5545 §3.3.6](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.6) (ISO 8601 `P1D`, `PT1H`, …; no months/years) or compact tokens `s`/`m`/`h`/`d`/`w` (`M` is minutes). Max 3650d (10 years). `1y` is rejected. Measured from resolved `valid_from`. Mutually exclusive with `valid_to`." }, "id": { "type": [ "string", "null" ] }, "invite_recurrence": {}, "is_enabled": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "starts_in": { "type": [ "string", "null" ], "description": "Duration per [RFC 5545 §3.3.6](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.6) (ISO 8601 `P1D`, `PT1H`, …; no months/years) or compact tokens `s`/`m`/`h`/`d`/`w` (`M` is minutes). Max 3650d (10 years). `1y` is rejected. Mutually exclusive with `valid_from`." }, "valid_from": { "type": [ "string", "null" ], "description": "[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) start (UTC). Mutually exclusive with `starts_in`." }, "valid_to": { "type": [ "string", "null" ], "description": "[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) end (UTC). Mutually exclusive with `expires_in`." } } }, "InviteScheduleEntrySnapshot": { "type": "object", "required": [ "id", "is_enabled", "valid_from", "valid_to", "schedule" ], "properties": { "id": { "type": "string" }, "invite_recurrence": {}, "is_enabled": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "schedule": { "$ref": "#/components/schemas/InviteScheduleSnapshot" }, "valid_from": { "type": "string" }, "valid_to": { "type": "string" } } }, "InviteScheduleKind": { "type": "string", "enum": [ "single_window", "single_recurring", "multiple" ] }, "InviteScheduleSnapshot": { "type": "object", "required": [ "is_recurring", "slot_duration_seconds" ], "properties": { "active_window": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InviteWindow" } ] }, "is_recurring": { "type": "boolean" }, "next_window": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InviteWindow" } ] }, "series_end": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InviteRecurrenceSeriesEnd" } ] }, "slot_duration_seconds": { "type": "integer", "format": "int64" } } }, "InviteWindow": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "error": {}, "id": {}, "jsonrpc": { "type": "string" }, "result": {} } }, "KeyOverage": { "type": "object", "description": "One capacity key's overage snapshot.", "required": [ "key", "unit", "current", "limit", "excess" ], "properties": { "current": { "type": "integer", "format": "int64", "minimum": 0 }, "excess": { "type": "integer", "format": "int64", "minimum": 0 }, "key": { "$ref": "#/components/schemas/QuotaKey" }, "limit": { "type": "integer", "format": "int64", "minimum": 0 }, "unit": { "$ref": "#/components/schemas/QuotaUnit" } } }, "LanAgentTaskSpecRequest": { "type": "object", "required": [ "lan_protocol_version", "task_id", "payload" ], "properties": { "lan_protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "payload": {}, "task_id": { "type": "string" } }, "additionalProperties": false }, "LanAgentTaskSpecResponse": { "type": "object", "required": [ "lan_protocol_version", "task_id", "spec" ], "properties": { "lan_protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "spec": {}, "task_id": { "type": "string" } } }, "LifeSafetyAttestation": { "type": "object", "required": [ "independent_egress", "power_fail_behavior", "fire_door_listing_unaltered", "openapp_not_fire_alarm_interface", "installer_name", "attested_at" ], "properties": { "attested_at": { "type": "string", "format": "date-time" }, "attested_by_user_id": { "type": [ "string", "null" ] }, "entrapment_protection_present": { "type": [ "boolean", "null" ] }, "fire_door_listing_unaltered": { "type": "boolean" }, "independent_egress": { "type": "boolean" }, "installer_name": { "type": "string" }, "listed_local_system": { "type": [ "boolean", "null" ] }, "openapp_not_fire_alarm_interface": { "type": "boolean" }, "power_fail_behavior": { "$ref": "#/components/schemas/PowerFailBehavior" } } }, "LifeSafetyClass": { "type": "string", "enum": [ "not_applicable", "ingress_only", "vehicle_gate", "special_locking_listed_local", "means_of_egress", "fire_door_assembly" ] }, "LightsAutoOffDuration": { "type": "object", "description": "Map of light entity ULID to auto-off duration in seconds.", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0 }, "propertyNames": { "type": "string" } }, "LimitSource": { "oneOf": [ { "type": "object", "description": "A row in `quota_overrides`; carries the override id for traceability.", "required": [ "id", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "override" ] } } }, { "type": "object", "description": "A row in `tier_quotas`; carries the tier slug.", "required": [ "slug", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "tier" ] }, "slug": { "type": "string" } } }, { "type": "object", "description": "The hardcoded fallback in `catalog::DEFAULT_TIER_FOR_PERSONAL` when no\ntier is configured for the org (e.g. brand-new personal workspace).", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "default" ] } } } ] }, "ListAccessInviteRenewalRequestsResponse": { "type": "object", "required": [ "requests" ], "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteRenewalRequestItem" } } } }, "ListAuditEventsQuery": { "type": "object", "properties": { "actor_guest_id": { "type": [ "string", "null" ], "description": "Filter to a single guest fingerprint. Disjoint from `actor_user_id`." }, "actor_kind": { "type": [ "string", "null" ] }, "actor_user_id": { "type": [ "string", "null" ] }, "correlation_id": { "type": [ "string", "null" ] }, "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor from a previous page's `next_cursor`." }, "event_type": { "type": [ "string", "null" ] }, "limit": { "type": [ "integer", "null" ], "format": "int32", "description": "Page size (default 50, max 200).", "minimum": 0 }, "occurred_after": { "type": [ "string", "null" ], "description": "RFC 3339 lower bound (inclusive). Must be within the 30-day hot window." }, "occurred_before": { "type": [ "string", "null" ], "description": "RFC 3339 upper bound (inclusive)." }, "outcome": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "resource_name": { "type": [ "string", "null" ], "description": "Case-insensitive substring match on the resource's snapshotted display name\n(`details.resource_name`), e.g. `shelly`." }, "resource_type": { "type": [ "string", "null" ] } } }, "ListDevicesQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" }, { "type": "object", "properties": { "device_kind": { "type": [ "string", "null" ], "description": "Optional filter: only devices with metadata.kind equal to this value (e.g. virtual_access_portal).\nRequires integration_id. Filtering done at SQL level." }, "external_id": { "type": [ "string", "null" ], "description": "Optional filter: only devices with this external_id. Requires integration_id and device_kind.\nReturns at most 1 device. Filtering done at SQL level." }, "has_external_id": { "type": [ "boolean", "null" ], "description": "When true, only devices with a non-empty `external_id`. Requires `integration_id`." }, "has_go2rtc_channel": { "type": [ "boolean", "null" ], "description": "When true, only devices whose metadata JSON has a non-empty `channel` (go2rtc cameras). Requires `integration_id`." }, "include_stale": { "type": [ "boolean", "null" ], "description": "When true with `integration_id`, include `stale` per device when the provider supports it." }, "integration_id": { "type": [ "string", "null" ], "description": "Optional filter: only devices belonging to this integration." }, "locale": { "type": [ "string", "null" ], "description": "Locale used to resolve the localized `name` when sorting by name (e.g. `en`). Defaults to `en`." }, "q": { "type": [ "string", "null" ], "description": "Case-insensitive substring match on localized device name (JSON). Best-effort when `integration_id` is set (SQL ILIKE)." }, "sort": { "type": [ "string", "null" ], "description": "Server-side ordering for org-wide lists: `name:asc`, `name:desc`, `created_at:asc`, `created_at:desc`.\nIgnored when `integration_id` is set. Defaults to insertion order when omitted." } } } ] }, "ListEntitiesQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" }, { "type": "object", "properties": { "q": { "type": [ "string", "null" ], "description": "Case-insensitive substring match on entity `name` (plain text). Applies to org-wide lists." }, "sort": { "type": [ "string", "null" ], "description": "Server-side ordering for org-wide lists: `name:asc`, `name:desc`, `created_at:asc`, `created_at:desc`.\nIgnored when `zone_id` is set. Defaults to insertion order when omitted." }, "zone_id": { "type": [ "string", "null" ], "description": "Optional filter: only entities in this zone." } } } ], "description": "List entities for the organization context (X-Org)." }, "ListIntegrationAccessInvitesResponse": { "type": "object", "required": [ "invites" ], "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteListItem" } } } }, "ListIntegrationAccessPortalsResponse": { "type": "object", "required": [ "portals" ], "properties": { "portals": { "type": "array", "items": { "$ref": "#/components/schemas/AccessPortalListItem" } } } }, "ListIntegrationsQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" }, { "type": "object", "properties": { "provider_type": { "type": [ "string", "null" ], "description": "Optional filter: only integrations with this provider_type (e.g. virtual_access)." }, "q": { "type": [ "string", "null" ], "description": "Optional case-insensitive substring match on integration `name` (localized JSON), same as devices list." } } } ] }, "ListInvitationsResponse": { "type": "object", "required": [ "invitations" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/UserInvitationDto" } } } }, "ListOrgChildrenQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" }, { "type": "object", "properties": { "parent_id": { "type": [ "string", "null" ], "description": "Parent org id. When omitted, returns the roots of the caller's visible org forest." } } } ] }, "ListOrgUsersQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" }, { "type": "object", "properties": { "recursive": { "type": [ "boolean", "null" ] } } } ] }, "ListOrgsQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" } ] }, "LocaleContentTranslation": { "type": "object", "required": [ "title", "body" ], "properties": { "body": { "type": "string" }, "title": { "type": "string" } } }, "LocalizedString": { "type": "object", "description": "Localized string dictionary.\n\nThis matches the dashboard convention: `{ [locale: string]: string }`.\n\nNotes:\n- Internally this is keyed by `icu_locale_core::Locale` for type-safety.\n- For JSON/OpenAPI purposes this is treated as a `{ [locale: string]: string }` object.", "required": [ "value" ], "properties": { "value": { "type": "object", "description": "OpenAPI representation: `HashMap` (JSON object).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "LocationBindingMode": { "type": "string", "enum": [ "inherit", "explicit", "none" ] }, "LocationBindingResponse": { "type": "object", "required": [ "mode" ], "properties": { "location_id": { "type": [ "string", "null" ] }, "mode": { "$ref": "#/components/schemas/LocationBindingMode" } } }, "LocationKind": { "type": "string", "enum": [ "address", "coordinates" ] }, "LocationListItemResponse": { "allOf": [ { "$ref": "#/components/schemas/LocationResponse" }, { "type": "object", "properties": { "is_bound_here": { "type": [ "boolean", "null" ] }, "is_relevant": { "type": [ "boolean", "null" ] }, "usage_count": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } } ] }, "LocationResponse": { "type": "object", "required": [ "id", "kind" ], "properties": { "city": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "formatted_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "id": { "type": "string" }, "image_url": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/LocationKind" }, "lat": { "type": [ "number", "null" ], "format": "double" }, "lng": { "type": [ "number", "null" ], "format": "double" }, "notes": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "place_id": { "type": [ "string", "null" ] }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationSource" } ] } } }, "LocationSource": { "type": "object", "required": [ "owner_kind", "owner_id" ], "properties": { "owner_id": { "type": "string" }, "owner_kind": { "type": "string" } } }, "MeAccessInvitesResponse": { "type": "object", "required": [ "invites" ], "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteListItem" } } } }, "MeApartmentAsset": { "type": "object", "required": [ "entity_id", "integration_id", "org_id", "role", "receives_calls", "call_eligible" ], "properties": { "apartment_label": {}, "apartment_number": { "type": [ "integer", "null" ], "format": "int64" }, "building_name": {}, "call_eligible": { "type": "boolean", "description": "True when this user would be a callee for intercom calls (policy + role + receives_calls)." }, "display_name": {}, "dnd_enabled": { "type": [ "boolean", "null" ], "description": "True when calls are silenced for this apartment (global DND or per-apartment DND)." }, "entity_id": { "type": "string" }, "floor": {}, "floor_number": { "type": [ "integer", "null" ], "format": "int64" }, "image_url": { "type": [ "string", "null" ], "description": "Presigned apartment (entity) photo URL (best-effort)." }, "integration_id": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "description": "Organization display name (best-effort)." }, "receives_calls": { "type": "boolean" }, "role": { "type": "string" } } }, "MeApartmentsResponse": { "type": "object", "required": [ "apartments", "age_class" ], "properties": { "age_class": { "$ref": "#/components/schemas/AgeClass", "description": "Derived from parent-declared date of birth. `adult` when unset." }, "apartments": { "type": "array", "items": { "$ref": "#/components/schemas/MeApartmentAsset" } }, "dnd_global": { "type": [ "boolean", "null" ], "description": "True when user has global DND enabled (all calls silenced)." } } }, "MeCallBlockItem": { "type": "object", "required": [ "public_portal_id", "created_at" ], "properties": { "created_at": { "type": "string" }, "public_portal_id": { "type": "string" } } }, "MeCallBlocksResponse": { "type": "object", "required": [ "blocks" ], "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/MeCallBlockItem" } } } }, "MeCallSafetyOkResponse": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "MeInvitationAsset": { "type": "object", "required": [ "invite_link_id", "integration_id", "org_id", "state", "portal_ids", "grants", "uses", "can_read" ], "properties": { "access_control": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicPortalAccessControl", "description": "Integration / building summary with photo (best-effort)." } ] }, "branding": { "description": "Invite branding overrides (may include `logoUrl` for card display)." }, "building_name": {}, "can_read": { "type": "boolean", "description": "True when the requester has `integrations:read` on the invite's org, i.e.\nmay open the invitation's management page. Mirrors the authz check in\n`list_integration_access_invites`." }, "claimed_at": { "type": [ "string", "null" ] }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/PublicInviteGrant" }, "description": "One entry per grant in the invite, with label / door image / lights flag\nenriched the same way as `GET /public/access/invites/{token}`. Lets\nclients render multi-door invitations without an extra round trip." }, "integration_id": { "type": "string" }, "invite_link_id": { "type": "string" }, "invitee_message": { "description": "Invitee-facing message (mirrors `PublicInviteResponse.invitee_message`).\nSame `LocalizedString` shape as on the public invite endpoint." }, "last_used_at": { "type": [ "string", "null" ] }, "max_uses": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": [ "string", "null" ], "description": "Admin-defined invite name (mirrors `PublicInviteResponse.name`)." }, "org_id": { "type": "string" }, "org_image_url": { "type": [ "string", "null" ], "description": "Presigned org logo URL (best-effort)." }, "photo_url": { "type": [ "string", "null" ], "description": "Presigned URL for the invite's main photo (best-effort)." }, "portal_ids": { "type": "array", "items": { "type": "string" }, "description": "Portal IDs the invite grants (for display: \"Scan portal QR to open\").\nKept for backwards compatibility — prefer `grants` for new clients." }, "state": { "type": "string" }, "uses": { "type": "integer", "format": "int32", "description": "Number of times the invite has been used." }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] } } }, "MeInvitationsResponse": { "type": "object", "required": [ "invitations" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/MeInvitationAsset" } } } }, "MeProfileResponse": { "type": "object", "required": [ "name" ], "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Flattened display name from the user's localized name." }, "phone": { "type": [ "string", "null" ] } } }, "MePushSubscriptionStatusResponse": { "type": "object", "required": [ "has_subscription", "has_device_token", "has_any_notification_channel", "push_configured" ], "properties": { "has_any_notification_channel": { "type": "boolean", "description": "Convenience: `has_subscription || has_device_token`." }, "has_device_token": { "type": "boolean", "description": "True when at least one native device token (APNs / FCM) is registered." }, "has_subscription": { "type": "boolean", "description": "True when at least one Web Push subscription exists for this browser/device flow." }, "push_configured": { "type": "boolean", "description": "True when VAPID is configured; false means Web Push call notifications cannot be sent." } } }, "MePushVapidPublicKeyResponse": { "type": "object", "required": [ "public_key" ], "properties": { "public_key": { "type": "string" } } }, "MeShareAuthoringPortal": { "type": "object", "required": [ "id", "public_id", "label", "org_id", "integration_id" ], "properties": { "id": { "type": "string" }, "integration_id": { "type": "string" }, "label": {}, "org_id": { "type": "string" }, "public_id": { "type": "string" } } }, "MeShareAuthoringResponse": { "type": "object", "required": [ "org_id", "integration_id", "max_duration_seconds", "default_max_uses", "allow_unlimited", "uses_editable", "require_justification", "portals" ], "properties": { "allow_unlimited": { "type": "boolean" }, "blocked_reason": { "type": [ "string", "null" ] }, "default_max_uses": { "type": "integer", "format": "int32" }, "integration_id": { "type": "string" }, "max_duration_seconds": { "type": "integer", "format": "int64", "description": "Effective share TTL cap (seconds): min of invitation max duration and share max\n(system default 86400 when `share_max_duration` is unset).", "minimum": 0 }, "max_uses": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "org_id": { "type": "string" }, "portals": { "type": "array", "items": { "$ref": "#/components/schemas/MeShareAuthoringPortal" } }, "require_justification": { "type": "boolean" }, "uses_editable": { "type": "boolean" } } }, "MemberCatalogItem": { "type": "object", "required": [ "inventory_id", "product_id", "name", "price_cents" ], "properties": { "external_url": { "type": [ "string", "null" ] }, "image_media_asset_id": { "type": [ "string", "null" ] }, "inventory_id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "price_cents": { "type": "integer", "format": "int64" }, "product_id": { "type": "string" }, "stock_quantity": { "type": [ "integer", "null" ], "format": "int32" } } }, "MemberCatalogResponse": { "type": "object", "required": [ "store", "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemberCatalogItem" } }, "store": { "$ref": "#/components/schemas/Store" } } }, "MergeOfferDto": { "type": "object", "required": [ "id", "trigger_kind", "trigger_masked", "requesting_user_id", "candidate_user_id", "survivor_user_id", "session_will_remap", "requesting_has_avatar", "candidate_has_avatar", "proof_complete", "expires_at" ], "properties": { "candidate_has_avatar": { "type": "boolean" }, "candidate_user_id": { "type": "string" }, "claim_email": { "type": [ "string", "null" ] }, "claim_phone": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "proof_complete": { "type": "boolean", "description": "False for an org-admin request until the resident proves the other identifier." }, "requesting_has_avatar": { "type": "boolean" }, "requesting_user_id": { "type": "string" }, "session_will_remap": { "type": "boolean" }, "survivor_user_id": { "type": "string" }, "trigger_kind": { "type": "string" }, "trigger_masked": { "type": "string" } } }, "MultiResourceOutputOptions": { "type": "object", "description": "Options for list and other multi-resource operations.\nContains single-resource options in a flat manner plus `only_deleted` and pagination.", "required": [ "single", "only_deleted", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int32", "description": "Pagination: max items to return. Default from config when not specified.", "minimum": 0 }, "offset": { "type": "integer", "format": "int32", "description": "Pagination: items to skip. Default 0 when not specified.", "minimum": 0 }, "only_deleted": { "type": "boolean", "description": "If true, return *only* soft-deleted items.\n\nNote: This implies `include_deleted=true` at the API boundary, but repository/storage\nimplementations should treat this as a separate filter." }, "single": { "$ref": "#/components/schemas/SingleResourceOutputOptions", "description": "Single-resource options (`include_deleted`). Accessed flat via `Deref`." } } }, "MultiResourceOutputOptionsQuery": { "type": "object", "properties": { "include_deleted": { "type": "boolean" }, "only_deleted": { "type": "boolean" } } }, "NotificationChannel": { "type": "string", "enum": [ "audit" ] }, "NotificationPolicyConfig": { "type": "object", "description": "Shared typed `config` shape for notification policies.", "required": [ "channels" ], "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannel" }, "description": "Notification destinations. Only `audit` is currently supported." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "NotifyPortalMessageBody": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } }, "additionalProperties": false }, "OrgPermissionsResponse": { "type": "object", "description": "Permissions the current user has in this org (for UI: gray out / tooltips).\nReturns permission keys (e.g. `users:create`, `admin`) granted directly or via inheritance.", "required": [ "permissions" ], "properties": { "permissions": { "type": "array", "items": { "type": "string" } } } }, "OrgPrivacySettingsResponse": { "type": "object", "required": [ "audit_retention_days", "audit_retention_days_min", "audit_retention_days_max" ], "properties": { "audit_retention_days": { "type": "integer", "format": "int32" }, "audit_retention_days_max": { "type": "integer", "format": "int32" }, "audit_retention_days_min": { "type": "integer", "format": "int32" } } }, "OrgProposeMergeRequest": { "type": "object", "required": [ "org_user_id" ], "properties": { "org_user_id": { "type": "string" }, "other_email": { "type": [ "string", "null" ] }, "other_phone": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "OrgProposeMergeResponse": { "type": "object", "required": [ "id", "expires_at" ], "properties": { "expires_at": { "type": "string" }, "id": { "type": "string" } } }, "OrgTimezoneResponse": { "type": "object", "properties": { "timezone": { "type": [ "string", "null" ], "description": "IANA timezone (e.g. `Asia/Jerusalem`). `null` means UTC fallback at evaluation." } } }, "Organization": { "allOf": [ { "$ref": "#/components/schemas/ResourceLifecycle" }, { "type": "object", "required": [ "id", "name", "user_roles" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Optional description." }, "id": { "type": "string", "description": "Unique identifier (ULID)." }, "is_personal": { "type": "boolean", "description": "True when this org is a personal workspace auto-created for a self-signup user.\n\nCompany / property orgs are `false`. A workspace is the parent a user's own first\nsite is created under, not an operating organization that members are invited into." }, "name": { "$ref": "#/components/schemas/LocalizedString", "description": "Organization name." }, "parent_id": { "type": [ "string", "null" ], "description": "Parent organization ID for hierarchy." }, "user_roles": { "type": "object", "description": "User ID to roles mapping for this org (keys are org IDs as strings).", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "propertyNames": { "type": "string" } } } } ], "description": "An organization (tenant) with optional parent for hierarchy." }, "OrganizationResponse": { "allOf": [ { "$ref": "#/components/schemas/Organization" }, { "type": "object", "properties": { "has_children": { "type": [ "boolean", "null" ], "description": "Whether this org has at least one child visible to the requester.\n\nPopulated only by the tree endpoints (children / search); `None` elsewhere. Lets the org\nselector render an expand affordance without first fetching the node's children." }, "parent_name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString", "description": "Localized name of the parent org when `parent_id` is set (for UI hierarchy).\nResolved server-side; does not require the client to `GET` the parent." } ] } } } ] }, "PaginatedResponse": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserResponse" } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_AccessInviteListItem": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "state", "is_enabled", "schedule_kind", "schedule_combined", "schedule_entries", "schedule", "uses", "location_mode", "granted_portals" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "created_by_user_id": { "type": [ "string", "null" ], "description": "User who created this invite or share. Omitted when the row has no creator." }, "creation_justification": { "type": [ "string", "null" ] }, "curfew_exempt": { "type": "boolean", "description": "Admin-only emergency exception: skip invitation curfew at redemption." }, "devices_count": { "type": [ "integer", "null" ], "format": "int32" }, "disabled_justification": { "type": [ "string", "null" ] }, "granted_portals": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteGrantedPortal" } }, "id": { "type": "string" }, "invite_recurrence": {}, "invitee_message": {}, "is_enabled": { "type": "boolean" }, "kind": { "$ref": "#/components/schemas/AccessInviteKind" }, "last_shared_at": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ] }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationResponse", "description": "Resolved event location for this invite (see `location_mode`): the invite's own\nlocation when `explicit`, the building location when `inherit`, or absent when `none`." } ] }, "location_mode": { "$ref": "#/components/schemas/LocationBindingMode", "description": "How the event location is resolved: `none`, `explicit`, or `inherit` (building)." }, "max_devices": { "type": [ "integer", "null" ], "format": "int32" }, "max_uses": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": [ "string", "null" ] }, "pending_renewal_count": { "type": [ "integer", "null" ], "format": "int32" }, "photo_url": { "type": [ "string", "null" ], "description": "Presigned URL for the invite's main photo (best-effort)." }, "revoked_at": { "type": [ "string", "null" ] }, "schedule": { "$ref": "#/components/schemas/InviteScheduleSnapshot" }, "schedule_combined": { "$ref": "#/components/schemas/InviteScheduleCombined" }, "schedule_entries": { "type": "array", "items": { "$ref": "#/components/schemas/InviteScheduleEntrySnapshot" } }, "schedule_kind": { "$ref": "#/components/schemas/InviteScheduleKind" }, "state": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] }, "uses": { "type": "integer", "format": "int32" }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_AccessPortalListItem": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "public_id", "name" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ], "description": "When set, the portal is soft-deleted (kept for restore)." }, "device_id": { "type": [ "string", "null" ], "description": "Door device id (virtual_access_portal in this integration). Canonical portal link key." }, "directory_id": { "type": [ "string", "null" ], "description": "Directory device id (virtual_access_directory in this integration)." }, "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "public_id": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_AgentResponse": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "owner_user_id", "name", "confirmation_mode" ], "properties": { "allowed_entity_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_portal_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_tool_names": { "type": [ "array", "null" ], "items": { "type": "string" } }, "confirmation_mode": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "org_id": { "type": "string" }, "owner_user_id": { "type": "string" }, "purpose": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_ApiKeyListItem": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "Response for API key list item (no token).", "required": [ "id", "name", "token_suffix", "base_url", "expires_at" ], "properties": { "base_url": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ] }, "scoped_entity_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scoped_roles": { "type": [ "array", "null" ], "items": { "type": "string" } }, "token_suffix": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_EntityResponse": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Entity" }, { "type": "object", "properties": { "entity_metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HashMap", "description": "Persisted, entity-specific metadata (integration-specific fields)." } ] }, "state": { "description": "Derived, read-only. When local provider config cannot run switchable\nopen/close/toggle, `{ \"status\": \"invalid\", \"reason\": \"\" }`." } } } ] } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_LocationListItemResponse": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/LocationResponse" }, { "type": "object", "properties": { "is_bound_here": { "type": [ "boolean", "null" ] }, "is_relevant": { "type": [ "boolean", "null" ] }, "usage_count": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } } ] } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_StoreMember": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "Store membership. `Pending` awaits admin approval; `Removed` keeps the row (history) but\nblocks purchasing.", "required": [ "id", "store_id", "user_id", "role", "status" ], "properties": { "billing_account_id": { "type": [ "string", "null" ], "description": "Account purchases are charged to. `None` falls back to the member's personal account." }, "created_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "removed_at": { "type": [ "string", "null" ] }, "role": { "$ref": "#/components/schemas/StoreMemberRole" }, "status": { "$ref": "#/components/schemas/StoreMemberStatus" }, "store_id": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] }, "user_id": { "type": "string" } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_StoreProduct": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "Org-scoped catalog product. Soft-deleted products are retained (`purge_at`) so historical\nstatements and audit stay readable.", "required": [ "id", "org_id", "name" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "image_media_asset_id": { "type": [ "string", "null" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "org_id": { "type": "string" }, "purge_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_ZoneResponse": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Zone" } ] } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginationQuery": { "type": "object", "description": "Pagination query parameters. Flatten into list-endpoint query structs.\nWhen not provided, defaults to first page (limit from config, offset=0).", "properties": { "limit": { "type": "integer", "format": "int32", "description": "Number of items per page. Default from config, max 200.", "minimum": 0 }, "offset": { "type": "integer", "format": "int32", "description": "Number of items to skip. Default 0.", "minimum": 0 } } }, "PalgateLinkedAccountProbeDto": { "type": "object", "required": [ "device_id", "phone", "is_admin", "linked_device_permitted", "can_open_output1", "can_open_output2", "relay_mode_permitted", "probed_at" ], "properties": { "can_open_output1": { "type": "boolean" }, "can_open_output2": { "type": "boolean" }, "device_id": { "type": "string" }, "is_admin": { "type": "boolean" }, "linked_device_permitted": { "type": "boolean" }, "phone": { "type": "string" }, "probed_at": { "type": "string" }, "relay_mode_permitted": { "type": "boolean" } } }, "PalgateProbeLinkedAccountRequest": { "type": "object", "description": "Standalone probe for wizard (before integration exists).", "required": [ "org_id", "device_id", "config", "secrets" ], "properties": { "config": {}, "device_id": { "type": "string" }, "org_id": { "type": "string" }, "secrets": {} }, "additionalProperties": false }, "PalgateProbeLinkedAccountResponse": { "type": "object", "required": [ "linked_account_admin_mode", "probe" ], "properties": { "linked_account_admin_mode": { "type": "string" }, "probe": { "$ref": "#/components/schemas/PalgateLinkedAccountProbeDto" } } }, "PatchEntityRequest": { "type": "object", "description": "Shallow-merge into existing `entity_metadata` (PATCH). Does not replace the whole map.", "required": [ "metadata" ], "properties": { "metadata": { "type": "object", "description": "Keys to merge into persisted metadata. Omitted keys are left unchanged.\nJSON `null` removes a key (e.g. clear `floor` when setting `floor_number`).", "additionalProperties": {}, "propertyNames": { "type": "string" } } }, "additionalProperties": false }, "PatchLocationRequest": { "type": "object", "properties": { "city": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "formatted_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "geocode": { "type": "boolean" }, "kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationKind" } ] }, "lat": { "type": [ "number", "null" ], "format": "double" }, "lng": { "type": [ "number", "null" ], "format": "double" }, "locale": { "type": [ "string", "null" ], "description": "Preferred locale (app code or BCP-47) for geocoding (see `CreateLocationRequest::locale`)." }, "notes": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "place_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PatchMeApartmentDndPayload": { "type": "object", "properties": { "availability_hours": {}, "dnd_enabled": { "type": [ "boolean", "null" ] }, "quiet_hours": {} } }, "PatchMeDndPayload": { "type": "object", "properties": { "dnd_global": { "type": [ "boolean", "null" ] } } }, "PatchOrgPrivacySettingsRequest": { "type": "object", "required": [ "audit_retention_days" ], "properties": { "audit_retention_days": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "PeerJsConfig": { "type": "object", "required": [ "host", "port", "path", "secure" ], "properties": { "host": { "type": "string" }, "path": { "type": "string" }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "secure": { "type": "boolean" } } }, "PendingSharingApprovalResponse": { "type": "object", "required": [ "id", "status", "subject_kind" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "subject_kind": { "type": "string" } } }, "PerceptionActionResponse": { "type": "object", "required": [ "credential_id", "kind", "result" ], "properties": { "credential_id": { "type": "string" }, "kind": { "type": "string" }, "result": {} } }, "PerceptionLprRequest": { "type": "object", "required": [ "plate", "entity_id" ], "properties": { "entity_id": { "type": "string" }, "evidence": {}, "plate": { "type": "string" } } }, "PerceptionVisitorRequest": { "type": "object", "required": [ "entity_id" ], "properties": { "entity_id": { "type": "string" }, "evidence": {}, "portal_id": { "type": [ "string", "null" ] } } }, "PhonePatch": { "oneOf": [ { "type": "null", "default": null }, { "type": "null", "default": null }, { "type": "string" } ], "description": "Tristate for nullable string-patch fields: missing (leave alone), null (clear), set (replace)." }, "PlanQuotaResponse": { "type": "object", "required": [ "quota_key", "period", "unit" ], "properties": { "limit_value": { "type": [ "integer", "null" ], "format": "int64" }, "period": { "type": "string" }, "quota_key": { "type": "string" }, "unit": { "type": "string", "description": "Machine-readable unit of `limit_value` (e.g. `count`, `seconds`). Empty\nwhen `quota_key` is not a recognized `QuotaKey`." } } }, "PlanResponse": { "type": "object", "required": [ "slug", "name", "is_published", "is_default_for_personal", "sort_order", "quotas" ], "properties": { "description": {}, "is_default_for_personal": { "type": "boolean" }, "is_published": { "type": "boolean" }, "name": {}, "quotas": { "type": "array", "items": { "$ref": "#/components/schemas/PlanQuotaResponse" } }, "slug": { "type": "string" }, "sort_order": { "type": "integer", "format": "int32" } } }, "PlansResponse": { "type": "object", "required": [ "plans" ], "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PlanResponse" } } } }, "PmsInboundPayload": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string" }, "reservation_id": { "type": [ "string", "null" ] } } }, "PolicyOutputSelector": { "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ] }, "PolicyPrincipalKind": { "type": "string", "enum": [ "agent", "api_key", "invitation", "member", "resident", "admin", "all" ] }, "PolicyPrincipalSelector": { "oneOf": [ { "$ref": "#/components/schemas/PolicyPrincipalKind" }, { "type": "array", "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" } } ] }, "PolicyResponse": { "type": "object", "required": [ "id", "scope", "policy_type", "config", "enforcement", "enabled" ], "properties": { "capability": { "type": [ "string", "null" ] }, "config": { "type": "object" }, "conflict_report": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ConflictingInviteResponse" }, "description": "Informational: currently valid invites that this curfew will constrain (never mutated)." }, "created_at": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "enforcement": { "type": "string" }, "id": { "type": "string" }, "integration_id": { "type": [ "string", "null" ] }, "org_id": { "type": [ "string", "null" ] }, "physical_device_id": { "type": [ "string", "null" ] }, "policy_type": { "type": "string" }, "scope": { "type": "string", "description": "`org` | `integration` | `device`." }, "updated_at": { "type": [ "string", "null" ] } } }, "PortalRequest": { "type": "object", "required": [ "return_url" ], "properties": { "return_url": { "type": "string" } }, "additionalProperties": false }, "PortalResponse": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } }, "PostMeCallBlockPayload": { "type": "object", "required": [ "public_portal_id" ], "properties": { "public_portal_id": { "type": "string" } }, "additionalProperties": false }, "PostMeCallReportPayload": { "type": "object", "required": [ "session_id", "reason" ], "properties": { "details": { "type": [ "string", "null" ] }, "public_portal_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "session_id": { "type": "string" } }, "additionalProperties": false }, "PostMeDeviceTokenPayload": { "type": "object", "required": [ "platform", "token" ], "properties": { "platform": { "type": "string", "description": "One of: `ios_voip`, `ios_alert`, `android`." }, "token": { "type": "string" } } }, "PostMeDeviceTokenResponse": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "PostMePushSubscriptionPayload": { "type": "object", "required": [ "endpoint", "p256dh", "auth" ], "properties": { "auth": { "type": "string" }, "endpoint": { "type": "string" }, "p256dh": { "type": "string" } } }, "PowerFailBehavior": { "type": "string", "enum": [ "fail_safe", "fail_secure", "mechanical_always" ] }, "PrivacyExportResponse": { "type": "object", "required": [ "exported_at", "account", "memberships", "apartments", "invitations", "device_tokens", "dnd", "eula" ], "properties": { "account": {}, "apartments": { "type": "array", "items": {} }, "device_tokens": { "type": "array", "items": {} }, "dnd": {}, "eula": {}, "exported_at": { "type": "string" }, "invitations": { "type": "array", "items": {} }, "memberships": { "type": "array", "items": {} } } }, "ProductRequest": { "type": "object", "required": [ "name" ], "properties": { "external_url": { "type": [ "string", "null" ] }, "image_media_asset_id": { "type": [ "string", "null" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" } }, "additionalProperties": false }, "ProhibitMasterDoorInvitesPolicyConfig": { "type": "object", "description": "Typed `config` shape for `prohibit_master_door_invites`.", "required": [ "master_door_ids" ], "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "master_door_ids": { "type": "array", "items": { "type": "string" } }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] } } }, "ProviderType": { "type": "string", "description": "Integration provider type (e.g. homeassistant, knx, mqtt).", "enum": [ "go2rtc", "home_assistant", "knx", "mqtt", "palgate_cloud", "shelly_cloud", "shelly_websocket", "virtual_access", "virtual_demo", "waveshare", "tasmota" ] }, "PublicCatalogItem": { "type": "object", "required": [ "inventory_id", "product_id", "name", "price_cents" ], "properties": { "external_url": { "type": [ "string", "null" ] }, "image_media_asset_id": { "type": [ "string", "null" ] }, "inventory_id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "price_cents": { "type": "integer", "format": "int64" }, "product_id": { "type": "string" }, "stock_quantity": { "type": [ "integer", "null" ], "format": "int32" } } }, "PublicHoldView": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "$ref": "#/components/schemas/HoldMode" }, "reason": { "type": [ "string", "null" ] } } }, "PublicInviteExecuteRequest": { "type": "object", "required": [ "grant_id" ], "properties": { "grant_id": { "type": "string" }, "otp_challenge_id": { "type": [ "string", "null" ] }, "otp_code": { "type": [ "string", "null" ] }, "pin": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PublicInviteExecuteResponse": { "type": "object", "required": [ "ok" ], "properties": { "degradation": { "description": "Present when an over-capacity org slowed this open; clients show a readable warning." }, "door_auto_close_duration": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "door_open_duration_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "lights_auto_off_duration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LightsAutoOffDuration" } ] }, "message": { "type": [ "string", "null" ] }, "ok": { "type": "boolean" } } }, "PublicInviteGrant": { "oneOf": [ { "type": "object", "required": [ "id", "public_portal_id", "has_lights", "openable", "entry_kind", "kind" ], "properties": { "door_image_url": { "type": [ "string", "null" ], "description": "Presigned URL for door image (loaded asynchronously as card background)." }, "entry_kind": { "type": "string", "description": "Entry type from linked portal device (`virtual_access.entry_kind`). Default `door`." }, "has_lights": { "type": "boolean", "description": "Whether the portal has light devices configured (controls light button visibility)." }, "hold": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicHoldView", "description": "Effective door hold when any opener is held (guest-visible)." } ] }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "portal_open" ] }, "label": { "description": "Localized portal name: string or object { \"en\": \"...\", \"he\": \"...\" }." }, "open_rate_limit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicPortalOpenRateLimit", "description": "Enforced integration-scoped minimum interval between `switchable.open` calls.\nA second open inside the interval returns 429 `provider_open_rate_limited`." } ] }, "openable": { "type": "boolean", "description": "Whether the portal is linked to a live door device (i.e. can actually be opened).\nWhen false, the invite UI disables the open action (a misconfigured/unlinked portal)." }, "public_portal_id": { "type": "string" } } }, { "type": "object", "required": [ "id", "entity_id", "action_id", "kind" ], "properties": { "action_id": { "type": "string" }, "entity_id": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "entity_action" ] }, "label": {}, "payload": {} } } ] }, "PublicInviteOtpStartResponse": { "type": "object", "required": [ "challenge_id", "expires_at" ], "properties": { "challenge_id": { "type": "string" }, "expires_at": { "type": "string" } } }, "PublicInviteQuery": { "type": "object", "properties": { "device_id": { "type": [ "string", "null" ] } } }, "PublicInviteRenewalRequest": { "type": "object", "properties": { "note": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PublicInviteRenewalResponse": { "type": "object", "required": [ "ok" ], "properties": { "already_requested": { "type": [ "boolean", "null" ] }, "ok": { "type": "boolean" } } }, "PublicInviteResponse": { "type": "object", "required": [ "invite_token", "invite_url", "state", "grants", "location_mode" ], "properties": { "access_control": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicPortalAccessControl", "description": "Access-control integration summary (building name, address, photo)." } ] }, "allowed_weekdays": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "already_claimed": { "type": [ "boolean", "null" ] }, "blackout_dates": { "type": [ "array", "null" ], "items": { "type": "string" } }, "branding": {}, "building": { "description": "Building (integration) summary: `name` (LocalizedString) and optional `location` fields\nfrom integration config (`address`, `city`, `country`)." }, "curfew_windows": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CurfewWindowResponse" }, "description": "Effective forbidden hour windows for invitation access (informational)." }, "devices_count": { "type": [ "integer", "null" ], "format": "int32" }, "event_location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationResponse", "description": "Event location (address / map-picked coordinates) owned by this invite, distinct from the\nbuilding/portal location surfaced via `access_control`." } ] }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/PublicInviteGrant" } }, "invite_token": { "type": "string" }, "invite_url": { "type": "string", "description": "Guest-facing invite URL (shareable link for SMS/email)." }, "invitee_message": {}, "location_mode": { "$ref": "#/components/schemas/LocationBindingMode", "description": "How the invite resolves its event location: `none` (hide all location, including the\nbuilding address), `explicit` (own location), or `inherit` (building location). Lets the\nguest UI suppress the building address when the invite opts out of location entirely." }, "max_devices": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": [ "string", "null" ], "description": "Optional admin-defined label (management UI \"name\"); exposed for link previews and guests who already know the invite by name." }, "photo_url": { "type": [ "string", "null" ], "description": "Presigned URL for the invite's main photo (best-effort)." }, "renewal_requested": { "type": [ "boolean", "null" ], "description": "True when the authenticated requester already submitted a pending renewal request." }, "require_pin": { "type": "boolean" }, "require_verified_phone": { "type": "boolean" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InviteScheduleSnapshot" } ] }, "schedule_combined": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InviteScheduleCombined" } ] }, "schedule_entries": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/InviteScheduleEntrySnapshot" } }, "schedule_kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InviteScheduleKind" } ] }, "state": { "$ref": "#/components/schemas/PublicInviteState" }, "timezone": { "type": [ "string", "null" ], "description": "Org IANA timezone used to evaluate invitation curfews (`UTC` when unset)." }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] } } }, "PublicInviteSessionResponse": { "type": "object", "required": [ "ok", "invite_id", "guest_id" ], "properties": { "guest_id": { "type": "string", "description": "Stable per-device guest fingerprint (ULID). Either the one supplied by the client (cookie\nor `X-Guest-Id`) or a freshly minted one. Echoed so native clients can persist it and send\nit back via `X-Guest-Id` on subsequent public-access calls. Used only for audit\nattribution — it confers no access." }, "invite_id": { "type": "string", "description": "ULID of the invite (= value of the `oa_access_invite` cookie). Echoed\nin the body so non-browser clients can construct the cookie without\nrelying on a platform cookie jar for `HttpOnly` `Set-Cookie` responses." }, "ok": { "type": "boolean" } } }, "PublicInviteState": { "type": "string", "enum": [ "active", "expired", "revoked", "scheduled", "disabled", "not_found", "max_devices_reached" ] }, "PublicPortalAccessControl": { "type": "object", "required": [ "name" ], "properties": { "address": { "description": "Legacy alias for formatted_address (localized JSON)." }, "city": {}, "country": {}, "formatted_address": { "description": "Normalized street address (localized JSON)." }, "image_url": { "type": [ "string", "null" ], "description": "Presigned URL for the integration or location photo." }, "lat": { "type": [ "number", "null" ], "format": "double" }, "lng": { "type": [ "number", "null" ], "format": "double" }, "name": { "description": "Integration / building name (localized JSON)." }, "notes": {} } }, "PublicPortalCreateSessionRequest": { "type": "object", "description": "Map of light entity ULID to auto-off duration in seconds (re-exported for OpenAPI).", "required": [ "target_entity_id", "mode" ], "properties": { "mode": { "type": "string" }, "target_entity_id": { "type": "string" } }, "additionalProperties": false }, "PublicPortalCreateSessionResponse": { "type": "object", "required": [ "session_id", "caller_token", "expires_at", "peerjs", "caller_peer_id", "callee_peer_id", "callees_notified" ], "properties": { "callee_peer_id": { "type": "string" }, "callees_notified": { "type": "boolean", "description": "True when at least one callee had a push subscription so notification was sent (or attempted)." }, "caller_peer_id": { "type": "string" }, "caller_token": { "type": "string" }, "expires_at": { "type": "string" }, "peerjs": { "$ref": "#/components/schemas/PeerJsConfig" }, "session_id": { "type": "string" } } }, "PublicPortalLight": { "type": "object", "required": [ "entity_id" ], "properties": { "effective_auto_off_duration": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "entity_id": { "type": "string" }, "label": {} } }, "PublicPortalMode": { "type": "string", "enum": [ "guest_directory", "resident_quick_open", "guest_quick_open" ] }, "PublicPortalOpenRateLimit": { "type": "object", "required": [ "integration_id", "min_interval_ms" ], "properties": { "integration_id": { "type": "string" }, "min_interval_ms": { "type": "integer", "format": "int64", "description": "Enforced minimum milliseconds between `switchable.open` calls on this integration.", "minimum": 0 } } }, "PublicPortalReachableResponse": { "type": "object", "required": [ "reachable" ], "properties": { "reachable": { "type": "boolean" } } }, "PublicPortalResponse": { "type": "object", "required": [ "public_portal_id", "mode", "entry_kind" ], "properties": { "access_control": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicPortalAccessControl", "description": "Access-control integration summary (building name, address, photo)." } ] }, "access_directory": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicPortalAccessControl", "description": "Visitor directory device summary for this portal (building directory name, photo)." } ] }, "branding": {}, "door_effective_auto_off_duration": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "door_image_url": { "type": [ "string", "null" ], "description": "Image URL for the door (presigned S3 URL from media service)." }, "entry_kind": { "type": "string", "description": "Entry type from linked portal device (`virtual_access.entry_kind`). Default `door`." }, "hold": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicHoldView", "description": "Effective door hold when any opener is held (guest-visible)." } ] }, "lights": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PublicPortalLight" } }, "mode": { "$ref": "#/components/schemas/PublicPortalMode" }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "open_rate_limit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicPortalOpenRateLimit" } ] }, "public_portal_id": { "type": "string" } } }, "PublicPortalTarget": { "type": "object", "required": [ "target_id", "display_name", "floor", "allowed_actions" ], "properties": { "allowed_actions": { "type": "array", "items": { "type": "string" } }, "apartment_label": {}, "apartment_number": { "type": [ "integer", "null" ], "format": "int64" }, "call_available": { "type": [ "boolean", "null" ], "description": "True when at least one resident (receives_calls) exists. When false, voice/video are excluded from allowed_actions." }, "display_name": {}, "floor": {}, "floor_number": { "type": [ "integer", "null" ], "format": "int64" }, "image": { "type": [ "string", "null" ] }, "require_video": { "type": [ "boolean", "null" ] }, "target_id": { "type": "string" } } }, "PublicPortalTargetsResponse": { "type": "object", "required": [ "targets" ], "properties": { "floor_order": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Building `floor_order` from virtual_access integration config (canonical keys)." }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPortalTarget" } } } }, "PublicSessionResponse": { "type": "object", "required": [ "session_id", "state", "role", "peerjs", "caller_peer_id", "callee_peer_id" ], "properties": { "building_display_name": { "description": "Integration / building name (localized JSON)." }, "call_target_display_name": { "description": "Localized apartment / unit title for call UI (caller/callee)." }, "call_target_location_line": { "type": [ "string", "null" ], "description": "Single line for apartment + floor (e.g. \"3 · Floor 2\")." }, "callee_peer_id": { "type": "string" }, "callees_notified": { "type": [ "boolean", "null" ], "description": "Whether at least one callee received a push notification. Caller uses this to skip peer-unavailable retries when false." }, "caller_peer_id": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "has_lights": { "type": [ "boolean", "null" ], "description": "Whether the portal has light devices configured. Callee-only." }, "mode": { "type": [ "string", "null" ], "description": "Call mode: \"voice\" or \"video\". Video on by default when mode is \"video\"." }, "peerjs": { "$ref": "#/components/schemas/PeerJsConfig" }, "portal_camera_device_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "role": { "$ref": "#/components/schemas/PublicSessionRole" }, "session_id": { "type": "string" }, "state": { "type": "string" } } }, "PublicSessionRole": { "type": "string", "enum": [ "caller", "callee" ] }, "PublicSessionStreamsResponse": { "type": "object", "required": [ "device_ids" ], "properties": { "device_ids": { "type": "array", "items": { "type": "string" }, "description": "Camera device IDs for the portal. Stream URLs resolved client-side or via future API." } } }, "PublicStoreResponse": { "type": "object", "required": [ "public_id", "store_id", "name", "currency", "registration_requested", "is_member", "items" ], "properties": { "currency": { "type": "string" }, "is_member": { "type": "boolean", "description": "Whether the authenticated caller (if any) is already an active member." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCatalogItem" } }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "public_id": { "type": "string" }, "registration_requested": { "type": "boolean", "description": "Whether the authenticated caller (if any) already has a pending registration request." }, "store_id": { "type": "string" } } }, "PurchaseRequest": { "type": "object", "required": [ "inventory_id" ], "properties": { "billing_account_id": { "type": [ "string", "null" ], "description": "Optional billing account to charge (must be chargeable by the buyer). Defaults to the\nmember's account." }, "inventory_id": { "type": "string" }, "quantity": { "type": [ "integer", "null" ], "format": "int32" } }, "additionalProperties": false }, "PutHoldRequest": { "type": "object", "required": [ "mode" ], "properties": { "include_lights": { "type": [ "boolean", "null" ] }, "kind": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "recurrence": { "type": [ "object", "null" ] }, "until": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PutLocationBindingRequest": { "type": "object", "required": [ "mode" ], "properties": { "location_id": { "type": [ "string", "null" ] }, "mode": { "$ref": "#/components/schemas/LocationBindingMode" } }, "additionalProperties": false }, "QuietHoursPolicyConfig": { "type": "object", "description": "Typed `config` shape for `quiet_hours`.", "required": [ "start", "end" ], "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector" } ] }, "end": { "type": "string", "description": "Inclusive local end of the window, in `HH:MM`; a later end wraps midnight." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector" } ] }, "start": { "type": "string", "description": "Inclusive local start of the window, in `HH:MM`." } } }, "QuotaKey": { "type": "string", "description": "A metered resource. Lifetime keys count current rows in their source-of-truth\ntable; temporal keys accumulate via `usage_events` + `quota_counters`.\n\nString form (used in DB columns and JSON responses) is snake_case via `EnumString`.", "enum": [ "org_users", "organizations", "integrations", "devices", "entities", "zones", "api_keys", "door_opens", "voice_invocations", "portal_views", "video_sessions", "video_session_duration_seconds", "scripting_executions", "ai_requests", "geocoding_requests" ] }, "QuotaOverrideRequest": { "type": "object", "required": [ "subject_type", "subject_id", "quota_key", "limit_value" ], "properties": { "expires_at": { "type": [ "string", "null" ] }, "limit_value": { "type": "integer", "format": "int64" }, "period": { "type": [ "string", "null" ] }, "quota_key": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "subject_id": { "type": "string" }, "subject_type": { "type": "string" } }, "additionalProperties": false }, "QuotaPeriod": { "type": "string", "description": "Window kind for a quota. `Lifetime` is \"ever / right now\"; `Day`/`Week`/`Month`\nreset on calendar boundaries (UTC); `PerSession` resets per opaque session id.", "enum": [ "lifetime", "day", "week", "month", "per_session" ] }, "QuotaReport": { "type": "object", "description": "Full quota report for an org; powers `/dashboard/billing`.", "required": [ "org_id", "items" ], "properties": { "degradation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DegradationStatus", "description": "Over-capacity remediation snapshot. Present only when the degradation system is\nenabled and the caller is permitted to see it; `null` otherwise." } ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/QuotaUsage" } }, "org_id": { "type": "string" }, "tier_slug": { "type": [ "string", "null" ] } } }, "QuotaUnit": { "type": "string", "description": "Machine-readable unit for a quota quantity. `Count` is a plain integer of the\nkey's noun (door opens, devices, …); `Seconds` is a duration clients may render\nin larger units (e.g. minutes for video chat).", "enum": [ "count", "seconds" ] }, "QuotaUsage": { "type": "object", "description": "Single (key, period) entry in a usage report.", "required": [ "key", "period", "unit", "period_label", "current", "limit" ], "properties": { "current": { "type": "integer", "format": "int64", "minimum": 0 }, "key": { "$ref": "#/components/schemas/QuotaKey" }, "limit": { "$ref": "#/components/schemas/EffectiveLimit" }, "period": { "$ref": "#/components/schemas/QuotaPeriod" }, "period_end": { "type": [ "string", "null" ], "description": "Window end ([RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)). `null` for `Lifetime`." }, "period_label": { "type": "string", "description": "Window label (e.g. `lifetime`, `month:2026-04`). Stable across reports." }, "period_start": { "type": [ "string", "null" ], "description": "Window start ([RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)). `null` for `Lifetime`." }, "unit": { "$ref": "#/components/schemas/QuotaUnit", "description": "Machine-readable unit of `current`/`limit` (e.g. `count`, `seconds`)." } } }, "ReadinessIssue": { "type": "object", "required": [ "code", "severity" ], "properties": { "code": { "$ref": "#/components/schemas/ReadinessIssueCode" }, "severity": { "$ref": "#/components/schemas/ReadinessSeverity" }, "subject": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReadinessSubject" } ] } } }, "ReadinessIssueCode": { "type": "string", "enum": [ "site_no_openers", "site_no_doors", "site_no_door_with_opener", "site_no_portals", "site_no_portal_with_usable_door", "site_no_intercom_directory", "door_no_opener", "door_opener_unresolved", "door_life_safety_incomplete", "door_no_portal", "portal_no_door", "portal_door_missing", "portal_door_no_opener", "portal_no_directory", "intercom_no_apartments", "apartment_no_residents", "site_no_people" ] }, "ReadinessSection": { "type": "string", "enum": [ "doors", "portals", "virtual_intercom", "people" ] }, "ReadinessSeverity": { "type": "string", "description": "Ordered from least to most severe; `Ord` is used to roll sections up.", "enum": [ "ok", "incomplete", "partial", "blocking" ] }, "ReadinessSubject": { "type": "object", "required": [ "kind", "id" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ReadinessSubjectKind" } } }, "ReadinessSubjectKind": { "type": "string", "enum": [ "door", "portal", "apartment", "directory" ] }, "RedeemInvitationRequest": { "type": "object", "required": [ "token", "pin" ], "properties": { "pin": { "type": "string" }, "token": { "type": "string" } }, "additionalProperties": false }, "RedeemInvitationResponse": { "type": "object", "required": [ "org_id", "user_id", "default_roles" ], "properties": { "default_roles": { "type": "array", "items": { "type": "string" } }, "merge": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MergeOfferDto" } ] }, "org_id": { "type": "string" }, "user_id": { "type": "string" } } }, "RegistrationStatus": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "RequireStepUpPolicyConfig": { "type": "object", "description": "Typed `config` shape for `require_step_up`. The runtime also accepts a single\nprincipal string in `applies_to`; the array form is canonical for generated clients.", "properties": { "applies_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyPrincipalSelector", "description": "Principal kind(s) requiring confirmation; unknown and empty values are rejected." } ] }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Optional provider-derived output/channel selector." } ] } } }, "ResolveCandidate": { "type": "object", "required": [ "id", "resource_type", "label", "score" ], "properties": { "entity_type": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "label": { "type": "string" }, "resource_type": { "type": "string" }, "score": { "type": "number", "format": "double" }, "why": { "type": [ "string", "null" ] } } }, "ResolveRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "resource_type": { "type": [ "string", "null" ] } } }, "ResolveResponse": { "type": "object", "required": [ "query", "ambiguous", "candidates" ], "properties": { "ambiguous": { "type": "boolean" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/ResolveCandidate" } }, "query": { "type": "string" } } }, "ResolvedLocationResponse": { "type": "object", "required": [ "binding" ], "properties": { "binding": { "$ref": "#/components/schemas/LocationBindingResponse" }, "resolved": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationResponse" } ] } } }, "ResourceImageUrlResponse": { "type": "object", "description": "Resource-scoped image URL response (does not expose asset_id).\nWhen no image is uploaded, returns 204 No Content (not 404).", "required": [ "url", "expires_in_seconds" ], "properties": { "expires_in_seconds": { "type": "integer", "format": "int64", "minimum": 0 }, "url": { "type": "string" } } }, "ResourceLifecycle": { "type": "object", "description": "Soft-delete and audit timestamps on a persisted resource.\n\nFlattened onto HTTP JSON so `created_at` sits next to `id` / `name`. Absent\nfields are omitted (`None`).", "properties": { "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "hard_delete_at": { "type": [ "string", "null" ], "format": "date-time" }, "purge_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ResourceState": { "type": "string", "description": "Per-resource degradation state (mirrors the `degradation_state` column).", "enum": [ "active", "flagged", "degraded", "marked_for_delete" ] }, "ReverseGeocodeRequest": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" }, "locale": { "type": [ "string", "null" ], "description": "Preferred locale (app code or BCP-47) for the resolved text. Defaults to `en`." } }, "additionalProperties": false }, "ReverseGeocodeResponse": { "type": "object", "description": "Resolved address for a map-picked point. Text fields are single-locale (the requested\n`locale`), ready for the client to wrap under its current locale. Empty strings mean the point\nhas no address (e.g. open water); the coordinates are always echoed back.", "required": [ "formatted_address", "city", "country", "lat", "lng" ], "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "formatted_address": { "type": "string" }, "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" }, "place_id": { "type": [ "string", "null" ] } } }, "Role": { "type": "string", "description": "A role name (e.g. admin, users:read) assigned to a user in an org." }, "SearchOrgsQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" }, { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "description": "Free-text query matched as a case-insensitive substring of the org name." } } } ] }, "SearchUsersQuery": { "type": "object", "properties": { "exclude_ids": { "type": [ "string", "null" ], "description": "Comma-separated user IDs to exclude" }, "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "org_id": { "type": [ "string", "null" ], "description": "Filter by org subtree (ignored when `scope=all`)." }, "q": { "type": [ "string", "null" ], "description": "Search text (ILIKE on name and email)" }, "scope": { "type": [ "string", "null" ], "description": "`all`: search every user in the database (requires `users:list` on the root org). Otherwise org-scoped." } } }, "SectionReadiness": { "type": "object", "required": [ "section", "severity", "blocking_count", "incomplete_count", "issues" ], "properties": { "blocking_count": { "type": "integer", "format": "int32", "description": "Issues whose subject cannot be used, including site-scoped gaps.", "minimum": 0 }, "incomplete_count": { "type": "integer", "format": "int32", "minimum": 0 }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ReadinessIssue" } }, "section": { "$ref": "#/components/schemas/ReadinessSection" }, "severity": { "$ref": "#/components/schemas/ReadinessSeverity", "description": "Aggregate severity of the section, not the worst issue severity: see the\nmodule docs for how subject-scoped issues degrade a section to\n[`ReadinessSeverity::Partial`]." } } }, "SelectionPolicy": { "type": "string", "description": "How excess resources are chosen when the admin has not pinned survivors via `quota_keep`.", "enum": [ "newest_first", "oldest_first", "least_recently_used", "manual" ] }, "SetDoorRestrictionsPayload": { "type": "object", "required": [ "apartment_entity_ids" ], "properties": { "apartment_entity_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "SetOrgTimezoneRequest": { "type": "object", "properties": { "timezone": { "type": [ "string", "null" ], "description": "IANA timezone. Empty or null clears to UTC fallback." } }, "additionalProperties": false }, "SetResourceKeepRequest": { "type": "object", "required": [ "resource", "resource_id", "keep" ], "properties": { "keep": { "type": "boolean", "description": "`true` pins the resource (kept within cap); `false` lets it be flagged as excess." }, "resource": { "$ref": "#/components/schemas/CapacityResource", "description": "Which capacity resource the row belongs to." }, "resource_id": { "type": "string", "description": "The resource id to pin or unpin." } }, "additionalProperties": false }, "SetSelectionPolicyRequest": { "type": "object", "required": [ "policy" ], "properties": { "policy": { "$ref": "#/components/schemas/SelectionPolicy", "description": "How excess resources are chosen for the lifecycle: `newest_first`, `oldest_first`,\n`least_recently_used`, or `manual`." } }, "additionalProperties": false }, "SingleResourceOutputOptions": { "type": "object", "description": "Options for single-resource operations (get/create/update/delete/restore).\nUsed when listing/filtering by `only_deleted` is not applicable.", "required": [ "include_deleted" ], "properties": { "include_deleted": { "type": "boolean", "description": "If true, include soft-deleted items in results." } } }, "SingleResourceOutputOptionsQuery": { "type": "object", "description": "Query parameters for single-resource operations (get/create/update/delete/restore).\nOmits `only_deleted` since it only applies to list endpoints.", "properties": { "include_deleted": { "type": "boolean" } } }, "SiteReadiness": { "type": "object", "required": [ "severity", "usable", "sections", "suppressed_sections" ], "properties": { "sections": { "type": "array", "items": { "$ref": "#/components/schemas/SectionReadiness" } }, "severity": { "$ref": "#/components/schemas/ReadinessSeverity" }, "suppressed_sections": { "type": "array", "items": { "$ref": "#/components/schemas/ReadinessSection" } }, "usable": { "type": "boolean" } } }, "SkillResponse": { "type": "object", "required": [ "id", "org_id", "agent_id", "name", "version", "trigger_event_types", "steps", "enabled" ], "properties": { "agent_id": { "type": "string" }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SkillStep" } }, "trigger_event_types": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer", "format": "int32" } } }, "SkillStep": { "type": "object", "required": [ "tool" ], "properties": { "args": {}, "tool": { "type": "string" } } }, "StatementResponse": { "type": "object", "required": [ "month", "currency", "total_cents", "purchase_count", "items" ], "properties": { "currency": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/StorePurchase" } }, "month": { "type": "string" }, "purchase_count": { "type": "integer", "format": "int64", "minimum": 0 }, "total_cents": { "type": "integer", "format": "int64" } } }, "Store": { "type": "object", "description": "A storefront. Many stores may exist per org.", "required": [ "id", "org_id", "name", "timezone", "currency" ], "properties": { "branding_overrides": { "type": [ "object", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code for prices/statements." }, "deleted_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "org_id": { "type": "string" }, "timezone": { "type": "string", "description": "IANA timezone used to derive monthly billing cycles." }, "updated_at": { "type": [ "string", "null" ] } } }, "StoreInventory": { "type": "object", "description": "Per-store listing of a catalog product. `stock_quantity` `None` means untracked (no\nenforcement); `Some(n)` is enforced and decremented on purchase.", "required": [ "id", "store_id", "product_id", "price_cents", "is_active" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "price_cents": { "type": "integer", "format": "int64" }, "product_id": { "type": "string" }, "stock_quantity": { "type": [ "integer", "null" ], "format": "int32" }, "store_id": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } } }, "StoreMember": { "type": "object", "description": "Store membership. `Pending` awaits admin approval; `Removed` keeps the row (history) but\nblocks purchasing.", "required": [ "id", "store_id", "user_id", "role", "status" ], "properties": { "billing_account_id": { "type": [ "string", "null" ], "description": "Account purchases are charged to. `None` falls back to the member's personal account." }, "created_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "removed_at": { "type": [ "string", "null" ] }, "role": { "$ref": "#/components/schemas/StoreMemberRole" }, "status": { "$ref": "#/components/schemas/StoreMemberStatus" }, "store_id": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] }, "user_id": { "type": "string" } } }, "StoreMemberRole": { "type": "string", "enum": [ "admin", "member" ] }, "StoreMemberStatus": { "type": "string", "enum": [ "pending", "active", "removed" ] }, "StorePortal": { "type": "object", "description": "Logical QR portal for a store (stable for printed QR codes). Mirrors the access portal.", "required": [ "id", "org_id", "store_id", "public_id", "name" ], "properties": { "branding_overrides": { "type": [ "object", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "org_id": { "type": "string" }, "public_id": { "type": "string" }, "store_id": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } } }, "StoreProduct": { "type": "object", "description": "Org-scoped catalog product. Soft-deleted products are retained (`purge_at`) so historical\nstatements and audit stay readable.", "required": [ "id", "org_id", "name" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "image_media_asset_id": { "type": [ "string", "null" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "org_id": { "type": "string" }, "purge_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "StorePurchase": { "type": "object", "description": "Immutable purchase ledger row (system of record for billing/statements).", "required": [ "id", "org_id", "store_id", "unit_price_cents", "quantity", "total_cents", "currency", "product_name_snapshot", "created_at" ], "properties": { "billing_account_id": { "type": [ "string", "null" ] }, "buyer_user_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "id": { "type": "string" }, "inventory_id": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "product_id": { "type": [ "string", "null" ] }, "product_name_snapshot": { "$ref": "#/components/schemas/LocalizedString", "description": "Localized product name captured at purchase time." }, "quantity": { "type": "integer", "format": "int32" }, "store_id": { "type": "string" }, "total_cents": { "type": "integer", "format": "int64" }, "unit_price_cents": { "type": "integer", "format": "int64" } } }, "StoreRegistrationRequest": { "type": "object", "description": "Pending store registration awaiting admin approval.", "required": [ "id", "org_id", "store_id", "user_id", "status" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/RegistrationStatus" }, "store_id": { "type": "string" }, "user_id": { "type": "string" } } }, "SubscriptionRef": { "type": "object", "description": "External subscription reference.", "required": [ "provider", "external_id", "tier_slug", "status" ], "properties": { "external_id": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "tier_slug": { "type": "string" } } }, "TasmotaConnectionConfig": { "type": "object", "required": [ "mqtt_host", "mqtt_port", "mqtt_username", "mqtt_password", "mqtt_client_id", "mqtt_tls", "command_topic", "web_password" ], "properties": { "command_topic": { "type": "string" }, "mqtt_client_id": { "type": "string" }, "mqtt_host": { "type": "string" }, "mqtt_password": { "type": "string" }, "mqtt_port": { "type": "integer", "format": "int32", "minimum": 0 }, "mqtt_tls": { "type": "boolean" }, "mqtt_username": { "type": "string" }, "power_topics": { "type": "array", "items": { "$ref": "#/components/schemas/TasmotaPowerTopic" } }, "web_password": { "type": "string" } } }, "TasmotaLanProvisionRequest": { "type": "object", "required": [ "device_host" ], "properties": { "device_host": { "type": "string" } } }, "TasmotaPowerTopic": { "type": "object", "required": [ "gpio", "channel_index", "topic" ], "properties": { "channel_index": { "type": "integer", "format": "int32", "minimum": 0 }, "gpio": { "type": "integer", "format": "int32", "minimum": 0 }, "topic": { "type": "string" } } }, "TasmotaProvisioningResponse": { "type": "object", "required": [ "backlog", "connection" ], "properties": { "backlog": { "type": "string" }, "connection": { "$ref": "#/components/schemas/TasmotaConnectionConfig" }, "mqtt_ca_pem": { "type": [ "string", "null" ] } } }, "TransferIntegrationRequest": { "type": "object", "required": [ "target_org_id" ], "properties": { "confirm": { "type": "boolean", "description": "Must be `true` when the preview reports side-effect warnings; otherwise the request is\nrejected with `error_code = \"confirmation_required\"`." }, "mode": { "$ref": "#/components/schemas/TransferModeDto" }, "target_org_id": { "type": "string", "description": "Destination organization id (must differ from the integration's current org)." } }, "additionalProperties": false }, "TransferIntegrationResponse": { "allOf": [ { "$ref": "#/components/schemas/IntegrationResponse" }, { "type": "object", "required": [ "mode", "source_org_id", "target_org_id", "affected", "warnings" ], "properties": { "affected": { "$ref": "#/components/schemas/AffectedCounts" }, "mode": { "type": "string" }, "source_org_id": { "type": "string" }, "target_org_id": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Side-effect warning codes that applied to this transfer." } } } ] }, "TransferModeDto": { "type": "string", "enum": [ "move", "duplicate" ] }, "TransferPreviewResponse": { "type": "object", "required": [ "source_org_id", "mode", "affected", "warnings", "notes", "requires_confirmation" ], "properties": { "affected": { "$ref": "#/components/schemas/AffectedCounts" }, "mode": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Informational notes the dashboard should display before transferring. Unlike `warnings`,\nthese never gate `requires_confirmation` — they inform without requiring a confirm step." }, "requires_confirmation": { "type": "boolean", "description": "When true, `POST /transfer` must be called with `confirm = true`." }, "source_org_id": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Side-effect warning codes the dashboard should surface before confirming." } } }, "TranslateLocaleContentRequest": { "type": "object", "required": [ "source_locale", "title", "body", "target_locales" ], "properties": { "body": { "type": "string" }, "source_locale": { "type": "string" }, "target_locales": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" } }, "additionalProperties": false }, "TranslateLocaleContentResponse": { "type": "object", "required": [ "translations" ], "properties": { "translations": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LocaleContentTranslation" }, "propertyNames": { "type": "string" } } } }, "UpdateAccessInviteRequest": { "type": "object", "properties": { "creation_justification": { "type": [ "string", "null" ], "description": "Why this invitation was created (required when `invitation_require_justification` applies)." }, "curfew_exempt": { "type": [ "boolean", "null" ], "description": "Admin-only emergency exception: skip invitation curfew at redemption." }, "disabled_justification": { "type": [ "string", "null" ] }, "expires_in": { "type": [ "string", "null" ], "description": "Duration per [RFC 5545 §3.3.6](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.6) (ISO 8601 `P1D`, `PT1H`, …; no months/years) or compact tokens `s`/`m`/`h`/`d`/`w` (`M` is minutes). Max 3650d (10 years). `1y` is rejected. Measured from resolved start (including now when `valid_from` is omitted). Mutually exclusive with `valid_to`." }, "invite_recurrence": {}, "invitee_message": {}, "invitee_phone": { "type": [ "string", "null" ], "description": "Omitted leaves the stored phone unchanged; JSON `null` clears it." }, "is_enabled": { "type": [ "boolean", "null" ] }, "location_id": { "type": [ "string", "null" ], "description": "Only consumed when `location_mode` is `explicit`: the reusable org location id to bind.\nWhen the mode is `explicit` and this is absent, the existing bound location is kept." }, "location_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationBindingMode", "description": "When set, replaces the event-location mode (`none`, `explicit`, or `inherit`). Absent\nleaves the mode and location unchanged." } ] }, "max_devices": { "type": [ "integer", "null" ], "format": "int32", "description": "Virtual keycard limit: max unique devices allowed. JSON `null` means unlimited." }, "max_uses": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": [ "string", "null" ] }, "pin": { "type": [ "string", "null" ], "description": "Omitted leaves the stored PIN unchanged; JSON `null` clears it." }, "portal_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "When set, replaces portal grants. Array order is the display order on the public invite page." }, "schedules": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/InviteScheduleEntryInput" }, "description": "When set, replaces all schedule entries. Required when changing times/recurrence on an\ninvite that already has multiple schedule entries." }, "valid_from": { "type": [ "string", "null" ], "description": "[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) window start (UTC). When omitted, the window opens at request time." }, "valid_to": { "type": [ "string", "null" ], "description": "[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) window end (UTC). Mutually exclusive with `expires_in`." } }, "additionalProperties": false }, "UpdateAccessPortalRequest": { "type": "object", "properties": { "device_id": { "type": [ "string", "null" ], "description": "Door device id. Must be a virtual_access_portal device in this integration. Use null to unlink." }, "directory_id": { "type": [ "string", "null" ], "description": "Directory device id. Must be a virtual_access_directory device in this integration. Use null to unlink." }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] } }, "additionalProperties": false }, "UpdateAgentRequest": { "type": "object", "properties": { "allowed_entity_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_portal_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_tool_names": { "type": [ "array", "null" ], "items": { "type": "string" } }, "confirmation_mode": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "expires_in": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] } } }, "UpdateApartmentResidentPayload": { "type": "object", "properties": { "date_of_birth": { "type": [ "string", "null" ] }, "is_child": { "type": [ "boolean", "null" ] }, "receives_calls": { "type": [ "boolean", "null" ] }, "role": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "expires_at": { "type": [ "string", "null" ], "description": "[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) absolute expiration timestamp (UTC). Mutually exclusive with `expires_in`. Optional; if omitted, expiry is unchanged." }, "expires_in": { "type": [ "string", "null" ], "description": "Duration per [RFC 5545 §3.3.6](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.6) (ISO 8601 `P1D`, `PT1H`, …; no months/years) or compact tokens `s`/`m`/`h`/`d`/`w` (`M` is minutes). Max 3650d (10 years). `1y` is rejected. Mutually exclusive with `expires_at`. Optional; if omitted, expiry is unchanged." }, "name": { "type": "string" } } }, "UpdateDeviceRequest": { "type": "object", "properties": { "device_metadata": {}, "external_id": { "type": [ "string", "null" ] }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] } }, "additionalProperties": false }, "UpdateEntityRequest": { "type": "object", "properties": { "channel_index": { "type": [ "integer", "null" ], "format": "int32" }, "entity_type": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "description": "Update (replace) persisted entity metadata.\n\n- `None`: no change\n- `Some(None)`: clear metadata\n- `Some(Some(map))`: replace with provided map", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "Update entity name.\n\n- `None`: no change\n- `Some(None)`: clear\n- `Some(Some(name))`: set (trimmed; empty becomes clear)" }, "zone_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateIntegrationRequest": { "type": "object", "properties": { "config": { "description": "Tri-state patch semantics for `config`:\n- field omitted: do not change config\n- `\"config\": null`: clear config (set to None)\n- `\"config\": { ... }`: replace config (do not merge)" }, "enabled": { "type": [ "boolean", "null" ] }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString", "description": "Human-friendly name for this integration.\nAccepts string or LocalizedString map, e.g. { \"en\": \"Name\", \"he\": \"שם\" }." } ] }, "provider_type": { "type": [ "string", "null" ] }, "secrets": { "description": "Tri-state patch semantics for `secrets` (stored in Secrets Manager):\n- field omitted: do not change secrets\n- `\"secrets\": null`: clear secrets\n- `\"secrets\": { ... }`: replace secrets" } }, "additionalProperties": false }, "UpdateInventoryRequest": { "type": "object", "required": [ "price_cents" ], "properties": { "is_active": { "type": [ "boolean", "null" ] }, "price_cents": { "type": "integer", "format": "int64" }, "stock_quantity": { "type": [ "integer", "null" ], "format": "int32" } }, "additionalProperties": false }, "UpdateMemberRequest": { "type": "object", "properties": { "billing_account_id": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateOrganizationRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "parent_id": { "type": [ "string", "null" ], "description": "Move the org under a new parent (re-parent). When present and different from the current\nparent, the org (and its whole subtree) is moved under `parent_id`. Requires `admin` on the\ndestination parent (or an ancestor) in addition to `update_orgs` on the org being moved." } }, "additionalProperties": false }, "UpdatePolicyRequest": { "type": "object", "properties": { "capability": { "type": [ "string", "null" ] }, "config": { "type": [ "object", "null" ], "description": "Omitted preserves the current config; explicit JSON null is rejected rather than\nbeing silently treated as an omitted field." }, "enabled": { "type": [ "boolean", "null" ] }, "enforcement": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateStoreRequest": { "type": "object", "required": [ "name" ], "properties": { "branding_overrides": { "type": [ "object", "null" ] }, "currency": { "type": [ "string", "null" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "timezone": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateUserRequest": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "phone": { "$ref": "#/components/schemas/PhonePatch", "description": "E.164 phone. Send `null` to clear; omit field to leave unchanged. When set,\n`phone_verified_at` is stamped server-side (admin-attested verification)." } }, "additionalProperties": false }, "UpdateWebhookRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "url": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateZoneRequest": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ] }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "parent_zone_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UsageActor": { "type": "object", "description": "The actor behind a usage entry. Registered users and guests are kept in disjoint fields so the\n(spoofable) guest fingerprint is never confused with a trusted user identity by the client.", "required": [ "kind" ], "properties": { "guest_id": { "type": [ "string", "null" ], "description": "Per-device guest fingerprint. Present only when `kind == \"guest\"`." }, "kind": { "type": "string", "description": "`user`, `guest`, `system`, `api_key`, … (mirrors `audit_events.actor_kind`)." }, "user_id": { "type": [ "string", "null" ], "description": "Trusted registered-user id. Present only when `kind == \"user\"`." } } }, "User": { "allOf": [ { "$ref": "#/components/schemas/ResourceLifecycle" }, { "type": "object", "required": [ "id", "name", "email" ], "properties": { "email": { "type": "string", "description": "Email address (used for login and provisioning). May be a synthetic placeholder for phone-only accounts (`{ulid}@phone.openapp.local`)." }, "id": { "type": "string", "description": "Unique identifier (ULID)." }, "merged_into_user_id": { "type": [ "string", "null" ], "description": "When set, this row was absorbed into another user. Follow for live identity." }, "name": { "$ref": "#/components/schemas/LocalizedString", "description": "Display name." }, "phone": { "type": [ "string", "null" ], "description": "Verified E.164 phone when set." }, "phone_verified_at": { "type": [ "string", "null" ] } } } ], "description": "A provisioned user (identity) in the system." }, "UserInvitationDto": { "type": "object", "required": [ "id", "org_id", "channel", "status", "default_roles", "expires_at", "sent_count", "invited_by_user_id", "created_at" ], "properties": { "accepted_user_id": { "type": [ "string", "null" ] }, "channel": { "type": "string", "description": "`sms`, `email`, or `both`." }, "created_at": { "type": "string" }, "default_roles": { "type": "array", "items": { "type": "string" } }, "email": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "invited_by_user_id": { "type": "string" }, "last_sent_at": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "phone": { "type": [ "string", "null" ], "description": "SMS recipient when the invite includes a phone (E.164)." }, "sent_count": { "type": "integer", "format": "int32" }, "site_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvitationSiteAccessDto" } ] }, "status": { "type": "string" } } }, "UserResponse": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "required": [ "email_is_synthetic", "roles" ], "properties": { "email_is_synthetic": { "type": "boolean", "description": "True when `email` is the internal `{ulid}@phone.openapp.local` placeholder." }, "roles": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "propertyNames": { "type": "string" } } } } ] }, "VirtualAccessOpenResponse": { "type": "object", "required": [ "ok" ], "properties": { "door_auto_close_duration": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "door_open_duration_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "lights_auto_off_duration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LightsAutoOffDuration" } ] }, "ok": { "type": "boolean" } } }, "WaveshareConnectionConfig": { "type": "object", "required": [ "mqtt_client_id", "mqtt_username", "mqtt_password", "mqtt_subscribe_topic", "mqtt_publish_topic" ], "properties": { "mqtt_client_id": { "type": "string" }, "mqtt_password": { "type": "string" }, "mqtt_publish_topic": { "type": "string" }, "mqtt_subscribe_topic": { "type": "string" }, "mqtt_username": { "type": "string" } } }, "WaveshareProvisioningDiffEntry": { "type": "object", "required": [ "key", "stored", "current" ], "properties": { "current": { "type": "string" }, "key": { "type": "string" }, "stored": { "type": "string" } } }, "WaveshareProvisioningStatusResponse": { "type": "object", "required": [ "stale", "stored", "current", "diff" ], "properties": { "current": { "$ref": "#/components/schemas/WaveshareConnectionConfig" }, "diff": { "type": "array", "items": { "$ref": "#/components/schemas/WaveshareProvisioningDiffEntry" } }, "stale": { "type": "boolean" }, "stored": { "$ref": "#/components/schemas/WaveshareConnectionConfig" } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "org_id", "url", "enabled" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "id": { "type": "string" }, "last_delivery_at": { "type": [ "string", "null" ] }, "last_delivery_status": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] }, "url": { "type": "string" } } }, "WebhookTestResponse": { "type": "object", "required": [ "delivered" ], "properties": { "delivered": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "status_code": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "Zone": { "allOf": [ { "$ref": "#/components/schemas/ResourceLifecycle" }, { "type": "object", "required": [ "id", "integration_id", "name" ], "properties": { "external_id": { "type": [ "string", "null" ], "description": "External ID from the integration." }, "id": { "type": "string", "description": "Unique identifier (ULID)." }, "integration_id": { "type": "string", "description": "Integration this zone belongs to." }, "name": { "$ref": "#/components/schemas/LocalizedString", "description": "Zone name." }, "parent_zone_id": { "type": [ "string", "null" ], "description": "Parent zone for hierarchy." } } } ], "description": "A logical or physical space (recursive for hierarchy).\n\nExample: Floor 1 > Living Room > TV Nook" }, "ZoneResponse": { "allOf": [ { "$ref": "#/components/schemas/Zone" } ] } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer", "bearerFormat": "OpenApp API key", "description": "OpenApp API key issued via `POST /api-keys`. Send as `Authorization: Bearer {base_url}_openapp_{secret}`. The SDK auto-derives the base URL from the token." } } } }