---
title: "Re-point a live install (human workspace owner only)"
method: PATCH
path: "/v1/apps/{id}/install"
tags: ["Apps"]
---

# Re-point a live install (human workspace owner only)

`PATCH /v1/apps/{id}/install`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/apps/{id}/install`
- Auth: HTTP bearer

Updates the surface URL, the allowed browser origin, and the OAuth client the origin is bound to. An absent field is unchanged; an explicit null clears the value. The origin and client are validated by exactly the rules install applies, against the merged next state. The service key, its grants, and the install status are not touched here. 409 when the install is uninstalled - install again instead.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `surface_url` string, nullable
  - `allowed_origin` string, nullable: Exact https origin admitted for the surface's browser calls. Must match the host of one of the OAuth client's registered redirect URIs, so a non-null origin requires an oauth_client_id on the merged row.
  - `oauth_client_id` string, uuid, nullable
  - `bindings` object: Rebind requirement slots: only the aliases present move, and only to resources of the slot's own kind. An alias with no stored binding takes its first one here. 400 `slot_unknown:` for an alias the approved manifest does not declare; 400 `endpoint_not_confirmed:` when the binding would give the install its first subscriptions (approve the version instead); 409 `install_not_ready:` while a newer version awaits approval — send bindings with `POST .../install/approve` then.

## Response `200`

Updated.

- object
  - `install` AppInstall: The binding between one workspace and one external service (Apps spec B7.1). Not versioned and never part of the manifest: it holds the ids that exist in one deployment only (service key, OAuth client, URL, origin).
    - `app_id` string, uuid
    - `status` 'installed' | 'suspended' | 'uninstalled'
    - `service_api_key_id` string, uuid, nullable: The workspace key the service authenticates with; null once revoked.
    - `oauth_client_id` string, uuid, nullable: The pre-consented OAuth public client the surface exchanges a session code for.
    - `surface_url` string, nullable
    - `allowed_origin` string, nullable: Exact https origin (scheme + host + optional port), no wildcard, no path.
    - `installed_by` string, nullable
    - `installed_at` string, date-time, nullable
    - `suspended_at` string, date-time, nullable
    - `suspended_reason` string, nullable: 'key_revoked' when the service key was revoked; otherwise the owner's reason.
    - `last_seen_at` string, date-time, nullable
    - `uninstalled_at` string, date-time, nullable
    - `approved_version` integer, nullable: The manifest version this install's grants, subscriptions and bindings were last synced against (§B13.2).
    - `approved_at` string, date-time, nullable
    - `approved_by` string, nullable
    - `pending_approval_version` integer, nullable: Set when a publish or hosted refresh parked a newer version on this install; while set the install is fail-closed (no embedded session, no run start, no decision-task offer, no delivery) until `POST .../install/approve`.
    - `subscriptions` AppSubscription[]
      - `id` string, uuid
      - `event_type` string
      - `match` object
      - `endpoint_url` string
      - `status` 'pending_verification' | 'active' | 'paused' | 'suspended' | 'revoked'
      - `failure_count` integer
      - `last_delivery_at` string, date-time, nullable
      - `verified_at` string, date-time, nullable
    - `bindings` AppInstallSlotBinding[]: What each requirement slot of the manifest was bound to at install.
      - `alias` string
      - `kind` string: AppResourceType of the bound resource.
      - `resource_id` string, uuid
      - `bound_at` string, date-time

## Other responses

- `400`: slot_unknown: / endpoint_not_confirmed: (see the bindings field).
- `403`: The API key does not have the required scope.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the current resource state.
- `422`: The origin is not admissible for the bound OAuth client, OR (hosted apps only) `hosted_surface_fixed:` — `surface_url` was sent for a hosted app; its surface comes from the manifest and moves only when a new version is approved.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)