---
title: "Run a custom app action"
method: POST
path: "/api/apps/{id}/actions/{name}"
tags: ["Apps"]
---

# Run a custom app action

`POST /api/apps/{id}/actions/{name}`

Runs the saved script, or creates the agent task, named by the app definition.

## Path parameters

- `id` string, required
- `name` string, required

## Request body

- object
  - `input` object

## Response `200`

Action invoked

- union
  - object
    - `ok` boolean, required
    - `result` unknown
    - `stdout` string, required
    - `error` string
    - `durationMs` number, required
  - object
    - `ok` true, required
    - `taskId` string, required
    - `status` 'backlog' | 'unassigned' | 'offered' | 'reviewing' | 'pending' | 'in_progress' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'superseded', required
  - object
    - `ok` boolean, required
    - `result` object, required
      - `passes` object[], required
        - `model` string, required
        - `source` string, required
        - `connector` 'script' | 'swarm-tasks', required
        - `pulled` number, required
        - `created` number, required
        - `updated` number, required
        - `refreshed` number, required
        - `unchanged` number, required
        - `markedStale` number, required
        - `staleSweepSkipped` boolean
        - `warnings` string[], required
        - `durationMs` number, required
        - `invokedBy` string
        - `error` string
        - `skipped` true
        - `alreadyRunning` true
    - `error` string
    - `durationMs` number, required

## Other responses

- `400` — Invalid action input or stale script reference
- `403` — Permission denied
- `404` — App or action not found
- `409` — App definition needs repair

---

[API](https://skmtc.net/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.net/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/versions/101e7a060651/schema)