---
title: "Restart workflow record from top"
method: POST
path: "/api/workflow-records/{sid}/restart"
tags: ["workflow_records"]
---

# Restart workflow record from top

`POST /api/workflow-records/{sid}/restart`

## Request

- Base URL: `https://beta.getsales.io/playtables/v1`
- URL: `https://beta.getsales.io/playtables/v1/api/workflow-records/{sid}/restart`
- Auth: HTTP bearer and API key in header `Team-SID`

Start one person's journey over: open tasks are cancelled, the version and sender profile pinned again, the step reset, the first task planned now. From any status the person gate does not hold, finished or in flight. Refusals: a row the gate holds is 409 (exit is its verb); a stoplisted or duplicate person 409 conflict; an archived or unpublished workflow 409; a sender profile outside the pool 422. Every call is another restart.

Contract:
- MCP tool `restart_workflow_record`, registry package `mcp.playtables/workflow_records`, mount `playtables.journeys`.
- Operation `action`, response envelope `action`.
- Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.

## Path parameters

- `sid` string, required: Workflow record sid (wf_rc_…).

## Request body

- RestartWorkflowRecordRequest: Request body of `restart_workflow_record`.
  - `mode` 'from_start' | 'from_current': from_start (default): the journey begins at the published version's entry step. from_current: it keeps the step it is on (the entry when the published version no longer has that step).
  - `sender_profile_sid` string: An explicit sender profile for the restarted journey; it must be in the workflow's sender pool (422 otherwise). Absent = the workflow's rotation strategy picks again.
  - `reason` string: Free-form; stored in the workflow_restarted activity and the log only - not on the row.

## Response `200`

`action` success envelope.

- RestartWorkflowRecordResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` object, nullable, required
    - `sid` string, required
    - `team_sid` string, required
    - `workflow_sid` string, required: wf_wf_… owning workflow; DB-UNIQUE together with people_sid - one row per (workflow, person) pair, forever - see ./workflows.md.
    - `workflow_version_sid` string, required: wf_vr_… version pinned at enrollment - the record executes that step graph even after newer publishes - see ./workflow_versions.md.
    - `people_sid` string, required: cr_pp_… the enrolled person; second half of the DB-UNIQUE pair - see ./people.md.
    - `entered_via_source_sid` string, required: wf_sr_… entry point that produced the row (immutable audit) - see ./workflow_sources.md.
    - `sender_profile_sid` string, nullable, required: ub_sp_… sender pinned at enrollment; null when the version has no send steps; re-resolved at next dispatch if the profile is deleted - see ./sender_profiles.md.
    - `current_step_id` number, required: Small int step id inside the pinned version steps JSON (server-assigned, immutable, never reused) - a JSON node pointer, not a sid or row.
    - `status` 'waiting_limit' | 'blocked' | 'active' | 'waiting' | 'paused_on_reply' | 'paused_manual' | 'paused_blocked' | 'failed' | 'completed' | 'exited', required
    - `entered_at` string, nullable, required
    - `touches_done` integer, required
    - `rotations_done` integer, required
    - `error_code` string, nullable, required: Machine code of the last failure, from the failing task result (max 64).
    - `error_message` string, nullable, required: Human-readable detail of the last failure (max 1024).
    - `last_touch_at` string, required: ISO 8601 UTC - last step advance or status change; the staleness clock.
    - `finished_at` string, nullable, required: ISO 8601 UTC - stamped once when status enters a terminal state; null while live.
    - `created_by` object, required
      - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required
      - `actor_sid` string, nullable, required
      - `team_sid` string, required
      - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job.
      - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path.
      - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise.
      - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract.
      - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write.
      - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row.
    - `created_at` string, required
    - `updated_at` string, required
    - `deleted_at` string, nullable, required
  - `result` object, required
    - `restarted_from` string, required: The status the journey had before the restart (completed, exited, failed, active, waiting, paused_on_reply, paused_manual).
    - `cancelled_tasks_count` integer, required: pending/scheduled tasks of this record cancelled in the same transaction before the first step was planned again.
    - `re_entered_count` integer, required: How many times this journey has been started over in all, this one included.
    - `current_step_id` integer, required: The step the journey stands on now: the entry step, or the kept one on from_current.
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/revisions/aa394506515d?raw)