{ "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": { "/access-invites/{id}/location-binding": { "get": { "tags": [ "Locations" ], "description": "Read the access invite's location binding and the effective location it resolves to. Requires `integrations:read` on the access invite's org.", "operationId": "get_access_invite_location_binding", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binding and resolved location", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedLocationResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] }, "put": { "tags": [ "Locations" ], "description": "Set the access invite's location binding: `inherit`, `none`, or `explicit` with a `location_id` in the access invite's org or an ancestor org. Requires `integrations:update` on the access invite's org.", "operationId": "put_access_invite_location_binding", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutLocationBindingRequest" } } }, "required": true }, "responses": { "200": { "description": "Binding and resolved location", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedLocationResponse" } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden, or the location is outside the org", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_AgentResponse" } } } } }, "security": [ { "api_key": [] } ] }, "post": { "tags": [ "Agents" ], "operationId": "create_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }, "required": true }, "responses": { "201": { "description": "Agent created", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/agents/{id}": { "get": { "tags": [ "Agents" ], "operationId": "get_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "Agents" ], "operationId": "revoke_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoked", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] }, "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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentCredentialResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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)", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "409": { "description": "Confirmation required or idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Provider min_interval_ms between opens has not elapsed", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "501": { "description": "Not implemented for provider", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/entities/{id}/actions/{action_id}/preview": { "post": { "tags": [ "Entities" ], "summary": "Preview an entity action: evaluates permissions and policies without calling the hardware.", "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.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites": { "get": { "tags": [ "Integrations" ], "summary": "List access invites for an integration.", "description": "Supports reconciliation by an external system of record: filtering by external source/record,\ncomputed state, granted portal, and validity window. An `external_source` +\n`external_record_id` pair is an indexed lookup, so an adapter that lost its local mapping can\nrecover a single invitation without scanning.", "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" ] } }, { "name": "external_source", "in": "query", "description": "External system slug to filter on (`external_ref.source`). Served by the external-reference\nindex, so an adapter can reconcile without keeping its own invite-id mapping.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "external_record_id", "in": "query", "description": "External record id to filter on. Requires `external_source`; the pair resolves to at most\none live invitation.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "state", "in": "query", "description": "Computed state: `active`, `scheduled`, `expired`, `disabled`, or `revoked`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "portal_id", "in": "query", "description": "Only invitations granting this portal ULID.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "valid_from_after", "in": "query", "description": "Only invitations whose window starts at or after this RFC 3339 instant.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "valid_to_before", "in": "query", "description": "Only invitations whose window ends at or before this RFC 3339 instant.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Paginated list of access invites", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_AccessInviteListItem" } } } }, "400": { "description": "Bad request (`invitation_validation_failed`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized (`invitation_unauthorized`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden (`invitation_forbidden`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Integration not found (`integration_not_found`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Server error (`invitation_internal_error`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] }, "post": { "tags": [ "Integrations" ], "summary": "Create an access invite granting portal_open on one or more portals.", "description": "Safe for at-least-once delivery from an external system of record:\n\n* `Idempotency-Key` makes a retried create replay the original result instead of creating a\n second invitation. The replayed body omits the one-time `invite_token` / `invite_url` and sets\n `idempotent_replay`.\n* `external_ref` binds the invitation to a record in the calling system. A second create for the\n same record is rejected with `external_reference_conflict`; use the reconcile route to make an\n existing invitation match a desired state.\n* `X-Correlation-Id` (or `X-Request-Id`) is stored with the invitation and on every audit event\n for the write, and echoed back on the response.", "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" } }, { "name": "Idempotency-Key", "in": "header", "description": "Replay key; a retry with the same key and body returns the original result without creating a second invitation.", "required": false, "schema": { "type": "string" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Caller request id recorded with the invitation and its audit events.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Created invite (or replay of an earlier create with the same Idempotency-Key)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessInviteResponse" } } } }, "400": { "description": "Validation or limit failure (`invitation_validation_failed`, `invitation_limit_exceeded`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized (`invitation_unauthorized`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden or policy denial (`invitation_forbidden`, `invitation_policy_denied`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Integration, portal, or location not found (`integration_not_found`, `invitation_portal_not_found`, `invitation_location_not_found`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Idempotency or external-reference conflict (`idempotency_key_conflict`, `idempotency_key_in_flight`, `external_reference_conflict`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Server error (`invitation_internal_error`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites/preview": { "post": { "tags": [ "Integrations" ], "summary": "Validate a desired invitation without creating physical access.", "description": "Runs exactly the validation, authorization, and policy evaluation that create runs, then stops\nbefore the write. Nothing is persisted: no invitation row, no token, no location binding, and no\nidempotency claim.", "operationId": "preview_integration_access_invite", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Caller request id used for tracing this preview.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "The plan create would produce", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAccessInviteResponse" } } } }, "400": { "description": "Validation or limit failure (`invitation_validation_failed`, `invitation_limit_exceeded`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized (`invitation_unauthorized`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden or policy denial (`invitation_forbidden`, `invitation_policy_denied`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Integration, portal, or location not found (`integration_not_found`, `invitation_portal_not_found`, `invitation_location_not_found`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Server error (`invitation_internal_error`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites/reconcile": { "post": { "tags": [ "Integrations" ], "summary": "Make the invitation state for an external record equal a desired state.", "description": "This is the operation a system of record needs: it addresses the invitation by\n`external_ref`, so the caller never has to discover or store OpenApp invitation ids, and there is\nno create-then-update race window. Behavior:\n\n* `state: active`, no invitation for the record — creates one and returns the one-time token.\n* `state: active`, invitation exists — updates it to the desired state (restoring it first when\n it was revoked, e.g. a reinstated reservation).\n* `state: revoked` — revokes the invitation, or reports `unchanged` when it is already revoked or\n was never created. The guest link stops working; history and the external reference survive.\n\nOut-of-order delivery is rejected: when `external_ref.revision` is older than the stored\nrevision the call fails with `external_revision_stale` and nothing is written. Duplicate\ndelivery is safe by construction, and `Idempotency-Key` additionally replays the original\nresponse.", "operationId": "reconcile_integration_access_invite", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Org", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Replay key; a retry with the same key and body returns the original result.", "required": false, "schema": { "type": "string" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Caller request id recorded with the invitation and its audit events.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileAccessInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Reconciled state", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileAccessInviteResponse" } } } }, "400": { "description": "Validation or limit failure (`invitation_validation_failed`, `invitation_limit_exceeded`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized (`invitation_unauthorized`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden or policy denial (`invitation_forbidden`, `invitation_policy_denied`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Integration, portal, or location not found (`integration_not_found`, `invitation_portal_not_found`, `invitation_location_not_found`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Idempotency conflict or stale external revision (`idempotency_key_conflict`, `idempotency_key_in_flight`, `external_revision_stale`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Server error (`invitation_internal_error`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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.", "description": "The update is a desired-state write and is therefore naturally idempotent: replaying the same\nbody leaves the same state. Out-of-order delivery is handled by `external_ref.revision` — a\nwrite whose revision is older than the stored one is refused with `external_revision_stale`\ninstead of restoring an earlier room, window, or portal set.", "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" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Caller request id recorded with the invitation and its audit events.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccessInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated invite", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInviteListItem" } } } }, "400": { "description": "Validation, limit, or revoked-invite failure (`invitation_validation_failed`, `invitation_limit_exceeded`, `invitation_revoked`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized (`invitation_unauthorized`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden or policy denial (`invitation_forbidden`, `invitation_policy_denied`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Integration, invitation, portal, or location not found (`integration_not_found`, `invitation_not_found`, `invitation_portal_not_found`, `invitation_location_not_found`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "External-reference conflict or stale revision (`external_reference_conflict`, `external_revision_stale`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Server error (`invitation_internal_error`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] }, "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" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Caller request id recorded on the audit event.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invite deleted", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "400": { "description": "Bad request, including `X-Org` sent more than once", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized (`invitation_unauthorized`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden (`invitation_forbidden`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found (`invitation_not_found`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/contacts/{contact_id}/notifications": { "get": { "tags": [ "Integrations" ], "operationId": "list_access_invite_contact_notifications", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Masked notification history", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNotificationsResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/contacts/{contact_id}/notify": { "post": { "tags": [ "Integrations" ], "operationId": "notify_access_invite_contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notification attempt", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifyContactsResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden or daily cap", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Cooldown; see Retry-After", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInviteMessageMediaResponse" } } } }, "400": { "description": "Bad request", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceImageUrlResponse" } } } }, "204": { "description": "No image for slot", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "400": { "description": "Bad request, including `X-Org` sent more than once", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/notify": { "post": { "tags": [ "Integrations" ], "operationId": "notify_access_invite_contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invite_link_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One result per contact", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifyContactsResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden or daily cap", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Cooldown; see Retry-After", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceImageUrlResponse" } } } }, "204": { "description": "No photo uploaded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "400": { "description": "Bad request, including `X-Org` sent more than once", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] }, "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", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceImageUrlResponse" } } } }, "400": { "description": "Bad request", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] }, "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", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "400": { "description": "Bad request, including `X-Org` sent more than once", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/regenerate-token": { "post": { "tags": [ "Integrations" ], "summary": "Regenerate invite token (returns new shareable link; old link stops working).", "description": "Rotation is the only way to recover a guest link after the one-time visibility on create: the\nprevious token is invalidated, so any link already delivered to a guest stops working.", "operationId": "regenerate_integration_access_invite_token", "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": "New invite token", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateAccessInviteTokenResponse" } } } }, "400": { "description": "Bad request (`invitation_validation_failed`, `invitation_revoked`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized (`invitation_unauthorized`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden (`invitation_forbidden`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found (`invitation_not_found`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccessInviteRenewalRequestsResponse" } } } }, "400": { "description": "Bad request", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } }, "400": { "description": "Bad request", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInviteListItem" } } } }, "400": { "description": "Bad request", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/revoke": { "post": { "tags": [ "Integrations" ], "summary": "Revoke an access invite.", "description": "Revocation is idempotent: revoking an already revoked invitation returns the same state with the\noriginal `revoked_at`, so a duplicate checkout webhook is safe. It is also reversible through the\nrestore route, which is what makes a reinstated reservation recoverable; the invitation row,\nits history, and its external reference are preserved (unlike delete).", "operationId": "revoke_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" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Caller request id recorded on the audit event.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked invite (idempotent)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInviteListItem" } } } }, "400": { "description": "Bad request (`invitation_validation_failed`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized (`invitation_unauthorized`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden (`invitation_forbidden`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found (`invitation_not_found`)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/integrations/{id}/access-invites/{invite_link_id}/usage": { "get": { "tags": [ "Integrations" ], "summary": "List recent uses of an access invitation.", "description": "Returns up to 200 uses from the last 30 days. Requires read access to the integration.", "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)", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessUsageResponse" } } } }, "400": { "description": "Bad request", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limited (`invitation_rate_limited`, a per-minute budget) or the customer's invitation API quota is exhausted (`quota_exceeded`); see `Retry-After`", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the exhausted budget resets." }, "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Requests allowed per minute in the tightest per-minute budget." }, "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Requests left in that budget for the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix seconds at which the current minute window resets." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/mcp": { "post": { "tags": [ "Agents" ], "operationId": "mcp_jsonrpc", "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "JSON-RPC response", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeAccessInvitesResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] }, "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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } } } }, "security": [ { "api_key": [] } ] } }, "/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": "source", "in": "query", "description": "Originating surface: `api`, `dashboard`, `public_access`, `smarthome`, `scripting`,\nor `system`.", "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": "door_name", "in": "query", "description": "Case-insensitive substring match on the snapshotted door name\n(`details.door_name`), e.g. `lobby`. Matches every event that names the door, so it\nanswers \"who opened this door\".", "required": false, "schema": { "type": "string" } }, { "name": "target_id", "in": "query", "description": "Exact match against the snapshotted portal target ID (`details.public_portal_id`).", "required": false, "schema": { "type": "string" } }, { "name": "zone_id", "in": "query", "description": "Zone ULID. Matches events whose zone snapshot (`details.zone_path`) contains the zone,\nso events in descendant zones are included. Only events recorded with a zone snapshot\nmatch. 400 when not a ULID.", "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": "org_scope", "in": "query", "description": "Organization scope for resource events. Descendants are included by default.", "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)", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventsPage" } } } }, "400": { "description": "Invalid filter (e.g. a non-ULID zone_id), or a range that exceeds the 30-day hot window (use exports)", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditExportJob" } } } } } }, "security": [ { "api_key": [] } ] }, "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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditExportJob" } } } }, "400": { "description": "Invalid range, format, or zone_id", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditExportJob" } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/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", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation id of this request: the caller's `X-Correlation-Id` when one was sent, otherwise a ULID minted for the request. Every response carries it, including errors." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResponse" } } } } }, "security": [ { "api_key": [] } ] } } }, "components": { "schemas": { "AccessInviteContactInput": { "type": "object", "description": "One contact named by an invitation.\n\nExactly one of `email`, `phone`, `user_id`, and `group_id` is set, and it must match\n`contact_kind`. Free-form contacts are normalized on write: a phone becomes E.164 using\n`phone_region` when it is not already international.", "required": [ "contact_kind" ], "properties": { "contact_kind": { "type": "string", "description": "`email`, `phone`, `user`, or `group`." }, "display_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "group_id": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "E.164, or national format when `phone_region` is supplied." }, "phone_region": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 region used to normalize a national-format phone." }, "user_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "AccessInviteContactNotification": { "type": "object", "description": "One notification attempt. `status` is `sent`, `failed`, or `bounced` — never `delivered`,\nbecause no provider delivery receipt is ingested for any channel.", "required": [ "id", "channel", "status", "created_at" ], "properties": { "channel": { "type": "string" }, "created_at": { "type": "string" }, "destination_hint": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "status": { "type": "string" } } }, "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" ] }, "external_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalReferenceResponse", "description": "External system-of-record correlation, when this invitation is driven by an adapter." } ] }, "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_thumb_url": { "type": [ "string", "null" ], "description": "Presigned URL for the `thumb` rendition of the invite photo, for avatar-sized renders.\nAbsent when the source is already thumb-sized; fall back to `photo_url`." }, "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." } } }, "AddBillingMemberRequest": { "type": "object", "required": [ "user_id" ], "properties": { "can_charge": { "type": [ "boolean", "null" ] }, "user_id": { "type": "string" } }, "additionalProperties": false }, "AddDirectoryListingMemberPayload": { "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 }, "AddGroupMemberPayload": { "type": "object", "required": [ "user_id" ], "properties": { "role": { "type": [ "string", "null" ] }, "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" } }, "AddSitePersonPayload": { "type": "object", "required": [ "user_id", "role" ], "properties": { "role": { "type": "string" }, "user_id": { "type": "string" } }, "additionalProperties": false }, "AdmissionDecisionPayload": { "type": "object", "required": [ "admitted" ], "properties": { "admitted": { "type": "boolean", "description": "true admits the member, false denies them. A denial is durable, so it does not resurface\nin the approval queue on every sync." } }, "additionalProperties": false }, "AdmissionResponse": { "type": "object", "description": "One row of the admission ledger, including members who were removed.", "required": [ "member_ref", "status", "admission_count" ], "properties": { "admission_count": { "type": "integer", "format": "int32" }, "admitted_at": { "type": [ "string", "null" ] }, "denied_at": { "type": [ "string", "null" ] }, "display_name": {}, "first_seen_at": { "type": [ "string", "null" ] }, "member_ref": { "type": "string" }, "removed_at": { "type": [ "string", "null" ] }, "status": { "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", "detached_zone_refs", "entities", "access_portals", "directory_listing_members", "invite_links", "invite_claims", "renewal_requests", "sessions", "unwired_door_refs" ], "properties": { "access_portals": { "type": "integer", "format": "int64" }, "detached_zone_refs": { "type": "integer", "format": "int64", "description": "Zone references the transfer clears: live devices with a zone plus live entities with an\nexplicit zone. Zones belong to the source organization and are not transferred: devices\nlose their zone and entities with an explicit zone become `inherit`." }, "devices": { "type": "integer", "format": "int64" }, "directory_listing_members": { "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" }, "unwired_door_refs": { "type": "integer", "format": "int64", "description": "Door references to hardware the transfer cannot keep: a door lists hardware of its own org\nonly, so MOVE unwires doors from hardware that stays behind (and doors left behind from\nmoved hardware), and DUPLICATE drops references to hardware that is not part of the clone." } } }, "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" } } }, "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." }, "current_phone": { "type": [ "string", "null" ], "description": "Present when `error_code` is `invite_phone_choice`: the number already on the signed-in account." }, "error_code": { "type": [ "string", "null" ], "description": "Optional stable code for clients to branch on (e.g. \"door_unreachable\")." }, "invited_phone": { "type": [ "string", "null" ], "description": "Present when `error_code` is `invite_phone_choice`: the number named by the invitation." }, "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 }, "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" }, "zone_id": { "type": [ "string", "null" ], "description": "Zone filter the job was created with." } } }, "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": "Billing event from a payment provider, after its webhook signature was validated. `raw`\nholds the provider's original payload.", "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" ] } } }, "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" ] } } }, "ContactNotificationsResponse": { "type": "object", "required": [ "notifications" ], "properties": { "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteContactNotification" } } } }, "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", "schedules" ], "properties": { "audience": { "$ref": "#/components/schemas/InviteAudience", "description": "Whether anyone holding the link may use the invitation, or only the named contacts." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteContactInput" }, "description": "Who the invitation is for. Each contact is either free-form (an email address or a phone\nnumber) or drawn from the organization (a person or a group). Rejected for shares, which\ncarry no invitee identity. Empty when the link is open to anyone." }, "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." }, "external_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalReferenceInput", "description": "Correlation to the record in the external system of record that owns this invitation\n(PMS reservation, work order, enrolment). One live invitation may own a given\n`(source, record_id)` pair per integration, which is what makes retries and duplicate\nwebhook deliveries safe. Omit for invitations authored inside OpenApp." } ] }, "has_photo": { "type": [ "boolean", "null" ], "description": "True when the client will upload a photo immediately after create (media is a follow-up POST)." }, "invitee_message": {}, "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", "items": { "$ref": "#/components/schemas/InviteScheduleEntryInput" }, "description": "One or more validity windows. A single non-recurring entry is the ordinary case; a share is\nexactly one entry with no explicit start (it opens at request time)." } }, "additionalProperties": false }, "CreateAccessInviteResponse": { "type": "object", "required": [ "invite_link_id", "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" }, "external_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalReferenceResponse", "description": "External system-of-record correlation stored with the invitation." } ] }, "granted_portals": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteGrantedPortal" } }, "idempotent_replay": { "type": "boolean", "description": "True when this body is a replay of an earlier create that carried the same\n`Idempotency-Key`. Nothing was created by this request and the one-time token fields are\nomitted." }, "invite_link_id": { "type": "string" }, "invite_recurrence": {}, "invite_token": { "type": [ "string", "null" ], "description": "Guest bearer token, returned **once** by the original create call.\n\nIt is stored only as a hash, never logged, and never cached for idempotent replay, so a\nreplayed create response omits it. Persist it at delivery time or rotate it through\n`POST /access-invites/{id}/regenerate-token`." }, "invite_url": { "type": [ "string", "null" ], "description": "Guest-facing invite URL (shareable link for SMS/email). Same one-time visibility as\n`invite_token`, and subject to the same logging restrictions." }, "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" ] }, "group_roles": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Group roles to add to the credential's default roles: any of `groups:create`,\n`groups:read`, `groups:update`, `groups:delete`, `groups:list`, `groups:share`,\n`groups:link`. Refused (403) unless the agent's organization has an enforcing\n`agent_group_write` policy and the caller holds each role there. The credential can use\nthem only in the agent's organization, and only while that policy stays enforced." }, "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." }, "zone_id": { "type": [ "string", "null" ], "description": "Zone ULID: export only events whose zone snapshot (`details.zone_path`) contains it\n(the zone and its descendants). 400 when not a ULID." } }, "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" }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the device is placed in (same org). Entities with `zone.mode = inherit` take it." } }, "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 stored as strings: non-string values are JSON-stringified.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "Optional friendly name for the entity." }, "zone": { "$ref": "#/components/schemas/ZonePlacement", "description": "Zone placement; defaults to `{\"mode\":\"inherit\"}` (follow the device zone)." } }, "additionalProperties": false }, "CreateGroupPayload": { "type": "object", "required": [ "name" ], "properties": { "description": {}, "kind": { "type": [ "string", "null" ] }, "name": {} }, "additionalProperties": false }, "CreateGroupShareOfferPayload": { "type": "object", "properties": { "expires_in_hours": { "type": [ "integer", "null" ], "format": "int64", "description": "Hours until the offer expires. Bounded so an offer cannot outlive the reason for it." } }, "additionalProperties": false }, "CreateHouseholdInvitation": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "invitee_name": { "type": [ "string", "null" ], "description": "Optional name for the person you invite. It greets them in the invitation and labels the\npending invitation for you. When they sign up without a name it becomes their account name,\nand they are asked to confirm it. Blank counts as no name; at most 100 characters." }, "locale": { "type": [ "string", "null" ], "description": "Language of the invitation SMS/email: a supported locale code. Used when the\ncontact has no account with a language of its own; resends reuse it. Omit to fall back to\nthe household's home org default message language, then English." }, "phone": { "type": [ "string", "null" ] }, "sms_consent_confirmed": { "type": "boolean", "description": "Must be `true` when `phone` is set: confirms the person you invite agreed to receive text\nmessages from OpenApp at that number. The confirmation is recorded with who gave it and\nwhen. Not needed for email-only invitations." } }, "additionalProperties": false }, "CreateHouseholdPayload": { "type": "object", "description": "Payload for creating a household.", "properties": { "name": { "type": [ "string", "null" ], "description": "Household name. Omit it to use the default derived from the caller." } }, "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_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Groups the person joins when they redeem, in the same transaction as the org role." }, "default_roles": { "type": "array", "items": { "type": "string" }, "description": "Roles to assign on accept (within the inviting org)." }, "email": { "type": [ "string", "null" ] }, "invitee_name": { "type": [ "string", "null" ], "description": "Name of the person being invited, up to 100 characters. Greets them in the invitation\nand labels the pending invitation for the inviter. At sign-up it becomes the account\nname only when no name is known, and the person confirms it. Omit when unknown." }, "locale": { "type": [ "string", "null" ], "description": "Language of the invitation SMS/email: a supported locale code. Used when the\ncontact has no account with a language of its own; resends reuse it. Omit to fall back to\nthe org's default message language, then English." }, "phone": { "type": [ "string", "null" ] }, "site_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvitationSiteAccessDto", "description": "Optional site (and listing) access applied atomically when the invitation is redeemed." } ] }, "sms_consent_confirmed": { "type": "boolean", "description": "Must be `true` when `phone` is set: confirms the person being invited agreed to receive\ntext messages from OpenApp at that number. The confirmation is recorded with who gave it\nand when. Not needed for email-only invitations." } }, "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" }, "geocoding_provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeocodingProviderId" } ] }, "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" } ] }, "provider_place_id": { "type": [ "string", "null" ], "description": "Opaque place id issued by `geocoding_provider`. Both fields must be sent together: a place id\ncannot be resolved without naming its issuer." } }, "additionalProperties": false }, "CreateOrganizationRequest": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "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", "signing_secret" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "signing_secret": { "type": "string", "description": "HMAC-SHA256 signing key, returned exactly once. The PMS signs each delivery with it (see\n`POST /pms/{connector_id}/inbound`); it is never returned again." }, "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) or `require_approval`. Each `policy_type` declares which modes it\naccepts (only `user_sharing` accepts `require_approval`); any other value is rejected\nwith 400." }, "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 }, "CreateScriptingExecutionRequest": { "type": "object", "required": [ "script" ], "properties": { "script": { "type": "string" } }, "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 accounts." }, "first_name": { "type": [ "string", "null" ], "description": "Given name stored on the Kratos identity (`traits.name.first`) when creating the account." }, "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" }, "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." } } } ] }, "CreateWifiNetworkRequest": { "type": "object", "required": [ "ssid", "security" ], "properties": { "credentials": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WifiCredentials", "description": "Required for `wpa_psk` (password) and `wpa_enterprise` (username and password); rejected\nfor `open`." } ] }, "hidden": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "format": "int32", "description": "Lower values are listed first in text messages. Defaults to 0." }, "security": { "$ref": "#/components/schemas/WifiSecurity" }, "ssid": { "type": "string" }, "zone_ids": { "type": "array", "items": { "type": "string" }, "description": "Zones the network covers. Each must be a live zone of the `X-Org` organization." } }, "additionalProperties": false }, "CreateZoneRequest": { "type": "object", "required": [ "name" ], "properties": { "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 over-capacity degradation snapshot for an org.", "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; its shape depends on the integration provider. Absent when\nthe device has none." }, "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." }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the device is placed in (same org). Entities with `zone.mode = inherit` take it." } } } ], "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", "credentials_set" ], "properties": { "credentials_set": { "type": "array", "items": { "type": "string" }, "description": "JSON Pointers into `data` of write-only credential fields that currently hold a value." }, "data": { "description": "Current `device_metadata` as a JSON object, without write-only credential fields." }, "provider_type": { "type": "string" }, "schema": { "description": "JSON Schema describing the device's `device_metadata` 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", "required": [ "credentials_set" ], "properties": { "credentials_set": { "type": "array", "items": { "type": "string" }, "description": "JSON Pointers into `device_metadata` of write-only credential fields (schema\n`format: password`) that currently hold a value. Credential values are never returned\nhere; an update that omits them keeps the stored value and `null` clears it." }, "is_primary_instance": { "type": [ "boolean", "null" ], "description": "Read-only, computed by the server: true when this device record is the primary instance\nfor its physical hardware, when the same hardware has more than one device record.\nNever accepted in a request body." }, "stale": { "type": [ "boolean", "null" ], "description": "Present when `include_stale=true` was requested and the provider supports stale detection." } } } ] }, "DeviceRuleResponse": { "type": "object", "description": "One device-tier policy as it applies to one device of the integration.", "required": [ "policy_id", "device_id", "device_name", "policy_type", "config" ], "properties": { "config": { "type": "object" }, "device_id": { "type": "string" }, "device_name": { "$ref": "#/components/schemas/LocalizedString" }, "output": { "type": [ "string", "null" ], "description": "Output the rule is scoped to, or null when it binds every output of the device." }, "policy_id": { "type": "string" }, "policy_type": { "type": "string" } } }, "DirectoryConfigResponse": { "type": "object", "required": [ "device_id", "state", "allowed_listing_kinds", "naming_patterns" ], "properties": { "allowed_listing_kinds": { "type": "array", "items": { "type": "string" } }, "device_id": { "type": "string" }, "disabled_message": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "naming_patterns": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "state": { "type": "string" } } }, "DirectoryFloorListResponse": { "type": "object", "description": "Distinct directory floors for a directory device.", "required": [ "floors" ], "properties": { "floors": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryFloorSummary" } } } }, "DirectoryFloorSummary": { "type": "object", "description": "One distinct floor among the listings of a directory device.", "required": [ "key", "floor" ], "properties": { "floor": {}, "floor_number": { "type": [ "integer", "null" ], "format": "int64" }, "key": { "type": "string" } } }, "DirectoryListingEnrichRequest": { "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." } } }, "DirectoryListingMemberResponse": { "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" } } }, "DirectoryListingMemberWithUserResponse": { "type": "object", "required": [ "member", "message_locale" ], "properties": { "age_class": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgeClass", "description": "Derived age class. Only set for listing managers." } ] }, "date_of_birth": { "type": [ "string", "null" ], "description": "Calendar date `YYYY-MM-DD`. Only set for listing managers." }, "member": { "$ref": "#/components/schemas/DirectoryListingMemberResponse" }, "message_locale": { "type": "string", "description": "Shipped locale code (`en`, `he`, `pt_br`) of the language messages to this person are\nwritten in: their own choice, the language last seen in their app, then the org default." }, "user_email": { "type": [ "string", "null" ], "description": "Mailbox the person can sign in with. Omitted when the account has only a placeholder email." }, "user_name": {}, "user_phone": { "type": [ "string", "null" ], "description": "Verified E.164 phone on the account, when one is set." } } }, "DirectoryOrderPayload": { "type": "object", "required": [ "listing_ids" ], "properties": { "listing_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "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": [ "listing_entity_ids" ], "properties": { "listing_entity_ids": { "type": "array", "items": { "type": "string" } } } }, "EffectiveLimit": { "type": "object", "description": "Resolved limit for a subject, quota key, and period, with the source that set it.", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/LimitSource", "description": "Where this value came from: an override, the org's tier, the system default, or the\nplatform exemption." }, "value": { "type": [ "integer", "null" ], "format": "int64", "description": "The effective cap, in the quota's unit. Null means unlimited.", "minimum": 0 } } }, "EffectivePoliciesResponse": { "type": "object", "required": [ "timezone", "curfew_windows", "user_sharing_mode", "device_rules", "zone_rules" ], "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 listing-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" } }, "device_rules": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceRuleResponse" }, "description": "Device-tier rules on the integration's hardware. They bind only actions that fire that\ndevice (and output, when set), so they are not reflected in the integration-wide values\nabove. Empty on the org preview without `integration_id`." }, "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_listing_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`." }, "zone_rules": { "type": "array", "items": { "$ref": "#/components/schemas/ZoneRuleResponse" }, "description": "Organization and integration rules scoped to a zone (`config.zone_id`). They bind only\ndoors whose effective zone is that zone or below it, so they are not reflected in the\nintegration-wide values above." } } }, "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": "Entity-specific metadata (for example integration-specific fields), as string values.\nAbsent when the entity has none." } ] }, "name": { "type": [ "string", "null" ], "description": "Optional friendly name for the entity." }, "zone": { "$ref": "#/components/schemas/ZonePlacement", "description": "Zone placement: inherit the device's zone, name one explicitly, or none." } } } ], "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 the entity's `entity_metadata` for this provider and entity type." } } }, "EntityResponse": { "allOf": [ { "$ref": "#/components/schemas/Entity" }, { "type": "object", "properties": { "effective_zone_id": { "type": [ "string", "null" ], "description": "Derived, read-only: the zone the entity is effectively in (`zone` resolved against the\ndevice zone), or null." }, "entity_metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HashMap", "description": "Persisted, entity-specific metadata (integration-specific fields)." } ] }, "entry_kind": { "type": [ "string", "null" ], "description": "Derived, read-only entry kind for switchable entries on Virtual Access devices.\nOmitted when the entity is not an entry or the device has no Virtual Access config." }, "state": { "description": "Derived, read-only. When local provider config cannot run switchable\nopen/close/toggle, `{ \"status\": \"invalid\", \"reason\": \"\" }`." }, "zone_door_id": { "type": [ "string", "null" ], "description": "Derived, read-only: the door that lists this entity and owns its zone. Present exactly\nwhen `zone_source` is `door`, and also when that door has no zone." }, "zone_source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ZoneSource", "description": "Derived, read-only: `entity` when the zone is explicit, `device` when inherited, `door`\nwhen a door that lists this entity owns the zone, null when there is no effective zone." } ] } } } ] }, "EntityType": { "type": "string", "description": "Entity type (directory_listing, switch, light, sensor...).", "enum": [ "directory_listing", "door", "light", "sensor", "switch" ] }, "ExecutionStatus": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "canceled" ] }, "ExternalReferenceInput": { "type": "object", "description": "Correlation to a record in an external system of record.\n\nThe pair (`source`, `record_id`) is the addressable key: one live invitation per pair per\nintegration. `revision` is the source's own monotonic version of the record and is the\nprecondition that keeps a late event from overwriting a newer one.", "required": [ "source", "record_id" ], "properties": { "record_id": { "type": "string", "description": "Identifier of the record inside that system (reservation, work order, enrolment). Opaque to\nOpenApp; up to 128 characters." }, "revision": { "type": [ "integer", "null" ], "format": "int64", "description": "Monotonic revision of the external record. When present, OpenApp rejects any later write\ncarrying a lower revision with `external_revision_stale`." }, "source": { "type": "string", "description": "Slug naming the external system, e.g. `mews`, `opera`, `custom-pms`. Lowercase letters,\ndigits, `.`, `_`, and `-`; up to 64 characters." } }, "additionalProperties": false }, "ExternalReferenceResponse": { "type": "object", "description": "External correlation as returned by the invitation API.", "required": [ "source", "record_id" ], "properties": { "correlation_id": { "type": [ "string", "null" ], "description": "Correlation id of the request that last wrote this reference." }, "record_id": { "type": "string" }, "revision": { "type": [ "integer", "null" ], "format": "int64" }, "source": { "type": "string" } } }, "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" } } }, "GenerateListingsPayload": { "type": "object", "required": [ "source_group_ids", "listing_kind" ], "properties": { "listing_kind": { "type": "string", "description": "The kind written onto every listing this request generates." }, "naming_pattern": { "type": [ "string", "null" ] }, "source_group_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "GeneratePlanEntry": { "type": "object", "required": [ "group_id" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "group_id": { "type": "string" }, "listing_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] } } }, "GeneratePlanResponse": { "type": "object", "required": [ "create", "update", "unchanged", "skipped", "orphaned" ], "properties": { "create": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratePlanEntry" } }, "orphaned": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratePlanEntry" } }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratePlanEntry" } }, "unchanged": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratePlanEntry" } }, "update": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratePlanEntry" } } } }, "GeocodingProviderId": { "type": "string", "description": "Issuer of a place id. Place ids are opaque to OpenApp and are only interpretable by the provider\nthat minted them, so every stored or transported place id names its issuer.", "enum": [ "google", "mapbox" ] }, "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)." }, "GroupLinkResponse": { "type": "object", "description": "A group's link into an org.", "required": [ "group_id", "org_id", "status", "admission_mode", "is_home" ], "properties": { "admission_mode": { "type": "string" }, "group_id": { "type": "string" }, "is_home": { "type": "boolean" }, "org_id": { "type": "string" }, "status": { "type": "string" } } }, "GroupMemberResponse": { "type": "object", "description": "A member as a requesting org may see them.\n\nContact details are absent by design: a referencing org may see who can enter its building but\nnot how to reach them.", "required": [ "member_ref", "role" ], "properties": { "display_name": {}, "member_ref": { "type": "string" }, "role": { "type": "string" } } }, "GroupProposalResponse": { "type": "object", "description": "One household's proposal state at one org.", "required": [ "group_id", "org_id", "status", "pending_members" ], "properties": { "group_id": { "type": "string" }, "org_id": { "type": "string" }, "pending_members": { "type": "integer", "description": "Members waiting for this org to admit them.", "minimum": 0 }, "status": { "type": "string", "description": "pending, active, or revoked." } } }, "GroupResponse": { "type": "object", "description": "A group as returned by the API.", "required": [ "id", "home_org_id", "name", "kind", "shareable" ], "properties": { "description": {}, "home_org_id": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": {}, "shareable": { "type": "boolean" } } }, "GroupShareOfferResponse": { "type": "object", "required": [ "offer_id", "group_id", "expires_at" ], "properties": { "expires_at": { "type": "string" }, "group_id": { "type": "string" }, "offer_id": { "type": "string" }, "token": { "type": [ "string", "null" ], "description": "The one-time token. Returned only by create; redemption never echoes it back." } } }, "GroupSiteRef": { "type": "object", "description": "A site a household grants access to.", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "description": "Localized site name." } } }, "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": { "dates": { "type": "array", "items": { "type": "string" }, "description": "Organization-local ISO dates in `YYYY-MM-DD` format." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "HouseholdAdmissionStatus": { "type": "object", "required": [ "org_name", "status" ], "properties": { "member_name": {}, "member_ref": { "type": [ "string", "null" ] }, "org_name": {}, "status": { "type": "string" } } }, "HouseholdInvitationPreview": { "type": "object", "required": [ "household_name", "channel", "target_masked", "expires_at" ], "properties": { "channel": { "type": "string" }, "expires_at": { "type": "string" }, "household_name": {}, "invited_by_name": {}, "target_masked": { "type": "string" } } }, "HouseholdInvitationResponse": { "type": "object", "required": [ "id", "group_id", "invited_by_user_id", "channel", "status", "created_at", "expires_at", "sent_count" ], "properties": { "channel": { "type": "string" }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "group_id": { "type": "string" }, "id": { "type": "string" }, "invited_by_user_id": { "type": "string" }, "invitee_name": { "type": [ "string", "null" ], "description": "Name you gave for the invitee. Omitted when none was given, and once the invitation is\naccepted or cancelled." }, "last_sent_at": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ], "description": "Message language the sender chose, or `null` when none was chosen." }, "phone_transport": { "type": [ "string", "null" ] }, "recipient_email": { "type": [ "string", "null" ] }, "recipient_phone": { "type": [ "string", "null" ] }, "responded_at": { "type": [ "string", "null" ] }, "sent_count": { "type": "integer", "format": "int32" }, "status": { "type": "string" } } }, "HouseholdManagerTransferView": { "type": "object", "required": [ "nominee_user_id", "expires_at", "declined" ], "properties": { "declined": { "type": "boolean" }, "expires_at": { "type": "string" }, "nominee_user_id": { "type": "string" } } }, "HouseholdMemberResponse": { "type": "object", "description": "A household member as a fellow member may see them.", "required": [ "user_id", "role", "manager_eligible" ], "properties": { "manager_eligible": { "type": "boolean", "description": "Missing age data is treated as adult; only an explicit under-16 classification is ineligible." }, "role": { "type": "string" }, "user_id": { "type": "string" }, "user_name": { "description": "Localized display name, so the roster never renders the transport id." } } }, "IdpLinkResponse": { "type": "object", "required": [ "provider", "is_primary" ], "properties": { "is_primary": { "type": "boolean" }, "provider": { "type": "string" } } }, "ImageUploadForm": { "type": "object", "description": "Multipart form body for image uploads.", "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 device `device_metadata` under an integration's provider (no device instance\nrequired).", "required": [ "provider_type", "schema" ], "properties": { "provider_type": { "type": "string" }, "schema": { "description": "JSON Schema describing device `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", "credentials_set" ], "properties": { "credentials_set": { "type": "array", "items": { "type": "string" }, "description": "JSON Pointers into `config` of write-only credential fields (schema `format: password`)\nthat currently hold a value. Credential values are never returned here; an update that\nomits them keeps the stored value and `null` clears it." }, "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 of the matching pending org invitation." }, "phone": { "type": [ "string", "null" ] }, "phone_transport": { "type": [ "string", "null" ], "description": "`sms` or `whatsapp` when `status == invited` and a phone PIN was sent." }, "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": { "blackout_dates": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Organization-local ISO dates that invitations cannot use." }, "holiday_calendar": { "type": [ "boolean", "null" ], "description": "Also block the dates from applicable `holiday_calendar` policies." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "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." }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "InvitationAllowedEntryKindsPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_allowed_entry_kinds`.", "required": [ "kinds" ], "properties": { "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationEntryKind" } }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "InvitationAuthoringPolicyConfig": { "type": "object", "description": "Typed `config` shape for invitation authoring policies without type-specific keys.", "properties": { "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "InvitationCountLimitPolicyConfig": { "type": "object", "description": "Typed `config` shape for `max_doors_per_invite` and `invitation_max_contacts`.", "required": [ "max" ], "properties": { "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "max": { "type": "integer", "format": "int64", "minimum": 1 }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "InvitationEntryKind": { "type": "string", "enum": [ "door", "gate", "boom-gate" ] }, "InvitationIdentityPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_require_identity`. Checked when the invitee redeems,\nwhere the author is not the actor, so it takes no `applies_to`.", "properties": { "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "require_photo": { "type": [ "boolean", "null" ] }, "require_pin": { "type": [ "boolean", "null" ] }, "require_verified_phone": { "type": [ "boolean", "null" ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "InvitationListingGrant": { "type": "object", "required": [ "entity_id", "role" ], "properties": { "entity_id": { "type": "string" }, "role": { "type": "string" } } }, "InvitationMaxActivePerUserPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_max_active_per_user`. Also enforced when an invitation\nis re-enabled, where no author context exists, so it takes no selectors.", "required": [ "max" ], "properties": { "max": { "type": "integer", "format": "int64", "minimum": 1 } } }, "InvitationMaxDurationPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_max_duration` and `share_max_duration`.", "required": [ "max_seconds" ], "properties": { "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "max_seconds": { "type": "integer", "format": "int64", "minimum": 1 }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "InvitationMaxUsesPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invitation_max_uses` and `share_default_max_uses`.", "required": [ "max_uses" ], "properties": { "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "max_uses": { "type": "integer", "format": "int64", "minimum": 1 }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "InvitationPreviewListing": { "type": "object", "description": "Listing (for example an apartment) an invitation grants membership in.", "required": [ "role" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the listing. Absent when it has none or no longer exists." }, "role": { "type": "string", "description": "`admin` or `member`." } } }, "InvitationPreviewRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } }, "additionalProperties": false }, "InvitationPreviewResponse": { "type": "object", "required": [ "org_id", "channel", "status", "target_masked", "expires_at", "default_roles" ], "properties": { "channel": { "type": "string" }, "default_roles": { "type": "array", "items": { "type": "string" }, "description": "Org roles granted on accept. Reflects the invitation as it is now, not as it was when a\nmessage was sent." }, "expires_at": { "type": "string" }, "invited_by_name": { "description": "Name of the person who sent the invitation, as a `LocalizedString`. Absent when that\naccount no longer exists." }, "org_id": { "type": "string" }, "org_name": { "description": "Name of the organization the invitation is into, as a `LocalizedString`." }, "site_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvitationPreviewSiteAccess", "description": "Site (and listing) access granted on accept; absent when the invitation grants none." } ] }, "status": { "type": "string" }, "target_masked": { "type": "string", "description": "Masked destination the code is sent to (for example `+9725…78`)." } } }, "InvitationPreviewSiteAccess": { "type": "object", "description": "Site access an invitation grants, with the names a person needs to recognize it.", "required": [ "role" ], "properties": { "listing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvitationPreviewListing" } ] }, "role": { "type": "string", "description": "`admin`, `resident`, or `technician`." }, "site_name": { "description": "Name of the site, as a `LocalizedString`. Absent when the site no longer exists." } } }, "InvitationSiteAccessDto": { "type": "object", "required": [ "integration_id", "role" ], "properties": { "integration_id": { "type": "string" }, "listing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvitationListingGrant" } ] }, "role": { "type": "string" } } }, "InvitationTokenRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } }, "additionalProperties": false }, "InviteAudience": { "type": "string", "description": "Who an invitation may be used by.\n\n`anyone_with_link`: whoever holds the link may use it. `listed_contacts`: the bearer must\nresolve to one of the invitation's named contacts, so a forwarded link cannot be used by\nsomeone else.", "enum": [ "anyone_with_link", "listed_contacts" ] }, "InviteCreatorRolesPolicyConfig": { "type": "object", "description": "Typed `config` shape for `invite_creator_roles`.", "required": [ "allowed_roles" ], "properties": { "allowed_roles": { "type": "array", "items": { "type": "string" } }, "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "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 per-subject quota override; carries the override id.", "required": [ "id", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "override" ] } } }, { "type": "object", "description": "The org's billing tier; carries the tier slug.", "required": [ "slug", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "tier" ] }, "slug": { "type": "string" } } }, { "type": "object", "description": "The system default, used when no tier is configured for the org (for example a new\npersonal workspace).", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "default" ] } } }, { "type": "object", "description": "A platform-owned organization (the root, or the container for personal workspaces).\nThese are not customers, so every quota is unlimited.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "platform" ] } } } ] }, "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`." }, "door_name": { "type": [ "string", "null" ], "description": "Case-insensitive substring match on the snapshotted door name\n(`details.door_name`), e.g. `lobby`. Matches every event that names the door, so it\nanswers \"who opened this door\"." }, "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)." }, "org_scope": { "type": [ "string", "null" ], "description": "Organization scope for resource events. Descendants are included by default." }, "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" ] }, "source": { "type": [ "string", "null" ], "description": "Originating surface: `api`, `dashboard`, `public_access`, `smarthome`, `scripting`,\nor `system`." }, "target_id": { "type": [ "string", "null" ], "description": "Exact match against the snapshotted portal target ID (`details.public_portal_id`)." }, "zone_id": { "type": [ "string", "null" ], "description": "Zone ULID. Matches events whose zone snapshot (`details.zone_path`) contains the zone,\nso events in descendant zones are included. Only events recorded with a zone snapshot\nmatch. 400 when not a ULID." } } }, "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." }, "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." }, "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 the device name in any locale. Best-effort when\n`integration_id` is set." }, "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." }, "zone_id": { "type": [ "string", "null" ], "description": "Optional filter: only devices placed directly in this zone. A malformed id is 400.\nCombines with `q`; cannot be combined with `integration_id`." } } } ] }, "ListEntitiesQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" }, { "type": "object", "properties": { "include_descendants": { "type": "boolean", "description": "With `zone_id`: also match entities whose effective zone is a descendant zone." }, "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`.\nCombines with `zone_id` and `q`. Defaults to insertion order when omitted." }, "zone_id": { "type": [ "string", "null" ], "description": "Optional filter: only entities whose **effective** zone is this zone. A malformed id is 400." } } } ], "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": { "q": { "type": [ "string", "null" ], "description": "Case-insensitive substring of name or email." }, "recursive": { "type": [ "boolean", "null" ] }, "role": { "type": [ "string", "null" ], "description": "Membership role that must be held in the listed org subtree." } } } ] }, "ListOrgsQuery": { "allOf": [ { "$ref": "#/components/schemas/MultiResourceOutputOptionsQuery" }, { "$ref": "#/components/schemas/PaginationQuery" } ] }, "ListScriptingExecutionsQuery": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum number of executions to return (1-100, default 20)." } } }, "LocaleContentTranslation": { "type": "object", "required": [ "title", "body" ], "properties": { "body": { "type": "string" }, "title": { "type": "string" } } }, "LocalizedString": { "type": "object", "description": "Localized text: a JSON object mapping locale codes (for example `en`, `he`, `pt-BR`) to the\ntext in that language.", "required": [ "value" ], "properties": { "value": { "type": "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" } ] }, "geocoding_provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeocodingProviderId" } ] }, "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" } ] }, "provider_place_id": { "type": [ "string", "null" ], "description": "Opaque place id issued by `geocoding_provider`. Both fields are present together or not at\nall: a place id cannot be interpreted without knowing who issued it." }, "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" } } }, "ManagerTransferPayload": { "type": "object", "required": [ "nominee_user_id" ], "properties": { "nominee_user_id": { "type": "string" } }, "additionalProperties": false }, "MeAccessInvitesResponse": { "type": "object", "required": [ "invites" ], "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteListItem" } } } }, "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", "grants", "uses", "can_read" ], "properties": { "access_control": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicPortalAccessControl", "description": "Integration / building summary with photo (best-effort)." } ] }, "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." }, "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_thumb_url": { "type": [ "string", "null" ], "description": "Presigned URL for the `thumb` rendition of the org logo, for small renders.\nAbsent when the source is already thumb-sized; fall back to `org_image_url`." }, "org_image_url": { "type": [ "string", "null" ], "description": "Presigned org logo URL (best-effort)." }, "photo_thumb_url": { "type": [ "string", "null" ], "description": "Presigned URL for the `thumb` rendition of the invite photo, for small renders.\nAbsent when the source is already thumb-sized; fall back to `photo_url`." }, "photo_url": { "type": [ "string", "null" ], "description": "Presigned URL for the invite's main photo (best-effort)." }, "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" } } } }, "MeListingAsset": { "type": "object", "required": [ "entity_id", "integration_id", "org_id", "role", "receives_calls", "call_eligible" ], "properties": { "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 listing (global DND or per-listing DND)." }, "entity_id": { "type": "string" }, "floor": {}, "floor_number": { "type": [ "integer", "null" ], "format": "int64" }, "image_thumb_url": { "type": [ "string", "null" ], "description": "Presigned URL for the `thumb` rendition of the listing photo, for small renders.\nAbsent when the source is already thumb-sized; fall back to `image_url`." }, "image_url": { "type": [ "string", "null" ], "description": "Presigned listing (entity) photo URL (best-effort)." }, "integration_id": { "type": "string" }, "listing_label": {}, "listing_number": { "type": [ "integer", "null" ], "format": "int64" }, "org_id": { "type": "string" }, "org_name": { "description": "Organization display name (best-effort)." }, "receives_calls": { "type": "boolean" }, "role": { "type": "string" } } }, "MeListingsResponse": { "type": "object", "required": [ "listings", "age_class" ], "properties": { "age_class": { "$ref": "#/components/schemas/AgeClass", "description": "Derived from parent-declared date of birth. `adult` when unset." }, "dnd_global": { "type": [ "boolean", "null" ], "description": "True when user has global DND enabled (all calls silenced)." }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/MeListingAsset" } } } }, "MeProfileResponse": { "type": "object", "required": [ "email_verified", "phone_verified", "idp_links", "profile_sources", "name_confirmation_pending" ], "properties": { "email": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" }, "idp_links": { "type": "array", "items": { "$ref": "#/components/schemas/IdpLinkResponse" } }, "image_sync_error": { "type": [ "string", "null" ] }, "image_thumb_url": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ], "description": "Explicit preferred locale: a supported locale code, or `null` to use the app\nlanguage. Messages use it ahead of `observed_locale`." }, "name": { "type": [ "string", "null" ] }, "name_confirmation_pending": { "type": "boolean", "description": "True while the account still owes a name confirmation after accepting an invitation: the\nname is the inviter's spelling, or there is none. Clears once a name is saved through\n`PATCH /me/profile`, or when an identity provider supplies the name." }, "observed_locale": { "type": [ "string", "null" ], "description": "Last app/device language reported through `PUT /me/locale/observed`. Read-only here." }, "phone": { "type": [ "string", "null" ] }, "phone_verified": { "type": "boolean" }, "profile_sources": { "$ref": "#/components/schemas/ProfileSourcesResponse" } } }, "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" } } }, "MergeZonesRequest": { "type": "object", "required": [ "source_zone_ids" ], "properties": { "source_zone_ids": { "type": "array", "items": { "type": "string" }, "description": "Zones merged into the target (path) zone; each is soft-deleted afterwards." } }, "additionalProperties": false }, "MergeZonesResponse": { "type": "object", "required": [ "zone", "moved_child_zones", "moved_devices", "moved_entities", "moved_provider_links" ], "properties": { "moved_child_zones": { "type": "integer", "format": "int64", "minimum": 0 }, "moved_devices": { "type": "integer", "format": "int64", "minimum": 0 }, "moved_entities": { "type": "integer", "format": "int64", "minimum": 0 }, "moved_provider_links": { "type": "integer", "format": "int64", "minimum": 0 }, "zone": { "$ref": "#/components/schemas/ZoneResponse" } } }, "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": "When true, return only soft-deleted items. Implies `include_deleted=true`." }, "single": { "$ref": "#/components/schemas/SingleResourceOutputOptions", "description": "Single-resource options (`include_deleted`)." } } }, "MultiResourceOutputOptionsQuery": { "type": "object", "properties": { "include_deleted": { "type": "boolean" }, "only_deleted": { "type": "boolean" } } }, "MyGroupResponse": { "allOf": [ { "$ref": "#/components/schemas/GroupResponse" }, { "type": "object", "required": [ "my_role", "sites" ], "properties": { "manager_transfer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HouseholdManagerTransferView", "description": "A managerless, read-only period while a nominated successor decides whether to take over." } ] }, "my_role": { "type": "string", "description": "The caller's role within the group." }, "sites": { "type": "array", "items": { "$ref": "#/components/schemas/GroupSiteRef" }, "description": "Sites where this group is linked and the caller is admitted." } } } ], "description": "A group the caller belongs to, with the sites it grants access to." }, "NotificationChannel": { "type": "string", "enum": [ "audit" ] }, "NotificationPolicyConfig": { "type": "object", "description": "Shared typed `config` shape for notification policies.", "required": [ "channels" ], "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannel" }, "description": "Notification destinations. Only `audit` is currently supported." } } }, "NotificationPreferences": { "type": "object", "required": [ "whatsapp", "sms", "push" ], "properties": { "push": { "type": "boolean", "description": "Send notices as push notifications to the user's registered browsers and devices." }, "sms": { "type": "boolean", "description": "Send notices to the phone on file as text messages when WhatsApp did not deliver them." }, "whatsapp": { "type": "boolean", "description": "Send notices to the phone on file over WhatsApp." } }, "additionalProperties": false }, "NotifyContactResult": { "type": "object", "required": [ "contact_id", "status" ], "properties": { "contact_id": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`sent` or `failed`." } } }, "NotifyContactsResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NotifyContactResult" } } } }, "NotifyPortalMessageBody": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } }, "additionalProperties": false }, "OrgDefaultLocaleResponse": { "type": "object", "properties": { "default_locale": { "type": [ "string", "null" ], "description": "Supported locale code, or `null` when unset (messages then use English unless the\nrecipient has a locale of their own)." } } }, "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.\n`system:*` keys are reported only for the root organization, where they are enforced.", "required": [ "permissions" ], "properties": { "permissions": { "type": "array", "items": { "type": "string" } } } }, "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\nPresent only in responses from the org children and search endpoints; omitted elsewhere.\nLets a client show whether a node can be expanded without fetching its 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" ] }, "external_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalReferenceResponse", "description": "External system-of-record correlation, when this invitation is driven by an adapter." } ] }, "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_thumb_url": { "type": [ "string", "null" ], "description": "Presigned URL for the `thumb` rendition of the invite photo, for avatar-sized renders.\nAbsent when the source is already thumb-sized; fall back to `photo_url`." }, "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": { "effective_zone_id": { "type": [ "string", "null" ], "description": "Derived, read-only: the zone the entity is effectively in (`zone` resolved against the\ndevice zone), or null." }, "entity_metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HashMap", "description": "Persisted, entity-specific metadata (integration-specific fields)." } ] }, "entry_kind": { "type": [ "string", "null" ], "description": "Derived, read-only entry kind for switchable entries on Virtual Access devices.\nOmitted when the entity is not an entry or the device has no Virtual Access config." }, "state": { "description": "Derived, read-only. When local provider config cannot run switchable\nopen/close/toggle, `{ \"status\": \"invalid\", \"reason\": \"\" }`." }, "zone_door_id": { "type": [ "string", "null" ], "description": "Derived, read-only: the door that lists this entity and owns its zone. Present exactly\nwhen `zone_source` is `door`, and also when that door has no zone." }, "zone_source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ZoneSource", "description": "Derived, read-only: `entity` when the zone is explicit, `device` when inherited, `door`\nwhen a door that lists this entity owns the zone, null when there is no effective zone." } ] } } } ] } }, "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 membership visible in\nhistory but blocks purchasing.", "required": [ "id", "store_id", "user_id", "role", "status" ], "properties": { "billing_account_id": { "type": [ "string", "null" ], "description": "Account purchases are charged to. When null, purchases are charged to the member's\npersonal 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. A soft-deleted product stays readable until `purge_at`.", "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_WifiNetworkResponse": { "type": "object", "description": "Paginated response body for list endpoints.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/WifiNetwork" }, { "type": "object", "required": [ "zone_ids", "has_credentials" ], "properties": { "has_credentials": { "type": "boolean", "description": "False for `open` networks." }, "zone_ids": { "type": "array", "items": { "type": "string" }, "description": "Zones this network covers. Invitations to doors in these zones offer the network." } } } ], "description": "A Wi-Fi network as returned by the API. Credentials are never included; use the\ncredentials endpoint." } }, "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" }, { "type": "object", "required": [ "provider_links" ], "properties": { "provider_links": { "type": "array", "items": { "$ref": "#/components/schemas/ZoneProviderLinkResponse" } } } } ] } }, "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" }, "geocoding_provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeocodingProviderId" } ] }, "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: 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" } ] }, "provider_place_id": { "type": [ "string", "null" ], "description": "Opaque place id issued by `geocoding_provider`; replaces the stored place reference. Both\nfields must be sent together: a place id cannot be resolved without naming its issuer." } }, "additionalProperties": false }, "PatchMeDndPayload": { "type": "object", "properties": { "dnd_global": { "type": [ "boolean", "null" ] } } }, "PatchMeListingDndPayload": { "type": "object", "properties": { "availability_hours": {}, "dnd_enabled": { "type": [ "boolean", "null" ] }, "quiet_hours": {} } }, "PatchMeProfileRequest": { "type": "object", "properties": { "locale": { "type": [ "string", "null" ], "description": "A supported locale code (`en`, `zh_cn`, `es`, `ru`, `pt_br`, `de`, `fr`, `ja`,\n`ar`, `it`, `he`); any other value is rejected with 422. JSON `null` clears the explicit\nchoice so messages follow the app language; omitting it leaves the locale unchanged." }, "name": { "type": [ "string", "null" ] }, "profile_sources": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProfileSourcePatch" } ] } }, "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" } } }, "PendingInvitationDto": { "allOf": [ { "$ref": "#/components/schemas/InvitationPreviewResponse" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Pass to `POST /me/org-invitations/{id}/accept`." } } } ], "description": "An invitation addressed to a phone or email the signed-in account has verified." }, "PendingInvitationListResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PendingInvitationDto" } } } }, "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" } } } }, "PmsConnectorResponse": { "type": "object", "required": [ "id", "name", "provider", "webhook_url_path" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "webhook_url_path": { "type": "string" } } }, "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" ] }, "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" ] }, "PreviewAccessInviteResponse": { "type": "object", "description": "Effective plan for a create request, produced without persisting anything.\n\nOnboarding an external adapter is the main use: it can check that a desired reservation maps to\nportals it is allowed to grant, that the schedule resolves as expected, and which identity\nfields organization policy will demand — before any physical access exists.", "required": [ "valid", "valid_from", "valid_to", "schedule_kind", "schedule_combined", "schedule_entries", "schedule", "granted_portals", "unlinked_portal_ids", "required_identity_fields", "requires_justification", "pending_approval", "is_enabled", "kind" ], "properties": { "curfew_exempt": { "type": "boolean" }, "curfew_windows": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CurfewWindowResponse" } }, "external_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalReferenceResponse" } ] }, "granted_portals": { "type": "array", "items": { "$ref": "#/components/schemas/AccessInviteGrantedPortal" } }, "is_enabled": { "type": "boolean" }, "kind": { "$ref": "#/components/schemas/AccessInviteKind" }, "max_devices": { "type": [ "integer", "null" ], "format": "int32" }, "max_uses": { "type": [ "integer", "null" ], "format": "int32" }, "pending_approval": { "type": "boolean", "description": "True when creating this invitation would land disabled awaiting admin approval." }, "required_identity_fields": { "type": "array", "items": { "type": "string" }, "description": "Identity fields organization policy requires for this invitation: `pin`, `invitee_phone`,\nand/or `photo`." }, "requires_justification": { "type": "boolean", "description": "Whether policy requires `creation_justification`." }, "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." }, "unlinked_portal_ids": { "type": "array", "items": { "type": "string" }, "description": "Portals that would be granted but do not currently resolve to a live door device, so the\nguest link would not open them." }, "valid": { "type": "boolean", "description": "Always true on a 200. A request that would be rejected returns the same status, error code,\nand message that create would return." }, "valid_from": { "type": "string" }, "valid_to": { "type": "string" } } }, "PrivacyExportResponse": { "type": "object", "required": [ "exported_at", "account", "memberships", "listings", "invitations", "device_tokens", "dnd", "eula" ], "properties": { "account": {}, "device_tokens": { "type": "array", "items": {} }, "dnd": {}, "eula": {}, "exported_at": { "type": "string" }, "invitations": { "type": "array", "items": {} }, "listings": { "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 }, "ProfileSourcePatch": { "type": "object", "properties": { "email": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProfileSourceRequest" } ] }, "image": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProfileSourceRequest" } ] }, "locale": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProfileSourceRequest" } ] }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProfileSourceRequest" } ] }, "phone": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProfileSourceRequest" } ] } }, "additionalProperties": false }, "ProfileSourceRequest": { "type": "string", "enum": [ "idp", "openapp" ] }, "ProfileSourcesResponse": { "type": "object", "required": [ "name", "image", "email", "phone", "locale" ], "properties": { "email": { "type": "string" }, "image": { "type": "string" }, "locale": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "ProhibitMasterDoorInvitesPolicyConfig": { "type": "object", "description": "Typed `config` shape for `prohibit_master_door_invites`.", "required": [ "master_door_ids" ], "properties": { "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "master_door_ids": { "type": "array", "items": { "type": "string" } }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyOutputSelector", "description": "Provider-derived output/channel selector: the row binds only actions on that output." } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Zone the row is scoped to (org and integration rows only): it binds only when the acting\neffective zone is this zone or a descendant. Must be a live zone of the policy's org." } } }, "ProposeGroupPayload": { "type": "object", "required": [ "integration_id", "disclosure_acknowledged" ], "properties": { "disclosure_acknowledged": { "type": "boolean" }, "integration_id": { "type": "string", "description": "The site (integration) to propose the household to." } }, "additionalProperties": false }, "ProviderType": { "type": "string", "description": "Integration provider type (e.g. homeassistant, knx, mqtt).", "enum": [ "go2rtc", "homeassistant", "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" }, "uses_remaining": { "type": [ "integer", "null" ], "format": "int32", "description": "Uses left after this execution; omitted when the invitation has no use limit." } } }, "PublicInviteGrant": { "oneOf": [ { "type": "object", "required": [ "id", "public_portal_id", "has_lights", "openable", "entry_kind", "kind" ], "properties": { "door_image_thumb_url": { "type": [ "string", "null" ], "description": "Presigned URL for the `thumb` rendition of the door image, for avatar-sized\nrenders. Absent when the source is already thumb-sized; fall back to\n`door_image_url`." }, "door_image_url": { "type": [ "string", "null" ], "description": "Presigned URL for door image (loaded asynchronously as card background)." }, "entry_kind": { "type": "string", "description": "Entry type configured on the linked portal device (`entry_kind` in its\n`virtual_access` metadata). 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" }, "wifi_available": { "type": "boolean", "description": "The door's zone is covered by a Wi-Fi network the guest may join, for example\nwhere the door has no cellular signal. A suggestion only: the door opens either way.\nThe networks are in `wifi_networks` on the response." } } }, { "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": {}, "wifi_available": { "type": "boolean", "description": "The acted-on device's zone is covered by a Wi-Fi network (see `PortalOpen`)." } } } ] }, "PublicInviteLocaleResponse": { "type": "object", "required": [ "locale" ], "properties": { "locale": { "type": "string", "description": "Locale code (`en`, `he`, `pt_br`) of the language the invitation's messages are sent in\nfor this link's contact." } } }, "PublicInviteOtpStartRequest": { "type": "object", "properties": { "channel": { "type": [ "string", "null" ], "description": "`sms` (default) or `email`. The destination is the matching contact on the invitation." } }, "additionalProperties": false }, "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", "audience" ], "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" ] }, "audience": { "type": "string", "description": "Whether anyone holding the link may use the invitation, or only the named contacts." }, "blackout_dates": { "type": [ "array", "null" ], "items": { "type": "string" } }, "building": { "description": "Building (integration) summary: `name` (LocalizedString) and optional `location` fields\nfrom integration config (`formatted_address`, `city`, `country`)." }, "contact_challenge_required": { "type": "boolean", "description": "True when the bearer must prove they are one of the named contacts before the invitation\ncan be used. Which contact was matched is never echoed back, so this cannot be used to\nenumerate who an invitation is for." }, "contact_display_name": { "type": [ "string", "null" ], "description": "The display name of the contact this token resolved to, when it resolved to one." }, "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" }, "max_uses": { "type": [ "integer", "null" ], "format": "int32", "description": "Total uses allowed; omitted when the invitation has no use limit." }, "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)." }, "uses_remaining": { "type": [ "integer", "null" ], "format": "int32", "description": "Uses left before the limit is consumed; omitted when the invitation has no use limit." }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] }, "wifi_networks": { "type": "array", "items": { "$ref": "#/components/schemas/PublicInviteWifiNetwork" }, "description": "Wi-Fi networks that cover the invitation's doors, with credentials, ordered by priority.\nPresent only for an active invitation whose grants are shown, and only when at least one\ngrant has `wifi_available`. Never part of a link preview." } } }, "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" ] }, "PublicInviteWifiNetwork": { "type": "object", "description": "A Wi-Fi network as the invite page shows it.", "required": [ "id", "ssid", "security", "hidden" ], "properties": { "credentials_unavailable": { "type": "boolean", "description": "The credentials could not be read right now. The network is listed so the guest knows it\nexists and can ask the host; the door itself opens without Wi-Fi." }, "hidden": { "type": "boolean", "description": "The network does not broadcast its SSID." }, "id": { "type": "string" }, "notes": { "type": [ "string", "null" ], "description": "Where the network reaches, for example \"lobby only\"." }, "password": { "type": [ "string", "null" ], "description": "Passphrase (`wpa_psk`) or enterprise password. Absent for open networks." }, "security": { "$ref": "#/components/schemas/WifiSecurity" }, "ssid": { "type": "string" }, "username": { "type": [ "string", "null" ], "description": "Enterprise username (`wpa_enterprise` only)." } } }, "PublicPortalAccessControl": { "type": "object", "required": [ "name" ], "properties": { "city": {}, "country": {}, "formatted_address": { "description": "Normalized street address (localized JSON)." }, "geocoding_provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeocodingProviderId" } ] }, "image_thumb_url": { "type": [ "string", "null" ], "description": "Presigned URL for the `thumb` rendition of the same photo, for small renders.\nAbsent when the source is already thumb-sized; fall back to `image_url`." }, "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" }, "message": { "description": "Admin-authored text for `disabled`, as localized JSON." }, "name": { "description": "Integration / building name (localized JSON)." }, "notes": {}, "provider_place_id": { "type": [ "string", "null" ], "description": "Opaque place id for the address, when it was resolved by a maps provider, together with the\nprovider that issued it. Clients that recognize the provider can link to the place itself\n(e.g. Google Maps URLs `query_place_id`) instead of a bare coordinate; the rest fall back to\nthe address text. Both fields are present together or not at all." }, "status": { "type": [ "string", "null" ], "description": "Directory status when this summary describes the visitor directory: one of `ready`,\n`empty`, `not_configured`, `disabled`. Absent for the access-control summary." } } }, "PublicPortalCreateSessionRequest": { "type": "object", "description": "Start a visitor session with a directory entry.", "required": [ "target_entity_id", "mode" ], "properties": { "mode": { "type": "string", "description": "`voice`, `video` or `message` (case-insensitive); any other value is rejected with 400." }, "target_entity_id": { "type": "string", "description": "ID of the directory entry (listing entity) to contact. Required; 400 when blank." } }, "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" }, "reason": { "type": [ "string", "null" ], "description": "Why the door is not reachable, when the server knows. `door_not_connected`: the portal has\nno door (it was purged, or never linked), so retrying cannot help. Omitted when reachable\nand when the cause is a door that exists but did not answer." } } }, "PublicPortalResponse": { "type": "object", "required": [ "public_portal_id", "mode", "entry_kind", "door_connected" ], "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_connected": { "type": "boolean", "description": "False when the portal has no door to open: the door was purged, or the portal was never\nlinked to one. The printed QR code stays valid; an admin can link a door again." }, "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 configured on the linked portal device (`entry_kind` in its\n`virtual_access` metadata). 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", "effective_display_name", "floor", "allowed_actions" ], "properties": { "allowed_actions": { "type": "array", "items": { "type": "string" } }, "call_available": { "type": [ "boolean", "null" ], "description": "True when at least one resident (receives_calls) exists. When false, voice/video are excluded from allowed_actions." }, "denial_reasons": { "type": "array", "items": { "type": "string" }, "description": "Why this entry cannot be called; empty when nothing blocks a call. `no_callees`: nobody\nat this entry receives calls. `dnd`: Do Not Disturb is on for this entry, or no callee\ncan currently be notified. `guest_disabled`: visitor access to this entry is turned off\nby policy." }, "display_name": {}, "effective_display_name": { "type": "string", "description": "Server-resolved visitor name. Clients render this and do not recompute it." }, "floor": {}, "floor_number": { "type": [ "integer", "null" ], "format": "int64" }, "image": { "type": [ "string", "null" ] }, "listing_label": {}, "listing_number": { "type": [ "integer", "null" ], "format": "int64" }, "require_video": { "type": [ "boolean", "null" ] }, "target_id": { "type": "string" } } }, "PublicPortalTargetsResponse": { "type": "object", "required": [ "targets", "status" ], "properties": { "floor_order": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Building `floor_order` from virtual_access integration config (canonical keys)." }, "message": { "description": "Admin-authored text shown to visitors when `status` is `disabled`. Omitted for every\nother status." }, "status": { "type": "string", "description": "One of `ready`, `empty`, `not_configured`, `disabled`. Each carries its own visitor\ncopy, so a building with no occupants reads differently from an intercom that was never\nset up." }, "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 listing / unit title for call UI (caller/callee)." }, "call_target_location_line": { "type": [ "string", "null" ], "description": "Single line for listing + 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": "Session mode: `voice`, `video` or `message`. Video is on by default when the mode is\n`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": "IDs of the camera devices configured on the session's portal (cameras outside the\nportal's organization are excluded). Empty when the session has no portal device. Stream\nURLs are not included." } } }, "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 }, "PutObservedLocaleRequest": { "type": "object", "required": [ "locale" ], "properties": { "locale": { "type": "string", "description": "The app or device language: a BCP-47 tag (`he-IL`, `pt-BR`) or a supported locale code\n(`zh_cn`). Stored as the matching supported code; an unsupported language is\nrejected with 422." } }, "additionalProperties": false }, "QuietHoursPolicyConfig": { "type": "object", "description": "Typed `config` shape for `quiet_hours`.", "required": [ "start", "end" ], "properties": { "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "end": { "type": "string", "description": "Inclusive local end of the window, in `HH:MM`; a later end wraps midnight." }, "start": { "type": "string", "description": "Inclusive local start of the window, in `HH:MM`." } } }, "QuotaKey": { "type": "string", "description": "A metered resource. Lifetime keys count resources that currently exist; temporal keys count\nusage within a period.", "enum": [ "org_users", "organizations", "integrations", "devices", "entities", "groups", "external_group_members", "zones", "api_keys", "door_opens", "voice_invocations", "portal_views", "video_sessions", "video_session_duration_seconds", "scripting_executions", "ai_requests", "geocoding_requests", "invitation_api_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 usage report for an org.", "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_listings", "listing_no_members", "intercom_directory_draft", "site_multiple_intercom_directories", "site_no_people" ] }, "ReadinessSection": { "type": "string", "enum": [ "doors", "portals", "virtual_intercom", "people" ] }, "ReadinessSeverity": { "type": "string", "description": "Readiness severity, from least to most severe: `ok`, `incomplete`, `partial`, `blocking`.", "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", "listing", "directory" ] }, "ReconcileAccessInviteRequest": { "type": "object", "required": [ "external_ref" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalReferenceInput", "description": "The external record this reconcile is about. It identifies the invitation, so the caller\ndoes not need to track OpenApp invitation ids." }, "invitation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateAccessInviteRequest", "description": "Desired invitation. Required when `state` is `active`, ignored when `revoked`. It must not\ncarry its own `external_ref`: the top-level reference owns the binding." } ] }, "state": { "$ref": "#/components/schemas/ReconcileInviteState", "description": "Desired state for that record. Defaults to `active`." } }, "additionalProperties": false }, "ReconcileAccessInviteResponse": { "type": "object", "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/ReconcileAction" }, "external_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalReferenceResponse" } ] }, "idempotent_replay": { "type": "boolean", "description": "True when this body is a replay of an earlier reconcile carrying the same\n`Idempotency-Key`; nothing was written by this request." }, "invite": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccessInviteListItem", "description": "Invitation state after reconciling." } ] }, "invite_link_id": { "type": [ "string", "null" ], "description": "The invitation serving the external record. Absent only when the desired state is `revoked`\nand no invitation exists for the record." }, "invite_token": { "type": [ "string", "null" ], "description": "Guest bearer token, returned **once**, only by the call that created the invitation. A\nreplayed reconcile omits it; use `regenerate-token` to obtain a fresh link." }, "invite_url": { "type": [ "string", "null" ], "description": "Guest-facing invite URL, with the same one-time visibility as `invite_token`." } } }, "ReconcileAction": { "type": "string", "description": "What a reconcile actually did.", "enum": [ "created", "updated", "restored", "revoked", "unchanged" ] }, "ReconcileInviteState": { "type": "string", "description": "Desired lifecycle state of the invitation that serves an external record.", "enum": [ "active", "revoked" ] }, "RedeemGroupShareOfferPayload": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } }, "additionalProperties": false }, "RedeemHouseholdInvitationRequest": { "type": "object", "required": [ "token", "pin" ], "properties": { "pin": { "type": "string" }, "token": { "type": "string" } }, "additionalProperties": false }, "RedeemHouseholdInvitationResponse": { "type": "object", "required": [ "group_id" ], "properties": { "group_id": { "type": "string" } } }, "RedeemInvitationRequest": { "type": "object", "required": [ "token", "pin" ], "properties": { "accept_on_signed_in_account": { "type": "boolean", "description": "Attach the invitation to the signed-in account when its mailbox is not the invited email.\nThe invited address is not stored. Required only in that case; omitted otherwise." }, "merge_accounts": { "type": "boolean", "description": "Start a combine-accounts offer when the invited email or phone already belongs to someone else.\nThe invitation stays pending until that offer is confirmed and redeem is called again." }, "phone_action": { "type": [ "string", "null" ], "description": "`keep` leaves the account's phone unchanged. `replace` saves the invited number over it.\nRequired when the account already has a different phone and the invited number is free." }, "pin": { "type": "string" }, "token": { "type": "string" } }, "additionalProperties": false }, "RedeemInvitationResponse": { "type": "object", "required": [ "org_id", "user_id", "default_roles" ], "properties": { "accepted": { "type": "boolean", "description": "False when `merge` was created and the invitation is still pending.\nOmitted when the invitation was accepted, so older clients treat a missing field as accepted." }, "default_roles": { "type": "array", "items": { "type": "string" } }, "merge": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MergeOfferDto" } ] }, "org_id": { "type": "string" }, "user_id": { "type": "string" } } }, "RegenerateAccessInviteTokenResponse": { "type": "object", "required": [ "invite_token", "invite_url", "last_shared_at" ], "properties": { "invite_token": { "type": "string" }, "invite_url": { "type": "string", "description": "Guest-facing invite URL (shareable link for SMS/email)." }, "last_shared_at": { "type": "string" } } }, "RegistrationStatus": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "RequireStepUpPolicyConfig": { "type": "object", "description": "Typed `config` shape for `require_step_up`.", "properties": { "applies_to": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PolicyPrincipalKind" }, "description": "Principal kinds the row binds; unknown and empty values are rejected. Omitted binds the\ntype's default principals." }, "resource_selector": { "type": [ "object", "null" ], "description": "Entities requiring confirmation: `\"*\"`, one entity ULID, or a non-empty array of entity\nULIDs. Omitted applies to every entity." } } }, "ResendHouseholdInvitation": { "type": "object", "description": "Body of a resend.", "properties": { "sms_consent_confirmed": { "type": "boolean", "description": "Must be `true` when the invitation has a phone: confirms the person you invite agreed to\nreceive text messages from OpenApp at that number. Not needed for email-only\ninvitations; send `{}`." } }, "additionalProperties": false }, "ResendInvitationRequest": { "type": "object", "description": "Body of a resend.", "properties": { "sms_consent_confirmed": { "type": "boolean", "description": "Must be `true` when the invitation has a phone: confirms the person being invited agreed\nto receive text messages from OpenApp at that number. Not needed for email-only\ninvitations; send `{}`." } }, "additionalProperties": false }, "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": "Lifecycle timestamps of a resource (created, updated, soft-deleted, scheduled purge and hard\ndelete), at the top level of the resource object. Timestamps that are not set are omitted.", "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": "Degradation state of a single resource.", "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" }, "geocoding_provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeocodingProviderId" } ] }, "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" }, "provider_place_id": { "type": [ "string", "null" ], "description": "Opaque place id issued by `geocoding_provider`, when the point resolved to a known place.\nBoth fields are present together or not at all." } } }, "Role": { "type": "string", "description": "A role name (e.g. admin, users:read) assigned to a user in an org." }, "ScriptingExecution": { "type": "object", "required": [ "id", "status", "created_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ], "description": "Present only when `status` is `failed` or `canceled`." }, "id": { "type": "string" }, "result": { "description": "Present only when `status` is `succeeded`." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/ExecutionStatus" } } }, "ScriptingExecutionSummary": { "type": "object", "description": "A scripting execution as returned by list endpoints: every field of a scripting execution\nexcept `result`. Fetch the execution by id to read its result.", "required": [ "id", "status", "created_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/ExecutionStatus" } } }, "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, or as an exact\n(case-insensitive) org ID." } } } ] }, "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)" }, "role": { "type": [ "string", "null" ], "description": "Membership role that must be held (within `org_id` when set; any org when `scope=all`)." }, "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. A blocking issue that\nnames a subject takes only that subject out of service, so the section is `partial`;\nonly site-scoped blocking issues make the section `blocking`." } } }, "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": [ "listing_entity_ids" ], "properties": { "listing_entity_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "SetOrgDefaultLocaleRequest": { "type": "object", "properties": { "default_locale": { "type": [ "string", "null" ], "description": "Supported locale code (`en`, `zh_cn`, `es`, `ru`, `pt_br`, `de`, `fr`, `ja`,\n`ar`, `it`, `he`), or `null` to clear." } }, "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 }, "SetWifiNetworkZonesRequest": { "type": "object", "required": [ "zone_ids" ], "properties": { "zone_ids": { "type": "array", "items": { "type": "string" }, "description": "The complete set of zones the network covers. Each must be a live zone of the network's\norg." } }, "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" } } }, "SiteAccessDevice": { "type": "object", "description": "One device in one section. A device may appear in more than one section.", "required": [ "device_id", "name", "integration_id", "deleted", "entities", "doors" ], "properties": { "created_at": { "type": [ "string", "null" ] }, "deleted": { "type": "boolean", "description": "True when the device is soft-deleted but still referenced by a door." }, "device_id": { "type": "string" }, "doors": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessDeviceDoor" }, "description": "Doors this device serves in this role (union of `entities[].doors`)." }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessDeviceEntity" }, "description": "Entities on this device playing this section's role. Empty for cameras." }, "external_id": { "type": [ "string", "null" ] }, "integration_id": { "type": "string", "description": "Owning integration — usually not the site's own integration." }, "name": { "$ref": "#/components/schemas/LocalizedString" } } }, "SiteAccessDeviceDoor": { "type": "object", "description": "A door (portal device) a device serves.", "required": [ "door_device_id", "name" ], "properties": { "auto_off_config": { "description": "The door's `auto_off_config` for this light entry. Lights only." }, "door_device_id": { "type": "string" }, "life_safety": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SiteAccessDoorLifeSafety", "description": "The door's life-safety class and attestation, for open gating." } ] }, "name": { "$ref": "#/components/schemas/LocalizedString" } } }, "SiteAccessDeviceEntity": { "type": "object", "description": "An entity on the device that plays the section's role.", "required": [ "entity_id", "name", "entity_type", "doors" ], "properties": { "doors": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessDeviceDoor" }, "description": "Doors this entity serves, each carrying that door's light auto-off config." }, "entity_id": { "type": "string" }, "entity_type": { "type": "string", "description": "`entity_type` as stored (`switch`, `door`, `light`, …)." }, "label": { "type": [ "string", "null" ], "description": "The label the door gave this opener/light, when set." }, "name": { "type": "string" } } }, "SiteAccessDeviceRole": { "type": "string", "description": "Which door-side list put a device in a section.", "enum": [ "opener", "light", "camera" ] }, "SiteAccessDevicesResponse": { "type": "object", "required": [ "openers", "lights", "cameras", "unresolved" ], "properties": { "cameras": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessDevice" } }, "lights": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessDevice" } }, "openers": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessDevice" } }, "unresolved": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessUnresolvedRef" }, "description": "Door references that resolve to no device. Never empty-by-omission." } } }, "SiteAccessDoorLifeSafety": { "type": "object", "description": "A door's life-safety class and commissioning attestation, as stored on the door.\n\nThe server refuses `switchable.open` and `switchable.toggle` on an opening that has no class,\nor whose class requires an attestation that is missing or incomplete (409\n`life_safety_class_required` / `life_safety_attestation_required`). This object reports the\nstored values so clients can show whether the door can be opened.", "properties": { "attestation": {}, "class": { "type": [ "string", "null" ] } } }, "SiteAccessOverviewDevices": { "type": "object", "required": [ "total", "unresolved", "openers", "lights", "cameras" ], "properties": { "cameras": { "type": "integer", "format": "int64", "minimum": 0 }, "lights": { "type": "integer", "format": "int64", "minimum": 0 }, "openers": { "type": "integer", "format": "int64", "minimum": 0 }, "total": { "type": "integer", "format": "int64", "minimum": 0 }, "unresolved": { "type": "integer", "format": "int64", "minimum": 0 } } }, "SiteAccessOverviewPortal": { "type": "object", "required": [ "id" ], "properties": { "device_id": { "type": [ "string", "null" ] }, "id": { "type": "string" } } }, "SiteAccessOverviewResponse": { "type": "object", "required": [ "integration", "doors_count", "listings_count", "visible_listings_count", "people_count", "invitations_count", "portals_count", "portals" ], "properties": { "devices": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SiteAccessOverviewDevices", "description": "Missing when the requester cannot list devices." } ] }, "directory_device_id": { "type": [ "string", "null" ] }, "doors_count": { "type": "integer", "format": "int64", "minimum": 0 }, "integration": { "$ref": "#/components/schemas/Integration", "description": "Sanitized integration data used by the setup checklist." }, "invitations_count": { "type": "integer", "format": "int64", "minimum": 0 }, "listings_count": { "type": "integer", "format": "int64", "minimum": 0 }, "people_count": { "type": "integer", "format": "int64", "minimum": 0 }, "policies_count": { "type": [ "integer", "null" ], "format": "int64", "description": "Missing when the requester cannot list policies.", "minimum": 0 }, "portals": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessOverviewPortal" }, "description": "Portal-to-door links are used to scope readiness issues on the hub." }, "portals_count": { "type": "integer", "format": "int64", "minimum": 0 }, "visible_listings_count": { "type": "integer", "format": "int64", "minimum": 0 }, "wifi": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SiteAccessOverviewWifi", "description": "Missing when the requester lacks `zones:read`." } ] }, "zones": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SiteAccessOverviewZones", "description": "Missing when the requester lacks `zones:read`." } ] } } }, "SiteAccessOverviewWifi": { "type": "object", "required": [ "total" ], "properties": { "total": { "type": "integer", "format": "int64", "description": "Networks that apply to at least one of the site's doors.", "minimum": 0 } } }, "SiteAccessOverviewZones": { "type": "object", "description": "Counts of the site's zones and Wi-Fi networks, from the same resolution as `access-zones`.", "required": [ "total", "doors_without_zone" ], "properties": { "doors_without_zone": { "type": "integer", "format": "int64", "description": "Doors with no zone.", "minimum": 0 }, "total": { "type": "integer", "format": "int64", "description": "Zones that hold at least one of the site's doors.", "minimum": 0 } } }, "SiteAccessUnresolvedReason": { "type": "string", "description": "Why a door's reference has no device to show.", "enum": [ "entity_missing", "device_missing" ] }, "SiteAccessUnresolvedRef": { "type": "object", "description": "A door reference with nothing to show.", "required": [ "role", "reference", "reason", "doors" ], "properties": { "doors": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessDeviceDoor" } }, "reason": { "$ref": "#/components/schemas/SiteAccessUnresolvedReason" }, "reference": { "type": "string", "description": "The raw id from the door's metadata (entity id for openers/lights, device id for cameras)." }, "role": { "$ref": "#/components/schemas/SiteAccessDeviceRole" } } }, "SiteAccessWifiCover": { "type": "object", "description": "A zone of the site that a network reaches, and whether it reaches it directly.", "required": [ "zone_id" ], "properties": { "via_zone_id": { "type": [ "string", "null" ], "description": "The ancestor zone the network is linked to. Absent when the network is linked to\n`zone_id` itself." }, "via_zone_name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString", "description": "Name of `via_zone_id`." } ] }, "zone_id": { "type": "string", "description": "A site zone (one that holds doors) the network applies to." } } }, "SiteAccessWifiNetwork": { "type": "object", "description": "A Wi-Fi network that applies to at least one door of the site.", "required": [ "id", "ssid", "security", "hidden", "priority", "has_credentials", "covers" ], "properties": { "covers": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessWifiCover" }, "description": "The site zones this network applies to, and how." }, "has_credentials": { "type": "boolean", "description": "False for `open` networks. Credentials are never part of this response." }, "hidden": { "type": "boolean" }, "id": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "format": "int32" }, "security": { "$ref": "#/components/schemas/WifiSecurity" }, "ssid": { "type": "string" } } }, "SiteAccessZone": { "type": "object", "description": "A zone that holds at least one door of the site.", "required": [ "id", "name", "path", "doors" ], "properties": { "doors": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessZoneDoor" }, "description": "Doors of the site placed in this zone." }, "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "path": { "type": "array", "items": { "$ref": "#/components/schemas/LocalizedString" }, "description": "Zone names from the root zone down to this zone, inclusive." } } }, "SiteAccessZoneDoor": { "type": "object", "description": "A door of the site.", "required": [ "device_id", "name" ], "properties": { "device_id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" } } }, "SiteAccessZonesResponse": { "type": "object", "required": [ "doors_without_zone" ], "properties": { "doors_without_zone": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAccessZoneDoor" }, "description": "Doors with no zone. Their invitations offer no Wi-Fi and no zone policy binds them." }, "wifi_networks": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SiteAccessWifiNetwork" }, "description": "Networks that apply to the site's doors. Omitted when the requester lacks `zones:read`." }, "zones": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SiteAccessZone" }, "description": "Zones that hold the site's doors. Omitted when the requester lacks `zones:read`." } } }, "SitePersonGroupResponse": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": {} } }, "SitePersonListingResponse": { "type": "object", "required": [ "id" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "id": { "type": "string" } } }, "SitePersonResponse": { "type": "object", "required": [ "user_id", "role", "source", "listings", "listing_names", "groups" ], "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/SitePersonGroupResponse" } }, "listing_names": { "type": "array", "items": { "$ref": "#/components/schemas/SitePersonListingResponse" } }, "listings": { "type": "array", "items": { "type": "string" } }, "role": { "type": "string", "description": "Site role (`admin`, `resident`, `technician`) or, for a via-group row, the group role." }, "source": { "type": "string", "description": "`org_member` or `via_group`. Via-group rows have no site role to edit." }, "user_email": { "type": [ "string", "null" ] }, "user_id": { "type": "string" }, "user_name": {} } }, "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. A null `stock_quantity` means stock is not tracked\n(no limit); a number is enforced and decremented on each 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 membership visible in\nhistory but blocks purchasing.", "required": [ "id", "store_id", "user_id", "role", "status" ], "properties": { "billing_account_id": { "type": [ "string", "null" ], "description": "Account purchases are charged to. When null, purchases are charged to the member's\npersonal 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. A soft-deleted product stays readable until `purge_at`.", "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 entry.", "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 note codes to show the user 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 to show the user before confirming the transfer." } } }, "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": { "audience": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InviteAudience", "description": "When set, changes whether anyone holding the link may use the invitation." } ] }, "contacts": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AccessInviteContactInput" }, "description": "When set, replaces the invitation's contacts. Omitted leaves them unchanged." }, "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" ] }, "external_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalReferenceInput", "description": "External-record precondition and correlation. When present, `source`/`record_id` must match\nthe invitation's stored reference (or bind it for the first time), and a `revision` older\nthan the stored one is rejected with `external_revision_stale` so a late event cannot\nrestore an earlier room, window, or portal set." } ] }, "invitee_message": {}, "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. This is the only way to change validity or\nrecurrence." } }, "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" ] } } }, "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" } ] }, "zone_id": { "type": [ "string", "null" ], "description": "Omit for no change, `null` to clear, or a zone id (same org) to place the device." } }, "additionalProperties": false }, "UpdateDirectoryConfigPayload": { "type": "object", "properties": { "allowed_listing_kinds": { "type": [ "array", "null" ], "items": { "type": "string" } }, "disabled_message": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "naming_patterns": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "state": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateDirectoryListingMemberPayload": { "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 }, "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- omitted: no change\n- `null`: clear metadata\n- object: replace with the provided map", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "Update entity name.\n\n- omitted: no change\n- `null`: clear\n- string: set (trimmed; an empty string clears)" }, "zone": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ZonePlacement", "description": "Replace the zone placement. Omit for no change." } ] } }, "additionalProperties": false }, "UpdateGroupLinkPayload": { "type": "object", "properties": { "admission_mode": { "type": [ "string", "null" ], "description": "approve waits for each member to be admitted; auto admits them immediately; pinned holds a\nfixed member set until an explicit re-sync." }, "resync": { "type": [ "boolean", "null" ], "description": "With pinned mode, re-reads the group's current membership and admits the difference." } }, "additionalProperties": false }, "UpdateGroupMemberPayload": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string" } }, "additionalProperties": false }, "UpdateGroupPayload": { "type": "object", "properties": { "description": {}, "kind": { "type": [ "string", "null" ] }, "name": {}, "shareable": { "type": [ "boolean", "null" ] } }, "additionalProperties": false }, "UpdateHouseholdPayload": { "type": "object", "description": "Payload for renaming a household.", "required": [ "name" ], "properties": { "name": { "type": "string" } }, "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), except write-only credential\n fields (schema `format: password`): omitted keeps the stored value, `null` clears it" }, "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 }, "UpdateInvitationRequest": { "type": "object", "description": "Fields of a pending invitation that can be edited. Omit a field to leave it unchanged.", "properties": { "default_roles": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Replaces the roles assigned on accept (within the inviting org)." }, "locale": { "type": [ "string", "null" ], "description": "Replaces the message language: a supported locale code. Applies to messages sent from now\non; a message already sent keeps the language it was written in." }, "site_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvitationSiteAccessDto", "description": "Replaces the site (and listing) access applied when the invitation is redeemed." } ] } }, "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 with 400." }, "enabled": { "type": [ "boolean", "null" ] }, "enforcement": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateSitePersonPayload": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string" } }, "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 }, "UpdateWifiNetworkRequest": { "type": "object", "required": [ "ssid", "security" ], "properties": { "credentials": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WifiCredentials", "description": "Omit to keep the stored credentials, which is only allowed while `security` is unchanged.\nChanging `security` to a type that needs credentials requires them here." } ] }, "hidden": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "format": "int32" }, "security": { "$ref": "#/components/schemas/WifiSecurity" }, "ssid": { "type": "string" } }, "additionalProperties": false }, "UpdateZoneRequest": { "type": "object", "properties": { "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalizedString" } ] }, "parent_zone_id": { "type": [ "string", "null" ], "description": "Omit for no change, `null` to make the zone a root, or a zone id to reparent." } }, "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": "Who performed the action: `user`, `guest`, `agent` or `system`." }, "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 an internal placeholder when no verified email is available." }, "id": { "type": "string", "description": "Unique identifier (ULID)." }, "merged_into_user_id": { "type": [ "string", "null" ], "description": "When set, this user was merged into the user with this id; use that user as the live\nidentity." }, "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_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Groups joined when the invitation is redeemed, in the same transaction as the org role." }, "default_roles": { "type": "array", "items": { "type": "string" } }, "email": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "invited_by_user_id": { "type": "string" }, "invitee_name": { "type": [ "string", "null" ], "description": "Name the inviter gave for the invitee. Present only while the invitation is pending." }, "last_sent_at": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ], "description": "Message language the sender chose, or `null` when none was chosen." }, "message_locale": { "type": [ "string", "null" ], "description": "Shipped locale code of the language the invitation messages are written in: the invitee's\nown account language, else `locale`, else the org default, else English. Present only while\nthe invitation is pending." }, "org_id": { "type": "string" }, "phone": { "type": [ "string", "null" ], "description": "SMS recipient when the invite includes a phone (E.164)." }, "phone_transport": { "type": [ "string", "null" ], "description": "`sms` or `whatsapp` when a phone PIN was sent." }, "resend_available_at": { "type": [ "string", "null" ], "description": "When a resend is next accepted (RFC 3339). Present only while the invitation is pending;\na resend before this time is refused with 429." }, "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 an internal placeholder (phone-only account or identity-provider merge claimant) and must not be shown as a mailbox." }, "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 } } }, "WifiCredentials": { "type": "object", "description": "Secret part of a Wi-Fi network. Stored in Secrets Manager, never in Postgres.", "properties": { "password": { "type": [ "string", "null" ], "description": "Passphrase (`wpa_psk`) or enterprise password (`wpa_enterprise`). Absent for `open`." }, "username": { "type": [ "string", "null" ], "description": "Enterprise username. Present only for `wpa_enterprise`." } }, "additionalProperties": false }, "WifiNetwork": { "type": "object", "description": "A Wi-Fi network owned by an org.", "required": [ "id", "org_id", "ssid", "security", "hidden", "priority", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "hidden": { "type": "boolean", "description": "The network does not broadcast its SSID." }, "id": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "priority": { "type": "integer", "format": "int32", "description": "Lower values are listed first." }, "security": { "$ref": "#/components/schemas/WifiSecurity" }, "ssid": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WifiNetworkResponse": { "allOf": [ { "$ref": "#/components/schemas/WifiNetwork" }, { "type": "object", "required": [ "zone_ids", "has_credentials" ], "properties": { "has_credentials": { "type": "boolean", "description": "False for `open` networks." }, "zone_ids": { "type": "array", "items": { "type": "string" }, "description": "Zones this network covers. Invitations to doors in these zones offer the network." } } } ], "description": "A Wi-Fi network as returned by the API. Credentials are never included; use the\ncredentials endpoint." }, "WifiSecurity": { "type": "string", "description": "How a Wi-Fi network authenticates.", "enum": [ "open", "wpa_psk", "wpa_enterprise" ] }, "Zone": { "allOf": [ { "$ref": "#/components/schemas/ResourceLifecycle" }, { "type": "object", "required": [ "id", "org_id", "name" ], "properties": { "id": { "type": "string", "description": "Unique identifier (ULID)." }, "name": { "$ref": "#/components/schemas/LocalizedString", "description": "Zone name." }, "org_id": { "type": "string", "description": "Organization that owns this zone." }, "parent_zone_id": { "type": [ "string", "null" ], "description": "Parent zone (same org) for hierarchy." } } } ], "description": "A physical space owned by an org (recursive for hierarchy).\n\nExample: Floor 1 > Living Room > TV Nook. Placement of devices and entities is never\nconstrained by vendor: any device or entity of the same org may be placed in any zone." }, "ZonePathItem": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/LocalizedString" } } }, "ZonePlacement": { "oneOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "inherit" ] } } }, { "type": "object", "required": [ "zone_id", "mode" ], "properties": { "mode": { "type": "string", "enum": [ "explicit" ] }, "zone_id": { "type": "string" } } }, { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "none" ] } } } ], "description": "How an entity is placed in a zone.\n\n`inherit` follows the device's zone, `explicit` names a zone, and `none` keeps the entity out\nof every zone even when its device has one. Sent as `{\"mode\":\"inherit\"}`,\n`{\"mode\":\"explicit\",\"zone_id\":\"…\"}`, or `{\"mode\":\"none\"}`." }, "ZoneProviderLinkResponse": { "type": "object", "description": "Provider provenance as exposed on zone responses (the zone id is implied).", "required": [ "integration_id", "external_id" ], "properties": { "external_id": { "type": "string" }, "integration_id": { "type": "string" } } }, "ZoneResponse": { "allOf": [ { "$ref": "#/components/schemas/Zone" }, { "type": "object", "required": [ "provider_links" ], "properties": { "provider_links": { "type": "array", "items": { "$ref": "#/components/schemas/ZoneProviderLinkResponse" } } } } ] }, "ZoneRuleResponse": { "type": "object", "description": "One organization- or integration-tier policy scoped to a zone.", "required": [ "policy_id", "zone_id", "zone_name", "zone_path", "policy_type", "config" ], "properties": { "config": { "type": "object" }, "policy_id": { "type": "string" }, "policy_type": { "type": "string" }, "zone_id": { "type": "string" }, "zone_name": { "$ref": "#/components/schemas/LocalizedString" }, "zone_path": { "type": "array", "items": { "$ref": "#/components/schemas/LocalizedString" }, "description": "Zone names from the root to this zone (inclusive)." } } }, "ZoneSource": { "type": "string", "description": "Where an entity's effective zone came from.", "enum": [ "entity", "device", "door" ] }, "ZoneSummaryResponse": { "type": "object", "required": [ "zone", "path", "children", "device_count", "entity_count", "descendant_entity_count" ], "properties": { "children": { "type": "array", "items": { "$ref": "#/components/schemas/Zone" } }, "descendant_entity_count": { "type": "integer", "format": "int64", "minimum": 0 }, "device_count": { "type": "integer", "format": "int64", "minimum": 0 }, "entity_count": { "type": "integer", "format": "int64", "minimum": 0 }, "path": { "type": "array", "items": { "$ref": "#/components/schemas/ZonePathItem" }, "description": "Ancestors root first, including the zone itself." }, "zone": { "$ref": "#/components/schemas/ZoneResponse" } } }, "ZoneSyncResponse": { "type": "object", "description": "Result of `POST /integrations/{id}/zone-sync`.", "required": [ "zones_created", "zones_linked", "devices_placed", "entities_placed", "skipped_manual" ], "properties": { "devices_placed": { "type": "integer", "format": "int64", "description": "Devices whose zone this sync changed.", "minimum": 0 }, "entities_placed": { "type": "integer", "format": "int64", "description": "Entities whose placement this sync changed.", "minimum": 0 }, "skipped_manual": { "type": "integer", "format": "int64", "description": "Devices and entities left alone because a user changed their placement since the last\nsync, or because a door lists the entity and owns its zone.", "minimum": 0 }, "zones_created": { "type": "integer", "format": "int64", "description": "Org zones created for provider zones with no unique name match.", "minimum": 0 }, "zones_linked": { "type": "integer", "format": "int64", "description": "Provider zones newly linked to an existing org zone (by unique normalized name).", "minimum": 0 } } }, "ZoneTreeNode": { "type": "object", "required": [ "zone", "children", "device_count", "entity_count" ], "properties": { "children": { "type": "array", "items": { "$ref": "#/components/schemas/ZoneTreeNode" } }, "device_count": { "type": "integer", "format": "int64", "description": "Devices placed directly in this zone.", "minimum": 0 }, "entity_count": { "type": "integer", "format": "int64", "description": "Entities whose effective zone is this zone (not descendants).", "minimum": 0 }, "zone": { "$ref": "#/components/schemas/ZoneResponse" } } }, "ZoneTreeResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ZoneTreeNode" } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "OpenApp API key issued via `POST /api-keys`, sent verbatim as `X-API-Key: {origin}_openapp_{secret}`. `{origin}` is the deployment origin the key was issued by; the API root is `{origin}/api/v1`, which the SDKs derive from the key. Do not send API keys in `Authorization`: the gateway reserves it for JWTs and rejects an API key there with 401." } } } }