---
title: "Execute Harbor Action"
method: POST
path: "/api/harbors/{harbor_id}/actions/execute"
tags: ["Harbors"]
---

# Execute Harbor Action

`POST /api/harbors/{harbor_id}/actions/execute`

## Request

- Base URL: `https://app.polytomic.com`
- URL: `https://app.polytomic.com/api/harbors/{harbor_id}/actions/execute`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

Execute a prepared action with at most one application attempt per server-issued execution identifier.

First call [Prepare action](../../../../../api-reference/harbors/actions/prepare). Submit only
its server-issued `execution_id` using a writable scoped credential belonging to
the same Harbor. The destination, operation, lookup, and input are fixed by
preparation. No per-request approval is required.

Polytomic checks current grants, provider capabilities, and the saved Connection
again before execution. Preparation does not reserve permission. An expired
preparation cannot start an execution. It returns `410 Gone` while the expired
preparation remains available, or `404 Not Found` after cleanup.

> 🚧 Updates can overwrite intervening edits
>
> Enabled operations can act on records accessible through the saved Connection
> and may trigger provider automation. Preparation does not lock the destination
> record. Action permission does not grant read access.

## One intended attempt

An identifier already claimed for execution returns its original receipt,
including through another eligible credential or after action disablement.
Receipts remain available after prepared arguments are removed or expire.
They are retained independently of Activity history.

An `action.attempt_started` event means permission to attempt the action was
claimed, not that the provider received it. Disabling actions blocks new claims
but does not recall an accepted attempt. This is at most one application attempt
per execution identifier, not a remote exactly-once guarantee. Advertised remote
idempotency does not authorize automatic replay.

## Results and recovery

Keep `execution_id` and the returned `status_path`. `succeeded` means the provider
confirmed the operation and Polytomic recorded that outcome. `failed` means the
operation was rejected. `executing` is incomplete. `recovery_required: true`
does not confirm durable acceptance or completion. Use the status path after a
timeout or server error. A missing receipt does not prove no operation occurred.

> ⚠️ An unknown outcome is terminal
>
> `unknown` means the operation may have happened. Investigate the record and
> provider automation. Do not resubmit or prepare a replacement action to retry.
> Polytomic never automatically retries an uncertain attempt. An overdue
> executing receipt becomes unknown after its 90-second deadline.

Send a separate nonzero UUID in `X-Polytomic-Activity-Request-ID` for each HTTP
request. MCP supplies this transport header automatically.
`X-Polytomic-Harbor-Session` is optional for direct REST requests; a supplied
session must be active and bound to your credential and Harbor. Receipts and
Activity contain operation identity, lookup field names, submitted field names,
original attribution, and safe outcome categories. They exclude lookup values,
input values, output payloads, and raw provider errors.

## Path parameters

- `harbor_id` string, uuid, required: Unique identifier of the Harbor

## Headers

- `X-Polytomic-Version` string
- `X-Polytomic-Harbor-Session` string: Harbor session token; when supplied, the session must be active and bound to this credential and Harbor.
- `X-Polytomic-Activity-Request-ID` string: New nonzero UUID for each request, required for scoped credentials; a reused value is rejected.

## Request body

- ExecuteHarborActionRequest
  - `execution_id` string, uuid, required: Server-issued identifier returned by prepare. Preserve it for status recovery; never prepare a replacement to retry uncertainty.

## Response `200`

OK

- HarborActionExecutionEnvelope
  - `data` HarborActionExecutionResponse
    - `connection_id` string, uuid: Connection ID of the action
    - `credential_id` string, uuid: Original credential attribution, including when another credential submits a duplicate
    - `deadline_at` string, date-time: When an unfinished execution becomes unknown
    - `execution_id` string, uuid: Action execution ID
    - `failure_category` string: Category of a failed or unknown outcome
    - `field_ids` string[], nullable: Submitted field names only, never their values
    - `finished_at` string, date-time, nullable: When the execution reached its final status
    - `lookup_field_id` string: Lookup field ID used to find the target record
    - `operation_id` string: Operation ID of the action
    - `recovery_required` boolean: True when receipt persistence was interrupted or uncertain. Inspect status; this response does not confirm durable acceptance or completion.
    - `schema_id` string: Schema ID of the action
    - `started_at` string, date-time: When the execution started
    - `status` 'executing' | 'succeeded' | 'failed' | 'unknown': Current execution status
    - `status_path` string: API path for reading this execution receipt

## Changes

- **2026-10-22** `d80b0fdea14e`: 1 breaking, 14 warning, 1 info
  - the `data` response's property type changed from `object` to no type for status `200`
  - removed the optional property `data/connection_id` from the response with the `200` status
  - removed the optional property `data/credential_id` from the response with the `200` status
  - removed the optional property `data/deadline_at` from the response with the `200` status
  - …12 more
- **2026-09-21** `9c3de87fb285`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/polytomic/apis/polytomic-api/changes/api/harbors/:harbor_id/actions/execute/post.md)

---

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