Archive

What has been put away, and how to get it back.

Deleting a card, an area or a board archives it: the row stays, everything hanging off it stays, and it disappears from every list — the board, the dashboard, search, the reminders. This is where you find it again.

Restoring lives here rather than on each of the three endpoints, because it is one idea and a caller should not have to know which table a thing is in. Permanent removal is the other way round: it stays on DELETE /api/data/card, DELETE /api/data/area and DELETE /api/data/board, asked for with permanent, so the code that knows how to take a card's uploaded files with it stays in one place.

GET /api/data/archive

With a boardId, the areas and cards that board has archived. Without one, the boards this account has archived.

A card archived inside an area is not listed separately: the area is the thing to restore, and it brings its cards back with it.

Parameters

NameTypeRequiredDescription
boardIdintegernoThe board to look inside. Omit it to list archived boards instead.

What comes back

With a boardId — needs edit access on it, the same as archiving did:

FieldTypeDescription
areasarrayEach an id, name, archivedAt, and cardCount: how many cards went with it.
cardsarrayEach an id, name, archivedAt, and the areaName it will return to.

Without one:

FieldTypeDescription
boardsarrayEach an id, name and archivedAt. Only boards this account owns, since only an owner can archive one.
# What this board has put away
curl -X GET "https://boards.example.com/api/data/archive?boardId=123" \
  -H "X-API-Key: $LOKALBOARDS_KEY"

# Archived boards
curl -X GET "https://boards.example.com/api/data/archive" \
  -H "X-API-Key: $LOKALBOARDS_KEY"

const response = await fetch(
  "https://boards.example.com/api/data/archive?boardId=123",
  { headers: { "X-API-Key": apiKey } },
);

if (!response.ok) throw new Error(await response.text());

const { areas, cards } = await response.json();

<script setup>
const config = useRuntimeConfig();

const { data } = await useAsyncData("archive", () =>
  $fetch("https://boards.example.com/api/data/archive", {
    headers: { "X-API-Key": config.lokalBoardsKey },
    query: { boardId: 123 },
  }),
);
</script>

<template>
  <ul>
    <li v-for="area in data?.areas ?? []" :key="area.id">
      {{ area.name }} — {{ area.cardCount }} card(s)
    </li>
    <li v-for="card in data?.cards ?? []" :key="card.id">
      {{ card.name }} — from {{ card.areaName }}
    </li>
  </ul>
</template>

import { useEffect, useState } from "react";

export function Example({ apiKey }) {
  const [archive, setArchive] = useState({ areas: [], cards: [] });

  useEffect(() => {
    fetch("https://boards.example.com/api/data/archive?boardId=123", {
      headers: { "X-API-Key": apiKey },
    })
      .then((response) => response.json())
      .then((data) => setArchive({ areas: data.areas, cards: data.cards }));
  }, [apiKey]);

  return <p>{archive.areas.length + archive.cards.length} archived</p>;
}

<?php

$ch = curl_init('https://boards.example.com/api/data/archive?boardId=123');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
]);

$archive = json_decode(curl_exec($ch), true);
curl_close($ch);

POST /api/data/archive

Puts one thing back. A card or an area needs edit access on its board; a board needs to be yours, since archiving one was yours alone.

Restoring an area brings its cards with it, in the order they were in. Restoring a card whose area is somehow archived brings that area back too — a card cannot return to a column that is not there.

Parameters

NameTypeRequiredDescription
typestringyescard, area or board.
idintegeryesThe id of the thing to restore.

What comes back

FieldTypeDescription
successbooleantrue when it is back.
boardIdintegerThe board it returned to, for a card or an area.
curl -X POST "https://boards.example.com/api/data/archive" \
  -H "X-API-Key: $LOKALBOARDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "card", "id": 501 }'

const response = await fetch("https://boards.example.com/api/data/archive", {
  method: "POST",
  headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
  body: JSON.stringify({ type: "card", id: 501 }),
});

if (!response.ok) throw new Error(await response.text());

<script setup>
const config = useRuntimeConfig();

async function restore(type, id) {
  return await $fetch("https://boards.example.com/api/data/archive", {
    method: "POST",
    headers: { "X-API-Key": config.lokalBoardsKey },
    body: { type, id },
  });
}
</script>

<template>
  <button @click="restore('card', 501)">Restore</button>
</template>

async function restore(apiKey, type, id) {
  const response = await fetch("https://boards.example.com/api/data/archive", {
    method: "POST",
    headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({ type, id }),
  });

  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

<?php

$ch = curl_init('https://boards.example.com/api/data/archive');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'type' => 'card',
    'id' => 501,
]));

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Deleting something for good

Not here. Ask the thing's own endpoint, with permanent:

# a card, with its comments, its attachments and the files behind them
curl -X DELETE "https://boards.example.com/api/data/card" \
  -H "X-API-Key: $LOKALBOARDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cardID": 501, "permanent": true }'

# an area, with every card in it
curl -X DELETE "https://boards.example.com/api/data/area?id=12&boardId=123&permanent=true" \
  -H "X-API-Key: $LOKALBOARDS_KEY"

# a board, with everything on it
curl -X DELETE "https://boards.example.com/api/data/board?id=123&permanent=true" \
  -H "X-API-Key: $LOKALBOARDS_KEY"

None of those can be undone.