LLM Context Reference

aptly.token           string|null         current delegate token
aptly.org             {id, name}          logged-in user's org
aptly.user            {id, email,         logged-in user
                       firstName, lastName,
                       phone, role, teams}
aptly.config          object              merged admin config — read any key directly
aptly.board           {id, schema}|null   board context; null unless board-tab embed
aptly.boards          object|null         prefetched standard boards (marketplace apps)
aptly.actions         string[]            action IDs admin enabled for this app (may be empty)

opts undefined  → Promise<string|null>                        v1, backward compat
opts {version:2} → Promise<{token:string|null, error:TokenError|null}>  v2, preferred

TokenError: { code: string, message: string, retryAfterMs: number|null }
Error codes: 'RATE_LIMITED' | 'TOKEN_ERROR'

→ Promise<Response>
Auth-aware. Prepends API base URL. Auto-retries once on 401.
path example: '/board/UUID?page=0'
Do NOT set Authorization header manually.

→ Promise<window.aptly>
Dev/test only. token = long-lived dev token from Settings → Profile → Developer Tools.
opts: { config: {}, org: {}, user: {}, boards: {} }
Ignored when running inside Aptly iframe.

→ Promise<{ success: boolean, error?: string }>
Raw action dispatcher. actionId must be in aptly.actions or returns { success: false, error: 'Not permitted' }.
Timeout after 3s → { success: false, error: 'timeout' }.

aptly.openCardPane({ cardId: string })                 // in a board: board side panel; elsewhere: fullscreen modal
aptly.openCardView({ cardId: string })                 // always a fullscreen modal
aptly.startDialer({ number: string, name?: string })   // number: E.164 recommended, not validated
aptly.openEmailComposer({ to?: string|string[]|{value:string,label:string}[], subject?: string, content?: string /* HTML */, composeMode?: 'email'|'sms', aptletInstanceId?: string, applicationId?: string })
aptly.openSMSComposer({ to?: string|string[]|{value:string,label:string}[] /* phone numbers */, subject?: string /* window title only */, content?: string /* plain text, max 1600 */, composeMode?: 'sms'|'email', aptletInstanceId?: string, applicationId?: string })
aptly.createEvent({ recipients?: { value: string /* email */, label: string /* name */ }[], date?: ISO-8601 /* accepted, currently not applied */, comments?: string /* accepted, currently not applied */ })
aptly.createCard({ boardId: string /* board UUID */, fields?: { name?: string, [fieldUuid: string]: any } /* board pages only; ignored on the dashboard */ })
aptly.createTask({ title?: string, dueAt?: ISO-8601, priority?: 'asap'|'high'|'medium'|'low' /* default 'low' */, activityLogType?: 'todo'|'email'|'sms'|'voice' /* default 'todo' */, note?: string, assigneeId?: string /* default: current user */, aptletInstanceId?: string, aptletUuid?: string })
aptly.createContact({ firstname?: string, lastname?: string, phone?: string|{type:string,number:string}[], email?: string, company?: string, title?: string })
aptly.navigateToContact({ contactId: string })
aptly.openConversation({ streamId: string /* non-empty, required */, title?: string })
aptly.openTask({ taskId: string /* non-empty, required; task detail with email, SMS and call actions */ })

Composer `to`: one string, an array of strings, or an array of { value, label }. Email addresses in
  email mode, phone numbers in sms mode. openSMSComposer defaults composeMode to 'sms'; openEmailComposer to 'email'.
createCard outside a board or the dashboard does nothing (still resolves success: true).
Email draft text must be passed as content, with subject for the subject line; displaying it in chat does not prefill the composer. Hiro replaces a blank contact-email button when it requests a populated draft, including after a resumed run.
createEvent recipients must be { value, label }, not { email, name }.
Full field detail, per-action behavior and caveats: /embed-actions

All return Promise<{ success: boolean, error?: string }>. success: true means dispatched, not completed.
An action only fires if its ID is in the embed's allowedActions (aptly.actions);
otherwise it resolves { success: false, error: 'Not permitted' }.
Other errors: 'timeout' (no reply in 3s), 'not-in-iframe'. openConversation without a string streamId, or openTask without a string taskId, resolves success: false.

<head>
  <script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>
</head>
<body>
  <script>
    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 boardId = aptly.config.BOARD_ID;
      const res = await aptly.fetch('/board/' + boardId + '?page=0');
      const { records } = await res.json();
      // render records
    }

    init();
  </script>
</body>

<script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>
<script>
  aptly.startEmulation('PASTE_DEV_TOKEN_HERE', {
    config: { BOARD_ID: 'lease' }
  }).then(init);
</script>

<script>
  window.APTLY_DEV = {
    token: 'your-api-key',
    config: { BOARD_ID: 'lease' },
    org:   { id: 'company-id', name: 'Acme' },
    user:  { email: '[email protected]', firstName: 'Dev' }
  };
</script>
<script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>

?aptly_token=KEY&aptly_config_BOARD_ID=lease&aptly_org_name=Acme

60 token requests / 60s / browser connection (not per user)
Error code: 'RATE_LIMITED'
retryAfterMs: ms until bucket resets

contextScope 'company'  one config per org                       default
contextScope 'board'    one config per board
contextScope 'user'     one config per user
contextScope 'all'      all three; user > board > company merge

Read scopes:  boards:*, contacts:*, knowledge:*
Write scopes: boards:*
Declared on app definition. Enforced by core-api.
403 = valid token, missing scope.

400  —                 missing required field
400  INVALID_DATA      bad scope format
401  INVALID_ACCESS_TOKEN  expired / wrong company
401  UNAUTHORIZED      user/app not found or revoked
403  FORBIDDEN         valid token, missing scope
429  RATE_LIMITED      too many token requests; retryAfterMs in error object