Rename a step in every case that carries it, or change its note
const url = 'https://beta-api.plune.ai/v1/settings/steps/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"step":"Sign in as the shop owner."}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”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
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 note — no case is touched
{ "description": "The owner account of the demo shop; its credentials are in the team vault."}Responses
Section titled “ Responses ”The step as it is now, and how many cases followed
object
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
The action, trimmed. Unique within the project, case-sensitively.
A note for the author — what the step means, how to do it. Absent when there is none.
Live cases carrying the step. 0 for a step made by hand that no case uses yet, or orphaned by an edit.
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
Cases whose steps were rewritten — each got a version bump and an audit entry.
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.
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
object
Example generated
{ "error": "example"}No / invalid token or session
No such step in your projects
object
Example generated
{ "error": "example"}A rename onto an existing step whose custom values would not fit together; nothing was written
object
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.)
The refusal of a rename or a merge of steps or tags that would rewrite more cases than one call may (#1142).
object
How many cases it would take, the ceiling, and what to do about it.
The cases the call would rewrite — each once, whichever of the steps or tags it carries.
The most cases one call rewrites.
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.
object
Example generated
{ "error": "example"}Headers
Section titled “Headers ”Seconds until the window rolls over