---
title: "Submit one bounded action"
method: POST
path: "/v1/actions/{action}"
---

# Submit one bounded action

`POST /v1/actions/{action}`

## Request

- Base URL: `https://actiondock.app`
- URL: `https://actiondock.app/v1/actions/{action}`
- Auth: HTTP bearer

Returns 202 with a durable job. Actions with sideEffect true start as awaiting_approval and execute only after a signed-in workspace owner releases the exact preview in the dashboard; other actions start as queued. integration.execute optionally accepts input.executeBefore, a UTC latest-dispatch timestamp bound to approval; expired writes fail without dispatch and need a new proposal and approval. Already-sent writes may finish later. It also accepts input.ifMatch, a single strong quoted ETag bound to approval and sent as If-Match. A provider 412 fails the job without retry and requires a fresh read and new proposal; the provider must enforce conditional writes. See each action's inputSchema in the action catalog.

## Path parameters

- `action` 'document.analyze' | 'data.extract' | 'data.validate' | 'research.web' | 'integration.fetch' | 'integration.execute' | 'report.create', required

## Headers

- `Idempotency-Key` string

## Request body

- ActionSubmission
  - `input` object, required: Action input validated against the action's inputSchema from GET /v1/actions.
  - `workflowId` string: Shared across related jobs so the owner can inspect the sequence.
  - `workflowName` string
  - `idempotencyKey` string: Alternative to the Idempotency-Key header; the header wins when both are present.

## Response `202`

Job accepted

- Job: Durable job record returned by action submission, job lookup, and the MCP run_action, get_job, and wait_for_job tools.
  - `id` string, uuid, required: Job identifier.
  - `workspaceId` string, uuid, required: Workspace that owns the job.
  - `action` string, required: Catalog action name, for example integration.execute.
  - `workflowId` string, nullable, required: Caller-supplied workflow identifier shared across related jobs.
  - `workflowName` string, nullable, required: Caller-supplied workflow name shown in the dashboard.
  - `status` 'awaiting_approval' | 'queued' | 'running' | 'succeeded' | 'failed' | 'rejected' | 'execution_unknown', required: awaiting_approval, queued, and running are non-terminal; succeeded, failed, rejected, and execution_unknown are terminal. An owner may revoke a queued approval, producing rejected with both approval and rejection evidence.
  - `input` object, required: Validated action input exactly as submitted.
  - `output` unknown, required
  - `error` string, nullable, required: Failure, execution_unknown or queued approval revocation explanation; null otherwise.
  - `sideEffect` boolean, required: True when the action writes to an external system and therefore required owner approval.
  - `idempotencyKey` string, nullable, required: Idempotency key that deduplicates this submission within the workspace.
  - `approvedAt` string, date-time, nullable, required: When a signed-in workspace owner released the write.
  - `approvedBy` string, nullable, required: Owner who approved the write.
  - `rejectedAt` string, date-time, nullable, required: When a signed-in workspace owner rejected the write.
  - `rejectedBy` string, nullable, required: Owner who rejected the write.
  - `createdAt` string, date-time, required: Creation time.
  - `updatedAt` string, date-time, required: Last status change.

## Other responses

- `400`: Action input is invalid (invalid_action_input).
- `401`: Missing, invalid, or revoked workspace API key.
- `402`: Subscription or processing limit blocks new work.
- `404`: Resource not found or outside the caller's workspace.
- `409`: Idempotency key was already used for a different request (idempotency_conflict).
- `429`: Rate limit exceeded (rate_limit_exceeded).

---

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