---
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` 'draft' | '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

## Changes

- **2026-08-31** `6f2d2fbe2599` — 1 warning
  - added the new `draft` enum value to the `anyOf[subschema #2]/status` response property for the response status `200`
- **2026-08-07** `0375890be8c4` — 1 info
  - added `subschema #3` to the response body `anyOf` list for the response status `200`
- **2026-08-07** `06cac6a7c5bc` — 5 info
  - added the media type `application/json` for the response with the status `200`
  - added the media type `application/json` for the response with the status `400`
  - added the media type `application/json` for the response with the status `403`
  - added the media type `application/json` for the response with the status `404`
  - …1 more
- **2026-08-05** `2ecf536b66f2` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/apps/:id/actions/:name/post.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/revisions/6b1a7f0876b9/schema)