post_api_tasks_id_restart

POST

/api/tasks/{id}/restart

const url = 'https://example.com/api/tasks/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/restart';
const options = {
  method: 'POST',
  headers: {
    cookie: 'supacloud_session=<supacloud_session>',
    'Content-Type': 'application/json'
  },
  body: '{"agent_profile_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","agent_type":"example","attachments":["example"],"effort":"example","git_workflow":"example","link_issue_id":"example","link_issue_url":"example","max_subagents":1,"mode":"example","model":"example","prompt":"example","provider":"example","subagents":"example","title":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/api/tasks/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/restart \
  --header 'Content-Type: application/json' \
  --cookie supacloud_session=<supacloud_session> \
  --data '{ "agent_profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "agent_type": "example", "attachments": [ "example" ], "effort": "example", "git_workflow": "example", "link_issue_id": "example", "link_issue_url": "example", "max_subagents": 1, "mode": "example", "model": "example", "prompt": "example", "provider": "example", "subagents": "example", "title": "example" }'

Authorizations

cookie_auth

Parameters

Path Parameters

required

string format: uuid

Task id

Request Body^required

application/json

object

agent_profile_id

Optional agent-profile re-route. Some(Some(id)) sets it, Some(None) clears it, an absent field preserves the current profile. Serde treats an absent key as None and an explicit null as Some(None).

string | null format: uuid

agent_type

string | null

attachments

Array | null

effort

string | null

git_workflow

string | null

link_issue_id

string | null

link_issue_url

string | null

max_subagents

#838 — the per-launch ceiling on CONCURRENT subagents. A provided value is merged onto config.max_subagents; 0 clears it back to inheriting the profile / workspace default; an absent field preserves the existing value. The FE Edit-&-restart panel prefills this from the task config, so without it the edited number was shown and then silently dropped on submit.

NOTE the deliberate divergence from the Tier-A PATCH /tasks/{id}/config, which is deny_unknown_fields and allowlists exactly effort|model|mode|subagents. That route is the LIVE-apply surface: an unknown key there must be refused loudly, because a caller may believe it took effect mid-session. Restart is the re-edit surface — it rebuilds the whole launch, accepts the full override set, and is not deny_unknown_fields, so adding a field here widens the re-edit form without touching what may be changed on a running task.

integer | null format: int64

mode

Axis 2 (mig 272) — the harness-native MODE (build|plan). A provided value is merged onto config.mode for the restarted run (empty clears it); an absent field preserves the existing mode. The FE Edit-&-restart panel sends this when changed.

string | null

model

string | null

prompt

string | null

provider

string | null

subagents

Axis 1 (mig 272) — the decoupled subagent toggle (on|off). A provided value is merged onto config.subagents (empty clears it); an absent field preserves it.

string | null

title

string | null

Example^generated

{
  "agent_profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "agent_type": "example",
  "attachments": [
    "example"
  ],
  "effort": "example",
  "git_workflow": "example",
  "link_issue_id": "example",
  "link_issue_url": "example",
  "max_subagents": 1,
  "mode": "example",
  "model": "example",
  "prompt": "example",
  "provider": "example",
  "subagents": "example",
  "title": "example"
}

Responses

200

Task restarting — returns {status: “restarting”}

application/json

{status: <str>} — the task lifecycle status ack (launch/cancel/restart/intervene/interrupt).

object

status

required

string

Example^generated

{
  "status": "example"
}

400

Structured client error

application/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

401

Authentication required

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

403

Permission denied

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

500

Structured server error

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

post_api_tasks_id_restart

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Examplegenerated

Responses

200

Examplegenerated

400

Example

401

Example

403

Example

500

Example

Request Body^required

Example^generated

Example^generated