---
search:
  tags:
    - Actions
    - POST
seo:
  description: >-
    Execute an enabled action inline, or park it behind a human approval when
    the… Reference for the POST /api/v2/actions/{ref}/invoke endpoint in the
    Anlyon API.
sidebar:
  label: Invoke an action
  badge: POST
title: Invoke an action
type: openapi-operation
---
Execute an enabled action inline, or park it behind a human approval when the action is gated.
Which definition runs depends on how the call is attributed. Passing a `runId` whose run names an agent runs the action version that agent's published version pins, if it pins one -- this is the path a rollback restores. Without a `runId`, or when the agent pins nothing for this action, the action's current definition runs. The response reports the version that actually executed as `actionVersionId`.
With an `Idempotency-Key`, the key is also recorded on the invocation and kept for its whole life, including after it fails. A retry with the same key after the 24-hour replay window (or after the replay store loses the key) is answered from the invocation's current state with `X-Idempotent-Replay: current-state` and `200`, or `202` while it still waits for approval. It is never executed, admitted or charged again. The same key from a different credential or with a different body returns `409 idempotency_key_reuse`. A request refused before the invocation is recorded (for example invalid input) leaves the key unused. To run the action again deliberately, use a new key.

`POST /api/v2/actions/{ref}/invoke`