Types Reference

The TypeScript SDK exports the public PR1 runtime types from configure.

ConfigureOptions

type ConfigureOptions = {
  apiKey?: string;
  agent?: string;
  externalId?: string;
  timeout?: number;
  fetch?: typeof fetch;
  baseUrl?: string;
};

All fields are optional in the type because the constructor can resolve apiKey from CONFIGURE_API_KEY and agent from CONFIGURE_AGENT. At runtime, construction still fails if no API key or agent handle can be resolved.

externalId is an optional default app-local user identifier for unlinked profiles. When set, profile and file operations use it unless a runtime handle supplies another externalId. Connector and web utility operations require the agent-scoped token returned by Configure.link(); they do not use externalId.

baseUrl is an advanced override for local or staging development. Do not include it in normal production snippets.

Agent Handles

agent is the public agent handle. The SDK validates it before sending requests:

• Lowercase letters, numbers, and hyphens only.
• 2 to 63 characters.
• Starts and ends with a letter or number.
• Reserved handles are rejected.

ProfileRuntimeOptions

type ProfileRuntimeOptions = {
  token?: string;
  externalId?: string;
};

Use token for a linked Configure user. Use externalId without token for a developer-scoped app-local user. externalId is the developer's ID, not a Configure-generated user ID.

ProfileReadOptions

type ProfileReadOptions = {
  sections?: Array<"identity" | "preferences" | "integrations" | "imports" | "agents" | "summary">;
};

imports contains user-directed ChatGPT, Claude, Gemini, Grok, or other memory imports. integrations contains connected tools such as Gmail, Calendar, Drive, and Notion.

ProfileSearchOptions

type ProfileSearchOptions = {
  query?: string;
  source?: string;
  from?: string;
  to?: string;
  limit?: number;
  detail?: "compact" | "full";
};

Search returns ranked attributed profile data scoped by user and agent permissions. Omit query or pass query: "*" to list bounded permitted results. Compact hits include source attribution and omit raw CFS paths/provenance; full detail includes safe path, marker, provenance, and update metadata.

Imported memory hits use sources such as import:chatgpt. You can filter them with either source: "chatgpt" or source: "import:chatgpt".

ProfileCommitInput

type ProfileCommitInput = {
  messages?: Array<{ role: "user" | "assistant" | "tool"; content: string; toolName?: string }>;
  response?: unknown;
  toolResults?: Array<{ toolName: string; content: string | object }>;
  memories?: string[];
  sync?: boolean;
};

commit() accepts bounded source material. messages or toolResults can clear read-backed commit obligations; memories are optional durable facts/preferences. It does not accept metadata or internal read-obligation/source-context fields.

Import Types

type ImportMode = "backfill";
type ImportJobStatus = "queued" | "processing" | "completed" | "failed" | "cancelled";

type ImportProfilesRequest = {
  mode: "backfill";
  // Scoped to the developer account and acting agent.
  idempotencyKey?: string;
  users: Array<{
    externalId: string;
    idempotencyKey?: string;
    profile?: {
      summary?: string;
      preferences?: string[];
      facts?: string[];
      identity?: Record<string, string>;
      [key: string]: unknown;
    };
    conversations?: Array<{
      id?: string;
      messages: Array<{
        role: "system" | "user" | "assistant" | "tool";
        content: string;
      }>;
    }>;
  }>;
};

type ImportJob = {
  id: string;
  mode: "backfill";
  status: ImportJobStatus;
  accepted_profiles: number;
  estimated_message_count: number;
  estimated_input_chars: number;
  imported_memory_count: number;
  processed_profile_count: number;
  failed_profile_count: number;
  quota?: {
    imported_profiles: {
      used: number;
      limit: number | "unlimited";
      requestedNew: number;
      remaining: number | "unlimited";
    };
  };
  caps?: {
    max_profiles_per_job: number;
    max_total_input_chars_per_job: number;
    max_concurrent_import_jobs: number;
    max_conversations_per_profile: number;
    max_messages_per_conversation: number;
    max_chars_per_message: number;
  };
  created_at: string;
  updated_at: string;
  started_at?: string | null;
  completed_at?: string | null;
  cancelled_at?: string | null;
};

Use configure.importProfiles() for historical/onboarding backfill and configure.importJobs.get(jobId) for polling. Import is server-side and secret-key only; it is not a model tool and does not write root profile files.

ProfileToolsOptions

type ProfileToolsOptions = {
  connectors?: Array<"gmail" | "calendar" | "drive" | "notion">;
  actions?: Array<"email.send" | "calendar.create_event">;
  advanced?: {
    commit?: boolean;
    files?: boolean;
    utilitySearch?: boolean;
  };
};

connectors and actions control which non-default tools are returned and executable for that runtime handle. advanced exposes adapter/runtime tools and raw profile file tools; these are not part of the default model-facing surface.

ConfigureToolCall

type ConfigureToolCall = {
  name?: string;
  arguments?: Record<string, unknown> | string;
  input?: Record<string, unknown>;
  function?: {
    name?: string;
    arguments?: Record<string, unknown> | string;
  };
};

profile.executeTool() accepts common tool-call shapes from model SDKs and normalizes them internally.

ConfigureError

SDK failures throw ConfigureError with a stable code, optional statusCode, and structured fields such as type, param, retryable, suggestedAction, docUrl, retryAfter, and requestId.