Skip to content

Fold several steps into one text

POST
/v1/settings/steps/merge
curl --request POST \
--url https://beta-api.plune.ai/v1/settings/steps/merge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "ids": [ "6f1c2b3a-0000-4000-8000-0000000000f1" ], "into": "Open the order and choose “Refund”." }'

Every live case carrying any step in ids has that action rewritten to into — the same per-case write as a rename, one transaction, one audit entry per case (D10). into need not exist yet: an existing row of that text is the survivor and keeps its note; else the first of ids is renamed in place. The other rows go with their links. An unknown id is a 404 before anything is written. One call rewrites at most 1 000 cases — counted once each, however many of the steps in ids it carries: more is a 413, refused before anything is written. The custom field values (#1764) of the rows that go are added to the survivor: its own value wins a field both hold, and between the others the earlier in ids wins. When the combination is over the 16 KiB limit the merge is a 409 and nothing is written.

Media type application/json
object
ids
required

The steps that go. Their carriers are rewritten to into.

Array<string>
>= 1 items <= 100 items
into
required

The text every carrier ends up with. An existing step of that text is the survivor; else the first of ids is renamed in place and keeps its description.

string
>= 1 characters <= 1000 characters
Example
{
"ids": [
"6f1c2b3a-0000-4000-8000-0000000000f1"
],
"into": "Open the order and choose “Refund”."
}

The surviving step and how many cases were rewritten

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-0000000000f3",
"step": "Open the order and choose “Refund”.",
"count": 1
},
"affected": 0
}

Invalid body

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

No / invalid token or session

One of ids is not a step of yours

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

The custom values of the rows would not fit the survivor (over the 16 KiB limit); 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