Agent-relevant API index

Use this page as a routing index when building agents or search-retrieval over OpenApp. Paths are relative to https://openapp.house/api/v1 unless noted. The machine-readable contract is OpenAPI JSON; browse schemas in the interactive API reference.

For setup and safety, start with Build an access-control agent.

Authentication and context

Concern	Operations	Notes
API keys	See API keys	X-API-Key. A scoped key reaches only these routes.
Org scope	Most GET /devices, integrations, zones	Header X-Org: {org_ulid}
Caller identity	GET /me/directory-listings, GET /me/invitations	No X-Org — Me. Not reachable with a scoped key.

Physical control (entities)

Intent	HTTP	operationId
List entities	GET /entities	list_entities
Get entity	GET /entities/{id}	get_entity
Open door / gate	POST /entities/{id}/actions/switchable.open	execute_entity_action
Preview (dry-run)	POST /entities/{id}/actions/{action_id}/preview	preview_entity_action
Close / toggle	POST .../switchable.close, .../switchable.toggle	execute_entity_action

Headers: Idempotency-Key (retries), X-OpenApp-Confirm (step-up confirmation).

When confirmation is required — by the agent’s confirmation mode or a require_step_up policy — the action returns an error with error_code: "confirmation_required" and a preview_token. Repeat the same request, with the same payload, with that token in X-OpenApp-Confirm. The token is short-lived and single-use.

Guide: Open the door with the HTTP API.

Agents, resolve, and hosted MCP

Intent	HTTP	Notes
Named agents	GET/POST /agents, POST /agents/{id}/credentials	First-class principal; audit actor_kind=agent
NL resolve	POST /orgs/{org_id}/resolve	Ranked candidates; ambiguous when top-2 are close
Aliases	POST/GET /orgs/{org_id}/aliases	Operator-defined spoken names
Hosted MCP	POST /mcp	OAuth; no scripting tools
Copilot	POST /orgs/{org_id}/copilot/chat, .../commit	Review-before-commit
Event skills	POST /orgs/{org_id}/skills	Versioned webhook playbooks
PMS inbound	POST /pms/{id}/inbound	Checkout → revoke invites
Perception	POST /orgs/{org_id}/perception/lpr, .../visitor-present	Same Cedar path as switchable.open

Groups (opt-in)

An agent credential carries entity, device and org read roles plus entities:set_state. Group routes (/orgs/{org_id}/groups, /groups/{id}/…, /group-share-offers/redeem) are closed to agents unless the agent’s organization enables agent_group_write. Then:

1. Mint the credential with group_roles, for example {"group_roles": ["groups:read", "groups:update"]} on POST /agents/{id}/credentials. You must hold each role in the agent’s organization yourself.
2. The credential can use those roles only in the agent’s organization and its sub-organizations.
3. If the policy is disabled, the next group request fails with 403 error_code: "agent_capability_disabled". Minting group roles without the policy fails the same way.

API keys and voice keys cannot carry group roles.

Trimmed Custom GPT spec: openapp-openapi-agent.json. MCP: MCP server setup.

Integrations, devices, zones

Intent	HTTP	operationId
List integrations	GET /integrations	list_integrations
Create integration	POST /integrations	create_integration
List devices	GET /devices	list_devices
Integration entities	GET /integrations/{id}/entities	list_integration_entities
Provider ops	POST /integrations/{id}/ops/{op_id}	execute_integration_op

SDK: Integrations, Devices, Entities.

Access portals and invites (admin)

Intent	HTTP	operationId
List portals	GET /integrations/{id}/access-portals	list_integration_access_portals
Create portal	POST /integrations/{id}/access-portals	create_integration_access_portal
List invites	GET /integrations/{id}/access-invites	list_integration_access_invites
Create invite	POST /integrations/{id}/access-invites	create_integration_access_invite
Update invite	PUT /integrations/{id}/access-invites/{invite_link_id}	update_integration_access_invite
Delete invite	DELETE .../access-invites/{invite_link_id}	delete_integration_access_invite

Guides: Time-bound guest invitation, Integrate existing software.

Public access (visitor / guest)

Intent	HTTP	operationId
Load invite	GET /public/access/invites/{inviteToken}	get_public_invite
Claim invite	POST .../claim	post_public_invite_claim
Execute grant (open)	POST .../execute	post_public_invite_execute
Portal config	GET /public/access/portals/{publicPortalId}	get_public_portal
Start call/video	POST .../portals/{id}/sessions	post_public_portal_sessions
Session open	POST /public/access/sessions/{sessionId}/open	post_public_session_open
Stream metadata	GET .../sessions/{sessionId}/streams	get_public_session_streams

Guide: Virtual intercom. SDK: Public Access.

Multi-tenant building

Intent	HTTP	Notes
Site people	GET/POST /integrations/{id}/people, DELETE /integrations/{id}/people/{user_id}	Site people
Org users / roles	/orgs/..., /users/...	Orgs, Users

Scripting and bulk provisioning

Intent	HTTP	operationId
Create execution	POST /scripting/executions	create_scripting_execution
Get execution	GET /scripting/executions/{id}	get_scripting_execution
List executions	GET /scripting/executions	list_scripting_executions
Cancel execution	DELETE /scripting/executions/{id}	cancel_scripting_execution

Executions are asynchronous jobs: POST returns 202 with a ScriptingExecution, and you poll GET until status is terminal (succeeded, failed, canceled). Runtime cap 15 minutes; executions are deleted 24 hours after completion; canceling does not roll back effects already applied.

Reference: OpenApp Scripting. Getting started: Scripting step.

Status and errors

Intent	HTTP	operationId
Backend health	GET /status	get_backend_status
Error shape	—	ApiErrorResponse: message (always), error_code, correlationId, preview_token (when error_code is confirmation_required)

See Errors & retries.

Audit and compliance

Intent	HTTP	operationId
List recent audit events	GET /orgs/{org_id}/audit/events	list_audit_events (30-day hot window, cursor pagination; supports exact target_id filters)
Start historical export	POST /orgs/{org_id}/audit/exports	create_audit_export
Poll export job	GET /orgs/{org_id}/audit/exports/{job_id}	get_audit_export
List / create webhooks	GET/POST /orgs/{org_id}/webhooks	list_webhooks / create_webhook

Guide: Query access and audit activity. When automating, preserve correlationId from API errors and org policy constraints. OpenApp does not replace certified life-safety design — see Architecture guide.