---
title: "Update Shortcut"
method: PATCH
path: "/api/v1/shortcuts/{id}"
tags: ["Shortcuts"]
---

# Update Shortcut

`PATCH /api/v1/shortcuts/{id}`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/shortcuts/{id}`
- Auth: HTTP bearer

Changes a shortcut you created. Send only the fields you want to change.

- `name`, `description`, `icon_emoji` — metadata, applied immediately.
- `visibility` — `org` lets everyone in your organization use the shortcut; `private` limits it to you and the people it is shared with (Share Shortcut). Applied immediately, with no new version.
- `outputs` — the full list of fields a run returns, in the same shape Create Shortcut takes. It replaces the previous outputs, is written onto the workflow's `output_shortcut` action, and publishes a **new version** of the shortcut. The version is re-derived from the workflow, so input columns added since the last publish are picked up at the same time; every existing input keeps its type, required flag and default. An output whose `name` is unchanged keeps its identity.

A shortcut is frozen at publish: editing the workflow on its own (Configure Action, Add Inputs) never changes what the shortcut takes or returns. This is the call that does.

For a shortcut shared globally by Floqer, this changes the source version used by new global runs. It requires verified Floqer publishing authority; accepted runs retain their original version.

Making a shortcut `private` while another workflow's Call Shortcut cell still calls it is refused with 409 `SHORTCUT_HAS_CALLERS`, naming the callers; send `force: true` to make it private anyway and break those calls.

Removing an output that another workflow's Call Shortcut cell reads is refused with 409 `SHORTCUT_CONTRACT_BREAK`, naming the outputs and the callers; send `force: true` to publish anyway and mark those call sites broken. A refused call changes nothing — not the workflow, not the shortcut.

Runs already in flight finish on the version they started on.

## Path parameters

- `id` string, required

## Request body

- UpdateShortcutBody: Body for Update Shortcut. Send only what changes. `outputs` replaces the previous outputs and publishes a new version; `name`, `description`, `icon_emoji` and `visibility` apply immediately.
  - `name` string: New display name.
  - `description` string: New description.
  - `icon_emoji` string: New icon emoji.
  - `outputs` object[]: The fields a run returns, in order. Each item names one output field and points it at a value: a `{{input.<field>}}` or `{{<action_instance_id>.<field>}}` reference, a literal, or a mix. Written onto the workflow's `output_shortcut` action (added to the end of the chain when there is none) and returned as `output_schema`. An output keeps its identity across updates as long as its `name` is unchanged. A reference nothing produces is kept and reported in `warnings`.
    - `name` string, required: Output field name — the key its value appears under in a run's `output_data`.
    - `value` string, required: Where the value comes from.
  - `extensions` object: Change which browser extensions can trigger the shortcut. A surface with an input `reference` turns it on or moves it to that input, `null` turns it off, and surfaces you leave out keep their setting. `{}` turns every extension off. Omit the field to leave the setting unchanged. Applies immediately, with no new version; the last update wins. When an `outputs` republish removes an input an extension fills, that extension is turned off and reported in `warnings`.
    - `linkedin` string, nullable: The input the LinkedIn extension fills from the profile page, by its `reference`.
    - `sales_navigator` string, nullable: The input the Sales Navigator extension fills from the page, by its `reference`.
  - `visibility` 'org' | 'private': Who can use the shortcut. `org`: everyone in your organization. `private`: you and the people it is shared with (Share Shortcut).
  - `force` boolean: Proceed even when the change breaks another workflow's Call Shortcut cell: new `outputs` that remove a field it reads (409 `SHORTCUT_CONTRACT_BREAK` otherwise), or `visibility: "private"` while it still calls the shortcut (409 `SHORTCUT_HAS_CALLERS` otherwise). Those call sites break. Defaults to false.

## Response `200`

Default Response

- object
  - `status` integer
  - `message` string
  - `warnings` object[]: Non-fatal issues with `outputs` — an unresolved `{{...}}` reference an item with neither a name nor a value, or an extension turned off because its input was removed (`extension_input_removed`). Same codes as Configure Action. Absent when every item applied cleanly.
    - `field` string
    - `code` string
    - `message` string
  - `data` Shortcut: A shortcut wraps a workflow with typed input/output schemas, providing a simplified interface for running workflows programmatically. Shortcuts can be shared across an organization.
    - `id` string: Unique shortcut identifier (UUID)
    - `workflow_id` string: UUID of the underlying workflow that powers this shortcut
    - `parent_app_id` string, nullable: If this is a shared copy, the ID of the original master shortcut. Null for master shortcuts.
    - `floqer_catalog_id` string: Global identity when this shortcut is shared across organizations.
    - `call_shortcut_id` string: Source shortcut ID accepted by a Call Shortcut workflow action.
    - `floqer_source_version` integer: Current published source version for a global shortcut.
    - `is_virtual` boolean: Whether this shortcut is a read-only projection.
    - `name` string: Shortcut display name
    - `description` string: Human-readable description of what the shortcut does
    - `creator_email` string: Email of the user who created the shortcut
    - `org_id` string: Organization ID the shortcut belongs to
    - `visibility` string, nullable: Get Shortcut only. `org`: everyone in the organization can use it. `private`: its creator and the people it is shared with. Null for a shortcut published before versioning.
    - `shared_users` string[]: Get Shortcut only. Emails it is shared with (use access). Populated for the shortcut's creator; otherwise `[]`.
    - `input_schema` InputField[]: Ordered list of input fields — derived from the workflow's input action (id1)
      - `reference` string: Snake_case identifier for this input field (derived from `name`) — use it as the key in `input_data` when running the shortcut
      - `name` string: Human-readable field name displayed in the shortcut UI
      - `description` string: Help text describing what value to provide for this field
      - `type` string: Field type: text, number, email, url, etc.
      - `required` boolean: Whether this field must be provided when running the shortcut
      - `defaultValue` unknown
    - `output_schema` OutputConfig[]: Ordered list of output fields — derived from the workflow's OUTPUT_CUSTOM_ENRICHMENT action
      - `name` string: Human-readable name for this output field — the key for its value in a run's `output_data`
      - `description` string: Description of what this output contains
      - `display_column` string: Column header label shown in results tables
    - `is_master` boolean: True if this is the original shortcut (not a shared copy)
    - `is_published` boolean: Whether the shortcut is published and available for runs
    - `is_archived` boolean: Whether the shortcut has been archived
    - `callable` boolean: Whether a workflow can call this shortcut: set its `id` as `shortcut` on a `call_shortcut` action. False until the shortcut has a published version; republish it in the Floqer app.
    - `extensions` object: Browser extensions that can trigger this shortcut, each with the input (by `reference`) it fills from the page. `{}` when none can. A `null` input means that extension is on but its input is no longer on the shortcut, so it fills nothing: set a new input or turn it off.
      - `linkedin` string, nullable: The input the LinkedIn extension fills from the profile page, by its `reference`.
      - `sales_navigator` string, nullable: The input the Sales Navigator extension fills from the page, by its `reference`.
    - `cover_image` string, nullable: URL of the shortcut's cover image
    - `icon_emoji` string, nullable: Emoji used as the shortcut icon
    - `created_at` string, date-time: When the shortcut was created
    - `updated_at` string, date-time: When the shortcut was last updated

## Other responses

- `400`: Bad Request — invalid body (`error: "Validation Error"` with per-field `errors[]`), the workflow has more than one `output_shortcut` action, or it can no longer back a shortcut (`code: "SHORTCUT_WORKFLOW_INELIGIBLE"` with `reasons[]`), or `extensions` names an input the shortcut does not have
- `401`: Unauthorized — missing or invalid API key
- `403`: Forbidden. `code` says which permission refused: ROLE_FORBIDDEN (your role), INSUFFICIENT_SCOPE (the API key's scopes), WORKFLOW_FORBIDDEN (no access to the workflow), KEY_WORKFLOW_FORBIDDEN (the API key's workflow restriction).
- `404`: Shortcut not found, archived, or not one you created
- `409`: Conflict — the new `outputs` break existing call sites (`code: "SHORTCUT_CONTRACT_BREAK"`, `breaks[]` + `callers`; send `force: true` to proceed), `visibility: "private"` would break other workflows' calls (`code: "SHORTCUT_HAS_CALLERS"` + `callers`; send `force: true` to proceed), the shortcut predates versioning and must be republished in the Floqer app first (`code: "SHORTCUT_NOT_PUBLISHED"`), or the workflow's draft holds an unpublished `output_shortcut` action to publish or remove first (`code: "OUTPUT_NODE_EXISTS"`)
- `429`: Too Many Requests — rate limit exceeded. Check `Retry-After` header for seconds until the limit resets.

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)