DevelopersHow to connect an assistantKeys
Reference/Cards/Change

Reorder a list

PUThttps://api.getwerk.ai/api/v1/projects/{projectId}/cards/{cardId}/list/order

Moves one item of a card's list to another place.

The order sent is every item of the list with one of them moved. Refused when the list or the card changed since it was read.

Authorization

AuthorizationheaderRequired

Authorization: Bearer <key> Authentication

Path parameters

projectIdstring, uuidRequired

The project's id.

cardIdstring, uuidRequired

The card's id.

Body

clientRequestIdstring, uuidRequired

An id the caller makes for this request. Sent again with the same request, it returns the first answer and changes nothing twice; sent with a different request, it is refused.

expectedRevisionintegerRequired

The list's revision as last read; when the list changed since, the change is refused.

At least 0
expectedItemVersioninteger

The card's version as last read; when given and the card changed since, the change is refused.

At least 1
orderedIdsarray of strings, uuidRequired

Every item's id in the new order: the list with one item moved.

Up to 100 items

Response

200 The list after the change.

checklistobject

The card's list.

Show properties of checklistHide properties of checklist
revisioninteger

The list's revision, which grows with every change to it; a change to the list sends it as expectedRevision.

At least 0
batchesarray of objects

The sets of items added together in one change.

Default[]
Show properties of batchesHide properties of batches
idstring, uuid

The set's id, which each of its items names as batch.

itemIdstring, uuid

The card's id.

authorIdstring, uuid or null

The person who added the set, or null when no person did.

createdAtstring, date-time

When the set was added.

groupIdstring, uuid

The id of the change that added the set.

itemsarray of objects

The list's items, in their order.

Show properties of itemsHide properties of items
idstring, uuid

The item's id.

positioninteger

The item's place in the list, from 0.

At least 0
batchstring, uuid or null

The id of the set the item was added in, or null when it was added on its own.

Defaultnull
textstring

The item's text, as written.

At least 1 character
translationobject

The text in the reader's language, when it is written in another.

Show properties of translationHide properties of translation
languagestring

The reader's language the text is translated into.

From 2 to 64 characters
stateenum

ready when text holds the translation, pending while it is being made, failed when it could not be made, paused when no plan pays for translations now.

Allowed valuesreadypendingfailedpaused
textstring

The translated text, present once ready.

checkedboolean

True when the item is checked.

checkedAtstring, date-time or null

When the item was checked, or null while it is not.

checkedByobject or null

Who checked the item, or null while it is not checked.

Show properties of checkedByHide properties of checkedBy

One of 3 shapes, told apart by kind:

kinduser
kindenum

user for a person; connector or schedule for a change Werk made without one.

Allowed valuesuser
displayNamestring

The person's name as the project shows it.

At least 1 character
initialsstring

The person's initials, for an avatar with no photo.

isViewerboolean

True when the person is the key's own person.

photoobject

The person's photo, when they have one.

Show properties of photoHide properties of photo
personIdstring, uuid

The person whose photo it is.

versioninteger

The photo's version, which changes with the photo; its read takes it to fetch the current one.

At least 1
viaobject

The connected app or API key the change came through; absent for a change made in Werk's apps.

Show properties of viaHide properties of via
kindenum

connection for an app connected by sign-in, key for an API key.

Allowed valuesconnectionkey
namestring

The app's or the key's name, as Werk shows it.

At least 1 character
verifiedboolean

True when Werk verified the app's identity.

labelstring

The caption Werk shows beside the change, in the reader's language.

At least 1 character
kindconnector
kindenum

user for a person; connector or schedule for a change Werk made without one.

Allowed valuesconnector
labelstring

The name Werk shows for a change made without a person.

At least 1 character
kindschedule
kindenum

user for a person; connector or schedule for a change Werk made without one.

Allowed valuesschedule
labelstring

The name Werk shows for a change made without a person.

At least 1 character
countsobject

The list's items checked and in all.

Show properties of countsHide properties of counts
doneinteger

List items checked.

At least 0
totalinteger

List items in all.

At least 0

Errors

400invalid_queryThe query is not in the form the route takes; the limit is in the unit of the input details.field names (characters for a text, entries for a list, the value for a number).
400invalid_checklist_requestThe list request is not in the form the route takes; the limit is in the unit of the input details.field names (characters for a text, entries for a list, the value for a number).
400empty_textThe text is empty once trimmed.
400text_too_longThe text has more characters than its field holds.
400order_mismatchThe order sent does not hold exactly the list's entries.
401session_revokedThe request carries no session the server holds, or its session has ended.
401session_expiredThe session has expired.
403actor_not_allowedThe signed-in person may not make this change to the card.
403not_permittedThe signed-in person's role, or whose the record is, does not allow this request.
404conversation_not_foundThe project the request names, or its chat, is not one the signed-in person is in.
404item_not_foundThe card the request names, or its list, is not one the signed-in person can see.
409session_changedThe session changed while the request was in flight.
409project_deletedThe project is being deleted.
409project_archivedThe project is archived, so it does not take this request.
409request_conflictThe request id was already used with another request, or the change it asks could not be made to the record it names.
409request_erasedThe request id belongs to a request whose record was erased.
409item_version_conflictThe card changed after the version the request names.
409card_archivedThe card is archived, so it does not take this change.
rate_limitedMore requests of this kind were sent than Werk takes within the time it counts them over.
500server_errorThe server could not complete the request, and it is not known whether a write it holds was made.
curl
curl -X PUT "https://api.getwerk.ai/api/v1/projects/2f6c9e41-7a3b-4d58-9c1e-0b8d4f2a6e73/cards/1a7d3f92-6b4e-4c15-8e2a-9f0c5b7d3e81/list/order" \
  -H "Authorization: Bearer wk_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "clientRequestId": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4f20",
    "expectedRevision": 3,
    "orderedIds": [
      "b5f9d3a7-8c2e-4fa4-b6d8-4a0c2e7f1b39",
      "a4e8c2f6-7b1d-4e93-a5c7-3f9b1d6e0a28"
    ]
  }'
TypeScript
const res = await fetch("https://api.getwerk.ai/api/v1/projects/2f6c9e41-7a3b-4d58-9c1e-0b8d4f2a6e73/cards/1a7d3f92-6b4e-4c15-8e2a-9f0c5b7d3e81/list/order", {
  method: "PUT",
  headers: {
    Authorization: "Bearer wk_key_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientRequestId": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4f20",
    "expectedRevision": 3,
    "orderedIds": [
      "b5f9d3a7-8c2e-4fa4-b6d8-4a0c2e7f1b39",
      "a4e8c2f6-7b1d-4e93-a5c7-3f9b1d6e0a28"
    ]
  }),
});
const answer = await res.json();
200JSON
{
  "checklist": {
    "revision": 4,
    "batches": [
      {
        "id": "c6a0e4b8-9d3f-4ab5-87e9-5b1d3f8a2c40",
        "itemId": "1a7d3f92-6b4e-4c15-8e2a-9f0c5b7d3e81",
        "authorId": "8a2e6c14-3f5d-4b9a-a7e2-61c0d9f4b3e8",
        "createdAt": "2026-11-19T16:10:00.000Z",
        "groupId": "d7b1f5c9-0e4a-4bc6-98fa-6c2e4a9b3d51"
      }
    ],
    "items": [
      {
        "id": "b5f9d3a7-8c2e-4fa4-b6d8-4a0c2e7f1b39",
        "position": 0,
        "batch": "c6a0e4b8-9d3f-4ab5-87e9-5b1d3f8a2c40",
        "text": "Pick up the new cartridge",
        "checked": false,
        "checkedAt": null,
        "checkedBy": null
      },
      {
        "id": "a4e8c2f6-7b1d-4e93-a5c7-3f9b1d6e0a28",
        "position": 1,
        "batch": "c6a0e4b8-9d3f-4ab5-87e9-5b1d3f8a2c40",
        "text": "Shut off the water under the sink",
        "checked": true,
        "checkedAt": "2026-11-19T16:20:00.000Z",
        "checkedBy": {
          "kind": "user",
          "displayName": "Tom Okafor",
          "initials": "TO",
          "isViewer": false
        }
      }
    ],
    "counts": {
      "done": 1,
      "total": 2
    }
  }
}