---
title: "Create Shortcut"
method: POST
path: "/api/v1/shortcuts/"
tags: ["Shortcuts"]
---

# Create Shortcut

`POST /api/v1/shortcuts/`

## Request

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

Packages a workflow as a shortcut and publishes its first version, in one call:

- **input_schema** — the workflow's input columns (List Inputs). Every column becomes an input; its `reference` is the snake_cased column name.
- **output_schema** — the `outputs` you send. Each item names one field a run returns and points it at a value, usually a `{{...}}` reference to an upstream action. They are written onto the workflow's `output_shortcut` action, which is added to the end of the chain when there is none.

**Requirements** (a 400 lists every unmet one in `reasons`): the workflow has at least one named input column, and at least one item in `outputs`. You must be able to edit the workflow. A workflow with one `output_shortcut` action per branch cannot be packaged here; use the Floqer app.

One shortcut per workflow: a second call returns 409. The created shortcut is published and runnable immediately — pass its `id` to Run Shortcut. To change its outputs or pick up new input columns later, call Update Shortcut; editing the workflow alone does not change the shortcut.

## Request body

- CreateShortcutBody: Body for Create Shortcut. `workflow_id`, `name` and `outputs` are required; the input schema is read from the workflow's input columns.
  - `workflow_id` string, required: UUID of the workflow to package. It must belong to your organization and have at least one named input column.
  - `name` string, required: Shortcut display name.
  - `description` string: What the shortcut does, shown in the Gallery and returned by Get Shortcut.
  - `icon_emoji` string: Emoji used as the shortcut icon. Defaults to 🚀.
  - `outputs` object[], required: 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: Browser extensions that can trigger the shortcut. Each key turns one on and names the input (by `reference`, the snake_cased input column name) the extension fills from the page. Omit it to leave the shortcut off every extension.
    - `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`.

## Response `201`

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 cannot back a shortcut yet (`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`: Workflow not found in your organization (`code: "WORKFLOW_NOT_FOUND"`)
- `409`: Conflict — this workflow already has a shortcut (`code: "SHORTCUT_ALREADY_EXISTS"`), or its draft already holds an unpublished `output_shortcut` action (`code: "OUTPUT_NODE_EXISTS"`), which has to be published or removed in the Floqer app first.
- `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)