Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Quick start

Add one script tag to your HTML <head>: 
<script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>
After it loads, window.aptly is ready: 
// Auth-aware fetch — handles the token, auto-retries on 401, prepends the API base URL
const res  = await aptly.fetch('/board/MY_BOARD_ID?page=0');
const data = await res.json();

// Context delivered by Aptly
aptly.org.id          // companyId of the logged-in user's org
aptly.org.name        // org display name
aptly.user.email      // logged-in user's email
aptly.user.firstName
aptly.config          // admin-declared config variables (see Config variables below)
For the full list of aptly.* properties and methods, see the SDK Reference.

​
Enable the SDK for your app

Open the board view settings for the tab that contains your app (or the dashboard panel), and toggle on Needs Aptly Context. This tells Aptly to deliver a delegate token and context to your app on each load.

​
Config variables

Config variables let users configure your app with friendly pickers — board selectors, text fields, toggles — rather than pasting raw IDs. Admins declare them in the app store admin panel; users fill them in during install. 
// Read a config variable declared by the admin
const boardId   = aptly.config.LEASES_BOARD_ID;
const threshold = aptly.config.OVERDUE_THRESHOLD ?? 30;
aptly.config is the fully merged configuration for the current context. If the app supports board-level or user-level config, Aptly handles the merge before delivering context — your code always reads the same flat object. See Config scoping for how merge priority works.

​
Testing outside Aptly

When you’re building in Replit preview, running locally, or developing before the app is embedded, you need to simulate the context Aptly would deliver. Three options: An Aptly admin generates a long-lived developer token in Global Admin → [Company] → Dev Tokens. Paste it into your app: 
<script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>
<script>
  aptly.startEmulation('LONG_EXPIRY_TOKEN_FROM_GA', {
    config: { LEASES_BOARD_ID: 'lease' }  // optional config overrides
  });
</script>
startEmulation verifies the token against the Aptly API to get real user and org identity, then populates window.aptly exactly as if Aptly had delivered the context via postMessage — same scopes, same user. Tokens can be issued with up to 7-day expiry so you won’t need to regenerate constantly.

​
Option B — window.APTLY_DEV block

Set values directly — useful for mocking specific config without a token: 
<script>
  window.APTLY_DEV = {
    token:  'your-api-key',
    config: { LEASES_BOARD_ID: 'lease' },
    org:    { id: 'your-company-id', name: 'My Company' },
    user:   { email: '[email protected]', firstName: 'Dev' }
  };
</script>
<script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>

​
Option C — URL params

https://your-app.repl.co?aptly_token=MY_TOKEN&aptly_config_BOARD_ID=lease
See the SDK Reference for the full list of supported params.
When running inside Aptly (embedded iframe), the SDK ignores all dev options — the real postMessage context always takes priority.

​
UI operations

aptly.ui lets your app trigger actions in the parent Aptly window. All methods post a message that Aptly intercepts and handles. They are no-ops (with a console warning) when the app runs outside Aptly. 
// Open the composer pre-addressed
aptly.ui.openComposer({ to: ['[email protected]'], subject: 'Lease renewal' });

// Create a card on a board
aptly.ui.createCard('my-board-uuid', { 'Title': 'Follow-up call', 'Stage': 'Active' });

// Navigate to a different section of Aptly
aptly.ui.navigate('/inbox/mine');

​
Examples

Each option below shows exactly where to place the dev-testing code relative to the SDK script tag. The init() function and app body are the same in all three — only the testing shim changes. Get a long-lived dev token from Global Admin → [Company] → Dev Tokens, then call startEmulation after the SDK loads. Remove the emulation block before deploying. 
<head>
  <!-- Aptly SDK -->
  <script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>

  <!-- DEV ONLY: remove before deploy -->
  <script>
    aptly.startEmulation('PASTE_DEV_TOKEN_HERE', {
      config: { BOARD_ID: 'my-board' }
    }).then(init);
  </script>
</head>
<body>
  <script>
    // In production, Aptly calls init() after delivering context via postMessage.
    // startEmulation() calls it here during local dev.
    async function init() {
      const boardId = aptly.config.BOARD_ID;
      const res  = await aptly.fetch('/board/' + boardId + '?page=0');
      const data = await res.json();
      console.log('Loaded', data.length, 'records for', aptly.org.name);
    }
  </script>
</body>

​
Option B — window.APTLY_DEV block

Set the dev block before the SDK tag so the SDK picks it up on load. Remove before deploy. 
<head>
  <!-- DEV ONLY: remove before deploy -->
  <script>
    window.APTLY_DEV = {
      token:  'YOUR_API_KEY',
      config: { BOARD_ID: 'my-board' },
      org:    { id: 'your-company-id', name: 'Acme' },
      user:   { email: '[email protected]', firstName: 'Dev' }
    };
  </script>

  <!-- Aptly SDK — reads APTLY_DEV on load -->
  <script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>
</head>
<body>
  <script>
    async function init() {
      const boardId = aptly.config.BOARD_ID;
      // ...
    }
    init();
  </script>
</body>

​
Option C — URL params

No code changes needed. Append params to the URL when opening your app. Nothing to remove before deploy. 
https://your-app.repl.co?aptly_token=MY_TOKEN&aptly_config_BOARD_ID=my-board&aptly_org_name=Acme

<head>
  <!-- Aptly SDK — picks up aptly_* params from the URL automatically -->
  <script src="https://preview.getaptly.com/api/ai/app-builder/sdk.js"></script>
</head>
<body>
  <script>
    async function init() {
      const boardId = aptly.config.BOARD_ID;
      // ...
    }
    init();
  </script>
</body>

​
Next steps

  • SDK Reference — full window.aptly API, config scoping, URL params
  • Delegate Tokens — raw token exchange API for server-side integrations and AI agents