Best Practices

// Backend: both clients are fine
const management = new ApolloManagementClient({ organizationApiKey: process.env.AUI_ORG_API_KEY! });

// Browser: messaging only
const messaging = new ApolloMessagingClient({ publishableKey: 'pk_network_...' });

// Good — module-level singleton
export const apollo = new ApolloMessagingClient({ publishableKey: PK });

// Bad — new client (and token exchange) per call
async function send(text: string) {
  const client = new ApolloMessagingClient({ publishableKey: PK });
  return client.messaging.sendMessage({ user_id, text });
}

import { Apollo, ApolloError, ApolloTimeoutError } from '@aui.io/aui-client';

try {
  await client.agents.getAgent(agentId);
} catch (error) {
  if (error instanceof Apollo.NotFoundError) {
    // handle the specific case
  } else if (error instanceof ApolloTimeoutError) {
    // the request timed out — consider a longer timeoutInSeconds
  } else if (error instanceof ApolloError) {
    // any other API error: statusCode + the error envelope in body
    const body = error.body as { error?: { code?: string; request_id?: string } };
    console.error(error.statusCode, body?.error?.code, body?.error?.request_id);
  } else {
    throw error; // not an API error — don't swallow it
  }
}

// Long-running list over a large window
await client.threads.listThreads({ filters }, { timeoutInSeconds: 120 });

// Don't retry non-idempotent sends more than you must
await client.messaging.sendMessage(request, { maxRetries: 0 });

// Cancelable from the UI
const controller = new AbortController();
await client.messaging.sendMessage(request, { abortSignal: controller.signal });

let page = await client.threads.listThreads({
  filters: { project_id, created: ['2026-07-01T00:00:00Z'] },
  'page[size]': 50,
});

while (page.meta?.has_more) {
  page = await client.threads.listThreads({
    filters: { project_id },
    'page[after]': page.meta.after_cursor!,
  });
}