Prepare Harbor Action

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, then inspect its fields with Describe action.

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 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.