---
title: "Organise automations in folders"
method: POST
path: "/v1/automations/arrange"
tags: ["Automations"]
---

# Organise automations in folders

`POST /v1/automations/arrange`

## Request

- Base URL: `https://api.banksync.io`
- URL: `https://api.banksync.io/v1/automations/arrange`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

One change to the folders automations sit in, named by `action`: `createFolder`, `updateFolder` (a name, an icon, or both), `move` (an automation or folder to a place among its siblings; `before` names the sibling it goes in front of, null puts it last), `favourite` (a star of the caller’s own), `trashFolder` and `restoreFolder`. A folder in trash takes nothing with it: its contents move up. An automation’s own name, icon, trash and restore are their own operations.

## Headers

- `Idempotency-Key` string: Makes a retry safe: the same key with the same request replays the first answer for 24 hours instead of running twice, and the same key with a different request is a 409 `IDEMPOTENCY_KEY_REUSED`. Refusals a retry can outlive — 408, 409, 423, 425, 429 and every 5xx — are never replayed, so retrying with the same key after the cause clears runs the request.

## Request body

- union
  - object
    - `action` 'createFolder', required
    - `name` string, required
    - `parentId` string, nullable
  - object
    - `action` 'updateFolder', required
    - `folderId` string, required
    - `name` string
    - `icon` string, nullable
  - object
    - `action` 'move', required
    - `id` string, required
    - `parentId` string, nullable, required
    - `before` string, nullable
  - object
    - `action` 'favourite', required
    - `id` string, required
    - `favourite` boolean, required
  - object
    - `action` 'trashFolder', required
    - `folderId` string, required
  - object
    - `action` 'restoreFolder', required
    - `folderId` string, required

## Response `200`

The item changed, and where a move landed

- object
  - `success` true, required
  - `data` object, required
    - `id` string, required
    - `anchor` 'resolved' | 'end' | 'stale'

## Other responses

- `400`: Invalid input, or the draft has blocking findings — `code` names the refusal (`AUTOMATION_BLOCKED_BY_FINDINGS`, `AUTOMATION_SECRET_REFUSED`, …) and `details[]` each finding with its node
- `401`: Unauthorized
- `403`: Forbidden — missing scope, insufficient role, a credential narrowed to some accounts, or a grant the caller does not hold
- `404`: Not found — or automations are not enabled for this workspace
- `409`: Conflict — the draft moved since you read it (`AUTOMATION_VERSION_CONFLICT`), the automation is not published or not active, or a grant does not hold (`AUTOMATION_GRANT_STATE`)
- `429`: The automation’s admission refused the run and does not queue (`AUTOMATION_ADMISSION_REFUSED`, `AUTOMATION_RATE_LIMITED`): `code` names which, and the `Retry-After` header says how many seconds to wait before trying again. A start that queues is a 202, not this.
- `503`: Automations are paused while an incident is worked (`AUTOMATIONS_STOPPED`) or not configured here (`AUTOMATIONS_UNAVAILABLE`): `code` names which, and the `Retry-After` header says how many seconds to wait before retrying

---

[API](https://skmtc.dev/banksync/apis/banksync-api.md) · [All operations](https://skmtc.dev/banksync/apis/banksync-api/llms.txt) · [OpenAPI document](https://skmtc.dev/banksync/apis/banksync-api/revisions/94465f5ee922?raw)