Aptly SDK Reference

async function init() {
  const { token, error } = await aptly.requestToken({ version: 2 });

  if (error?.code === 'RATE_LIMITED') {
    setTimeout(init, error.retryAfterMs);
    return;
  }
  if (!token) return;

  const res = await aptly.fetch('/board/' + aptly.config.BOARD_ID + '?page=0');
  const { records } = await res.json();
}

const res  = await aptly.fetch('/board/MY_BOARD_UUID?page=0');
const { data, count, page, pageSize } = await res.json();
// data    — array of card objects for this page
// count   — total matching cards across all pages
// page    — the page number you requested
// pageSize — number of cards per page (default 20, max 1000)

// ✅ Correct — first page
const res = await aptly.fetch('/board/lease?page=0&pageSize=100');

// ❌ Wrong — skips the first 100 records, returns empty if fewer than 100 exist
const res = await aptly.fetch('/board/lease?page=1&pageSize=100');

async function fetchAllCards(boardId) {
  const pageSize = 100;
  let page = 0;
  let allCards = [];

  while (true) {
    const res = await aptly.fetch(`/board/${boardId}?page=${page}&pageSize=${pageSize}`);
    const { data, count } = await res.json();
    allCards = allCards.concat(data);
    if (allCards.length >= count) break;
    page++;
  }

  return allCards;
}

const fields = await aptly.fetch('/schema/MY_BOARD_UUID').then(r => r.json());
// [ { key: 'stage', label: 'Stage', type: 'stage' }, ... ]

const json = { 'Content-Type': 'application/json' };

// Open tasks on a card (filter by priority with `taskPriority: 'high'`)
const { tasks } = await aptly
  .fetch('/tasks/search', {
    method: 'POST',
    headers: json,
    body: JSON.stringify({ aptletInstanceId: cardId, isChecked: false, status: ['notStarted', 'inProgress'] }),
  })
  .then(r => r.json());

// Change status, priority, due date or assignee
await aptly.fetch(`/tasks/${taskId}`, {
  method: 'PUT',
  headers: json,
  body: JSON.stringify({ status: 'inProgress', priority: 'high', dueAt: '2026-11-01T17:00:00Z', assigneeId: userId }),
});

// Close (or skip) every open task on a card in one call
const { updated, failed } = await aptly
  .fetch('/tasks/bulk-update', {
    method: 'POST',
    headers: json,
    body: JSON.stringify({ aptletInstanceId: cardId, update: { archived: true } }),
  })
  .then(r => r.json());

// Assignee picker: the company's users (users:* read scope)
const { data: users } = await aptly.fetch('/users').then(r => r.json());

// Hand off to Aptly's task detail window (email, SMS, calls)
await aptly.openTask({ taskId });

// Same code regardless of what scope the admin chose
const boardId = aptly.config.LEASES_BOARD_ID;

{
  code: 'RATE_LIMITED',
  message: 'Rate limited. Retry in 42 seconds.',
  retryAfterMs: 42000   // milliseconds until the bucket resets
}

async function loadData() {
  const { token, error } = await aptly.requestToken({ version: 2 });

  if (error?.code === 'RATE_LIMITED') {
    console.warn(error.message);
    setTimeout(loadData, error.retryAfterMs ?? 60000);
    return;
  }
  if (!token) {
    console.error('Could not obtain token');
    return;
  }

  const res = await aptly.fetch('/boards/leases/records');
  const data = await res.json();
  // ...
}

https://your-app.repl.co?aptly_token=MY_TOKEN&aptly_config_BOARD_ID=lease&aptly_org_name=Acme

type BoardData = {
  id:      string;                         // board UUID ('lease', 'location', etc.)
  name:    string;                         // display name ('Leases')
  schema:  { key: string; label: string; type: string }[];  // field definitions
  records: object[];                       // first 50 records, keyed by schema field keys
  total:   number;                         // total record count (for pagination)
}

// Schema and records are ready immediately — no fetch needed
const leases = aptly.boards.leases;
if (leases) {
  console.log(leases.name);        // 'Leases'
  console.log(leases.schema);      // [{ key: 'name', label: 'Name', type: 'text' }, ...]
  console.log(leases.records);     // [{ _id: '...', name: 'Unit 1A', stage: 'Active' }, ...]
  console.log(leases.total);       // 847 — fetch more pages if total > 50
}

if (aptly.boards.leases) { /* safe to use */ }

const { id, records, total } = aptly.boards.leases;
// records already has page 0 — fetch additional pages if needed
if (total > records.length) {
  const more = await aptly.fetch('/board/' + id + '?page=1').then(r => r.json());
}

<script>
  window.APTLY_DEV = {
    token: 'MY_DEV_TOKEN',
    boards: {
      // Full object — closest to production
      leases: { id: 'lease', name: 'Leases', schema: [{ key: 'name', label: 'Name', type: 'text' }], records: [], total: 0 },
      // Shorthand UUID string — SDK wraps it automatically
      properties: 'location'
    }
  };
</script>

aptly.startEmulation('MY_DEV_TOKEN', {
  boards: { leases: 'lease' }
});