Skip to content

Rename a step in every case that carries it, or change its note

PATCH
/v1/settings/steps/{id}
curl --request PATCH \
--url https://beta-api.plune.ai/v1/settings/steps/example \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "step": "Sign in as the shop owner." }'

A new step is written into the action of every live case carrying the old one — one transaction, each case gets its own audit entry with the reason and a version bump (D10). When the new text already exists the rename is a merge into that row: merged: true and step.id is the survivor’s. A description alone touches only the row. A case edited between the read and this write keeps what its form saved and is skipped; its link is rebuilt on its next save. A rename of a step that more than 1 000 cases carry is a 413, refused before anything is written; a description alone touches no case and is never refused for it.

id
required
string
Media type application/json

A new text, a description, custom field values, or any of them. description: null removes the note. An empty object is refused (400). A refused custom leaves the step as it was, a rename included.

object
step
string
>= 1 characters <= 1000 characters
description
string
nullable <= 16384 characters
custom

Custom field values to change (#1764): a key sets it, null clears it, a key left out keeps its value. Written to the step that is left after a rename or merge. A rename onto an existing step also folds the values of the renamed row into it, as a merge does (409 when they do not fit).

object
Examples

The text — every carrier follows

{
"step": "Sign in as the shop owner."
}

The step as it is now, and how many cases followed

Media type application/json
object
step
required

One row of the Steps Database: the text of an action as manual cases carry it, with how many live cases carry it. Rows are written on every save of a manual case — each * line under ## Steps becomes one — and by hand here.

object
id
required
string format: uuid
step
required

The action, trimmed. Unique within the project, case-sensitively.

string
>= 1 characters <= 1000 characters
description

A note for the author — what the step means, how to do it. Absent when there is none.

string
count
required

Live cases carrying the step. 0 for a step made by hand that no case uses yet, or orphaned by an edit.

integer
custom

Values of the project’s step fields (#1764), field id → value. They belong to the dictionary step - one per text of a step in the project - and are not in the body of any case that carries it. Absent while there are none.

object
affected
required

Cases whose steps were rewritten — each got a version bump and an audit entry.

integer
merged

On a rename only: true when the new text already existed, so the step was folded into that row and step.id is the survivor’s, not the one patched.

boolean
Example
{
"step": {
"id": "6f1c2b3a-0000-4000-8000-0000000000f1",
"step": "Sign in as the shop owner.",
"description": "The owner account of the demo shop; its credentials are in the team vault.",
"count": 0
},
"affected": 0
}

Invalid body, or nothing to change

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No / invalid token or session

No such step in your projects

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

A rename onto an existing step whose custom values would not fit together; nothing was written

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

The rename or merge would rewrite more cases than one call may (limit, 1 000), and nothing was written. carriers is how many it would take: the distinct cases that carry any of the steps or tags named, each counted once. Asking again changes nothing until carriers is down to limit, and there is no batched rewrite to ask for instead — the sentence in error says what to do: edit some of those cases yourself to carry the new step or tag, then call again for the rest. (A body over the size limit of the API is also a 413; it is answered before the route and carries error alone.)

Media type application/json

The refusal of a rename or a merge of steps or tags that would rewrite more cases than one call may (#1142).

object
error
required

How many cases it would take, the ceiling, and what to do about it.

string
carriers
required

The cases the call would rewrite — each once, whichever of the steps or tags it carries.

integer
>= 1
limit
required

The most cases one call rewrites.

integer
>= 1
Example
{
"error": "1001 cases would be rewritten, and one rename or merge of tags rewrites at most 1000. Edit some of those cases yourself to carry the new tag, then run it again for the rest.",
"carriers": 1001,
"limit": 1000
}

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}
Retry-After
integer

Seconds until the window rolls over