--- title: "Prepare Harbor Action" method: POST path: "/api/harbors/{harbor_id}/actions/prepare" tags: ["Harbors"] --- # Prepare Harbor Action `POST /api/harbors/{harbor_id}/actions/prepare` ## Request - Base URL: `https://app.polytomic.com` - URL: `https://app.polytomic.com/api/harbors/{harbor_id}/actions/prepare` - Auth: one of: - HTTP bearer - HTTP basic Validate and prepare an enabled action without executing it, returning a server-issued execution identifier. Use a writable scoped credential belonging to this Harbor. An administrator must first enable the destination Connection, operation, and input fields. Select an identity with [List actions](../../../../../api-reference/harbors/actions/list), then inspect its fields with [Describe action](../../../../../api-reference/harbors/actions/describe). Preparation validates and temporarily stores the exact destination, lookup, and input. It returns a server-generated `execution_id` and `expires_at`. You do not supply an execution UUID. Preparation neither performs nor approves a destination mutation. Call [Execute action](../../../../../api-reference/harbors/actions/execute) with only the returned identifier within 15 minutes. Polytomic checks current permissions, provider capabilities, and the saved Connection again at execution. Supply one advertised lookup when `lookup_fields` is nonempty. Otherwise omit `lookup`. Omitted input fields remain unchanged. Explicit `null` requires `nullable: true`. Empty and blank strings follow the advertised constraints. Values are JSON scalars; arrays, nested objects, and type coercion are unsupported. Numbers must use integer JSON notation, without a decimal point or exponent, and lie between -9007199254740991 and 9007199254740991. Preserve opaque IDs as strings. Unknown envelope properties, duplicate keys, invalid Unicode, trailing JSON, and bodies larger than 256 KiB are rejected. ## Lifetime and recovery Prepared arguments are fixed for that identifier. Polytomic removes them when execution is claimed and periodically cleans up expired, unexecuted preparations. Execution receipts and Activity event metadata contain no submitted values. Polytomic retains a separate encrypted copy of the target and submitted values for 90 days from preparation. Only Organization administrators can reveal these details in the audit ledger. MCP receipts do not expose them. This evidence records your request, not a verified before-and-after record state. Preparation alone does not create an execution receipt. If the preparation response is lost, you may prepare again: no destination mutation occurred. Each preparation creates a distinct execution identifier. > ⚠️ Preserve the identifier after execution > > After submitting an execution, use its original `execution_id` to investigate > an uncertain outcome. Do not prepare a replacement action to retry it. Send a new 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. Preparation is recorded as `action.prepared`, with its original actor and execution identifier. Expired, unexecuted preparations are recorded as `action.preparation_expired`. Execution records its own actor and attempt separately. ## 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 - PrepareHarborActionRequest - `connection_id` string, uuid, required: Explicit destination connection ID from action discovery. Must have this action and its submitted fields enabled in this Harbor. - `input` SchemaRecord, required - `lookup` ActionLookup - `field_id` string: Field ID to look the record up by - `value` unknown - `operation_id` string, required: Exact operation_id from action discovery - `schema_id` string, required: Exact schema_id from action discovery ## Response `200` OK - HarborActionPreparationEnvelope - `data` HarborActionPreparation - `execution_id` string, uuid: Execution ID of the prepared action - `expires_at` string, date-time: When the prepared action expires ## Changes - **2026-10-22** `d80b0fdea14e`: 1 breaking, 2 warning, 1 info - the `data` response's property type changed from `object` to no type for status `200` - removed the optional property `data/execution_id` from the response with the `200` status - removed the optional property `data/expires_at` from the response with the `200` status - added `#/components/schemas/HarborActionPreparation` to the `data` response property `allOf` list for the response status `200` - **2026-10-21** `61c2b96f65ba`: 4 breaking, 2 warning - added `#/components/schemas/ActionLookup` to the `lookup` request property `allOf` list - added `#/components/schemas/SchemaRecord` to the `input` request property `allOf` list - the `input` request property type changed from `object` to no type - the `lookup` request property type changed from `object` to no type - …2 more - **2026-09-21** `9c3de87fb285`: 1 info - endpoint added [Operation history](https://skmtc.dev/polytomic/apis/polytomic-api/changes/api/harbors/:harbor_id/actions/prepare/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)