Configure Reference

Configure is the public TypeScript SDK client.

import { Configure } from "configure";

const configure = new Configure({
  apiKey: process.env.CONFIGURE_API_KEY!,
  agent: "your-agent",
});

Constructor

new Configure(options: ConfigureOptions)

ConfigureOptions:

Field	Type	Required in type	How it is resolved
apiKey	string	no	Server-side Configure secret key. Falls back to CONFIGURE_API_KEY; construction fails if neither is set.
agent	string	no	Public agent handle. Falls back to CONFIGURE_AGENT; construction fails if neither is set or validation fails.
externalId	string	no	Default app-local user ID for unlinked developer-scoped profile operations.
timeout	number	no	Request timeout in milliseconds. No default: when unset, requests never time out. When set, the SDK aborts the request after that many milliseconds and throws TIMEOUT.
fetch	typeof fetch	no	Custom fetch implementation for runtimes without native fetch. Defaults to globalThis.fetch; construction fails if no fetch implementation exists.
baseUrl	string	no	Advanced override for local/staging development. Falls back to CONFIGURE_BASE_URL, then https://api.configure.dev. An explicit baseUrl wins over the env var.

The constructor fails synchronously with a ConfigureError: API_KEY_MISSING when no API key resolves, and INVALID_INPUT when the agent handle is missing or invalid, or when no fetch implementation exists.

Do not expose secret keys in browser code. Browser flows should use Configure UI components and publishable keys.

Agent Handle Rules

The agent handle is the one public identifier for an agent, similar to a social username.

• Lowercase letters, numbers, and hyphens only.
• 2 to 63 characters.
• Starts and ends with a letter or number.
• Reserved names are rejected. Reserved names include docs, api, www, app, admin, dashboard, status, blog, mcp, v1, auth, profile, tools, connectors, web, memory, and internal demo handles.

Invalid or reserved handles throw ConfigureError with code INVALID_INPUT.

Profile objects

Create a per-user profile object with configure.profile().

const profile = configure.profile({ token });

token is the agent-scoped bearer token from Configure Link or an auth flow for a linked user. See Auth Flows.

The profile object owns reads, memory search, explicit remembers, targeted forgets, bounded conversation commits, model tool definitions, and tool execution.

For app-local unlinked users, use configure.profile({ externalId: "customer-123" }).

Identity resolves in a fixed order. A token wins outright. Without a token, the call's externalId wins, then the constructor's externalId. With a constructor externalId, configure.profile() with no arguments works:

const configure = new Configure({ apiKey, agent, externalId: "customer-123" });
const profile = configure.profile();

When nothing resolves, the first profile request (read, search, remember, forget, or commit) throws ConfigureError with code INVALID_INPUT. The configure.profile() call itself does not validate; do not rely on it to fail fast.

Bulk Import

Create historical/onboarding backfill jobs with configure.importProfiles().

const job = await configure.importProfiles({
  mode: "backfill",
  users: [
    {
      externalId: "customer-123",
      profile: { preferences: ["Prefers concise replies."] },
    },
  ],
});

const status = await configure.importJobs.get(job.id);

importProfiles() and importJobs.get() both return an ImportJob. Key fields: id, mode (only "backfill"), status ("queued" | "processing" | "completed" | "failed" | "cancelled"), accepted_profiles, processed_profile_count, failed_profile_count, imported_memory_count, plus optional quota and caps. See Import Types for the full shape.

Import is server-side and secret-key only. It is separate from profile.commit() and is not exposed through profile.tools().