Agent HTTP reference

This reference follows the current server implementation. Use the SDK for customer flows; it manages identity proof and retries. Authentication and errors apply to every endpoint. Types below describe JSON: dates are ISO strings, ? means optional, and null differs from an omitted field. Responses may include additional fields. Schemas also enforce constraints that TypeScript cannot express; download the request JSON Schemas. Named response types are defined in the data model reference.

GET /agent/context

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ providerConnections?: { connections: { connection: ProviderConnectionDto;
  accounts: { workspaceId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  connectionId: string;
  parentAccountId: string | null;
  accountKind: string;
  externalAccountId: string;
  role: string | null;
  permissions: string[];
  currency: string | null;
  timezone: string | null;
  metadata: ProviderConnectionAccountMetadata;
  lastDiscoveredAt: string;
  }[];
  mappings: { appId: string;
  projectId: string;
  workspaceId: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  enabled: boolean;
  connectionId: string;
  accountId: string;
  externalAppId: string;
  externalAppName: string | null;
  settings: ProviderConnectionAppMappingSettings;
  }[];
  operations: { appId: string | null;
  workspaceId: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  status: "failed" | "queued" | "running" | "succeeded" | "cancelled" | "expired";
  completedAt: string | null;
  startedAt: string | null;
  connectionId: string;
  accountId: string | null;
  appMappingId: string | null;
  parentOperationId: string | null;
  actorPlatformUserId: string | null;
  operationType: "validate" | "sync" | "import_preview" | "import_apply" | "secret_rotate" | "connection_revoke" | "resource_mutation_preview" | "resource_mutation_apply" | "resource_destructive_preview" | "resource_destructive_apply";
  idempotencyKey: string | null;
  resourceType: string | null;
  resourceId: string | null;
  request: ProviderConnectionOperationData;
  beforeState: ProviderConnectionOperationData | null;
  requestedState: ProviderConnectionOperationData | null;
  providerResponse: ProviderConnectionOperationData | null;
  errorCode: string | null;
  errorMessage: string | null;
  queuedAt: string;
  expiresAt: string | null;
  appliedAt: string | null;
  }[];
  }[];
  } | undefined;
  workspace: { id: string;
  name: string;
  slug: string;
  };
  token: { id: string;
  scopes: ("workspace:read" | "workspace:write" | "apps:read" | "apps:write" | "reports:read" | "catalog:read" | "catalog:write" | "paywalls:read" | "paywalls:write" | "messaging:read" | "messaging:write" | "campaigns:read" | "campaigns:write" | "remote_config:read" | "remote_config:write" | "surfaces:read" | "surfaces:write" | "surveys:read" | "surveys:write" | "rules:read" | "rules:write" | "webhooks:read" | "webhooks:write" | "integrations:read" | "integrations:write" | "auth:read" | "auth:write" | "audit:read")[];
  allowedAppIds: string[] | null | undefined;
  };
  apps: { id: string;
  name: string;
  emailChangeMode: string;
  environment: "test" | "live";
  liveAppId: string | null;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentContext.

GET /agent/apps/:appId/paid-access-settings

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

"account" | "app_store"

Response

JSON response shape

{ settings: { appId: string;
  platform: "ios" | "android" | "web" | "windows" | "macos";
  bootstrap: { appId: string;
  bundleId: string | null;
  environment: "test" | "live";
  paidAccess: PaidAccessConfiguration;
  };
  policy: "account" | "app_store";
  appPurchaseRules: AppStoreAppPurchaseRule[];
  preservedImport: PreservedImportPolicy | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentPaidAccessSettings.

GET /agent/apps/:appId/account-deletion-policy

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  }

Response

JSON response shape

{ [x: string]: unknown;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentAccountDeletionPolicy.

GET /agent/auth-identities/inspect

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ environment: "test" | "live";
  email: string;
  }

Response

JSON response shape

{ environment: IdEnvironment;
  normalizedEmail: string;
  identity: null | { id: string;
  email: string;
  emailVerified: boolean;
  createdAt: string;
  updatedAt: string;
  providers: Array<{ providerId: string;
  accountCount: number;
  hasPassword: boolean;
  passwordUpdatedAt: string | null;
  }>;
  customerCount: number;
  linkedAppIds: string[];
  workspaceCustomerCount: number;
  sessionCount: number;
  activeSessionCount: number;
  challengeCount: number;
  activeChallengeCount: number;
  deletionEligibility: { eligible: boolean;
  environment: "test_only";
  reasonCodes: string[];
  };
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleInspectAgentAuthIdentity.

GET /agent/creative-contract

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ [x: string]: unknown;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentCreativeContract.

GET /agent/apps/:appId/in-app-surfaces

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: identifier, path.appId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  surfaces: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  description: string | null;
  config: AnyInAppSurfaceConfig;
  surfaceType: string;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentInAppSurfaces.

GET /agent/apps/:appId/in-app-surfaces/:surfaceIdOrIdentifier

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), surfaceIdOrIdentifier (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.surfaceIdOrIdentifier. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  surface: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  description: string | null;
  config: AnyInAppSurfaceConfig;
  surfaceType: string;
  };
  revisions: { appId: string;
  id: string;
  createdAt: string;
  label: string | null;
  source: "publish" | "restore";
  config: AnyPaywallConfig | AnyInAppSurfaceConfig | SurveyConfig;
  creativeType: "paywall" | "in_app_surface" | "survey";
  creativeId: string;
  configVersion: string;
  createdByPlatformUserId: string | null;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentInAppSurface.

GET /agent/apps/:appId/paywalls

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: identifier, path.appId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  paywalls: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  isDefault: boolean;
  description: string | null;
  config: AnyPaywallConfig;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentPaywalls.

GET /agent/apps/:appId/paywall-placements

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  placements: { id: string;
  identifier: string;
  name: string;
  fallbackPaywall: { id: string;
  identifier: string;
  name: string;
  status: "active" | "inactive" | "archived";
  } | null;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentPaywallPlacements.

GET /agent/apps/:appId/paywalls/:paywallIdOrIdentifier

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), paywallIdOrIdentifier (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.paywallIdOrIdentifier. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  paywall: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  isDefault: boolean;
  description: string | null;
  config: AnyPaywallConfig;
  };
  revisions: { appId: string;
  id: string;
  createdAt: string;
  label: string | null;
  source: "publish" | "restore";
  config: AnyPaywallConfig | AnyInAppSurfaceConfig | SurveyConfig;
  creativeType: "paywall" | "in_app_surface" | "survey";
  creativeId: string;
  configVersion: string;
  createdByPlatformUserId: string | null;
  }[];
  productLinks: { appId: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  productId: string;
  paywallId: string;
  product: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  description: string | null;
  pricingType: "subscription" | "non_consumable" | "consumable" | "free";
  pricingPeriod: "month" | "year" | null;
  prices: { appId: string;
  active: boolean;
  platform: "ios" | "android" | "web" | "windows" | "macos" | null;
  id: string;
  createdAt: string;
  updatedAt: string;
  provider: "stripe" | "apple_app_store" | "google_play" | "microsoft_store";
  currency: string | null;
  metadata: Record<string, unknown>;
  productId: string;
  isDefault: boolean;
  providerProductId: string;
  providerPriceId: string | null;
  unitAmount: number | null;
  billingPeriod: "month" | "year" | null;
  trialConfig: ProductPriceTrialConfig;
  familySharingEnabled: boolean;
  priority: number;
  }[];
  };
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentPaywall.

GET /agent/apps/:appId/email-templates

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: identifier, path.appId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  emailTemplates: { id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  category: "transactional" | "lifecycle" | "marketing" | "system";
  enabled: boolean;
  channel: "email" | "push";
  locale: string;
  subject: string | null;
  contentType: "push" | "mjml" | "html" | "text";
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentEmailTemplates.

GET /agent/apps/:appId/email-templates/:templateId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), templateId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.templateId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  emailTemplate: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  category: "transactional" | "lifecycle" | "marketing" | "system";
  enabled: boolean;
  channel: "email" | "push";
  locale: string;
  subject: string | null;
  title: string | null;
  bodyText: string | null;
  contentType: "push" | "mjml" | "html" | "text";
  contentSource: string | null;
  contentHtml: string | null;
  dataPayload: Record<string, unknown> | null;
  variables: Record<string, unknown> | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentEmailTemplate.

GET /agent/apps/:appId/campaigns

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ identifier?: string | undefined;
  status?: "active" | "inactive" | "archived" | undefined;
  limit?: unknown;
  }

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  campaigns: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  description: string | null;
  priority: number;
  startsAt: string | null;
  endsAt: string | null;
  currentExperimentRunId: string | null;
  placements: { appId: string;
  createdAt: string;
  campaignId: string;
  placementId: string;
  placement: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  description: string | null;
  kind: "paywall" | "in_app_surface" | "survey" | "custom";
  fallbackPaywallId: string | null;
  firstSeenAt: string | null;
  lastSeenAt: string | null;
  };
  }[];
  audiences: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  enabled: boolean;
  audienceRule: RuleLogic | null;
  cooldownSeconds: number;
  windowSeconds: number | null;
  description: string | null;
  campaignId: string;
  sortOrder: number;
  maxMatchesPerCustomer: number | null;
  maxMatchesPerWindow: number | null;
  variants: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  payload: Record<string, unknown> | null;
  paywallId: string | null;
  campaignId: string;
  campaignAudienceId: string;
  allocationPercent: number;
  isControl: boolean;
  targetType: "paywall" | "in_app_surface" | "survey" | "custom" | "none";
  inAppSurfaceId: string | null;
  surveyId: string | null;
  paywall: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  isDefault: boolean;
  description: string | null;
  config: AnyPaywallConfig;
  } | null;
  inAppSurface: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  description: string | null;
  config: AnyInAppSurfaceConfig;
  surfaceType: string;
  } | null;
  }[];
  }[];
  currentExperimentRun: { appId: string;
  id: string;
  createdAt: string;
  startedAt: string;
  campaignId: string;
  configRevision: number;
  configurationHash: string;
  randomizationUnit: "canonical_app_customer";
  conversionEvent: string;
  conversionWindowSeconds: number;
  baselineConversionRateBps: number;
  minimumDetectableEffectBps: number;
  alphaBps: number;
  targetPowerBps: number;
  minimumSamplePerArm: number;
  endedAt: string | null;
  } | null;
  }[];
  limit: number;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentCampaigns.

GET /agent/apps/:appId/campaigns/:campaignIdOrIdentifier

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), campaignIdOrIdentifier (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.campaignIdOrIdentifier. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  campaign: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  description: string | null;
  priority: number;
  startsAt: string | null;
  endsAt: string | null;
  currentExperimentRunId: string | null;
  placements: { appId: string;
  createdAt: string;
  campaignId: string;
  placementId: string;
  placement: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  description: string | null;
  kind: "paywall" | "in_app_surface" | "survey" | "custom";
  fallbackPaywallId: string | null;
  firstSeenAt: string | null;
  lastSeenAt: string | null;
  };
  }[];
  audiences: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  enabled: boolean;
  audienceRule: RuleLogic | null;
  cooldownSeconds: number;
  windowSeconds: number | null;
  description: string | null;
  campaignId: string;
  sortOrder: number;
  maxMatchesPerCustomer: number | null;
  maxMatchesPerWindow: number | null;
  variants: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  payload: Record<string, unknown> | null;
  paywallId: string | null;
  campaignId: string;
  campaignAudienceId: string;
  allocationPercent: number;
  isControl: boolean;
  targetType: "paywall" | "in_app_surface" | "survey" | "custom" | "none";
  inAppSurfaceId: string | null;
  surveyId: string | null;
  paywall: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  isDefault: boolean;
  description: string | null;
  config: AnyPaywallConfig;
  } | null;
  inAppSurface: { appId: string;
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  identifier: string;
  status: "active" | "inactive" | "archived";
  description: string | null;
  config: AnyInAppSurfaceConfig;
  surfaceType: string;
  } | null;
  }[];
  }[];
  currentExperimentRun: { appId: string;
  id: string;
  createdAt: string;
  startedAt: string;
  campaignId: string;
  configRevision: number;
  configurationHash: string;
  randomizationUnit: "canonical_app_customer";
  conversionEvent: string;
  conversionWindowSeconds: number;
  baselineConversionRateBps: number;
  minimumDetectableEffectBps: number;
  alphaBps: number;
  targetPowerBps: number;
  minimumSamplePerArm: number;
  endedAt: string | null;
  } | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentCampaign.

GET /agent/apps/:appId/ios-release-readiness

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

string

unknown

{ paywall: { id: string;
  identifier: string;
  name: string;
  config: unknown;
  description?: string | null | undefined;
  };
  paywallProducts: { id: string;
  identifier: string;
  product: { id: string;
  identifier: string;
  name: string;
  pricingType: "subscription" | "non_consumable" | "consumable" | "free";
  pricingPeriod: "month" | "year" | null;
  description?: string | null | undefined;
  };
  productPrice: { id: string;
  provider: "stripe" | "apple_app_store" | "google_play" | "microsoft_store" | "custom";
  platform: "ios" | "android" | "web" | "windows" | "macos" | null;
  providerProductId: string;
  providerPriceId?: string | null | undefined;
  currency?: string | null | undefined;
  unitAmount?: number | null | undefined;
  billingPeriod?: "month" | "year" | null | undefined;
  trialOffer?: { type: "free_trial";
  trialPeriodDays?: number | undefined;
  appleSubscriptionGroupId?: string | undefined;
  } | null | undefined;
  } | null;
  prices?: Partial<Record<"stripe" | "apple_app_store" | "google_play" | "microsoft_store" | "custom", { amountMinor: number;
  currency: string;
  interval: "month" | "year" | null;
  intervalCount: number;
  }>> | undefined;
  }[];
  paywallOffers?: { identifier: string;
  productIdentifier: string;
  offerKind: "subscription_offer_code" | "in_app_purchase_offer_code";
  prices: { territory: string;
  pricePointId: string;
  customerPrice: string;
  currency: string;
  }[];
  offerMode?: "free" | "pay_as_you_go" | "pay_up_front" | "discount" | null | undefined;
  duration?: string | null | undefined;
  numberOfPeriods?: number | null | undefined;
  autoRenews?: boolean | null | undefined;
  regularPrice?: { amountMinor: number;
  currency: string;
  billingPeriod?: "month" | "year" | null | undefined;
  } | undefined;
  }[] | undefined;
  campaign?: { placementId: string;
  placementIdentifier: string;
  targetType: "paywall" | "in_app_surface" | "survey" | "custom" | "none";
  campaignId?: string | null | undefined;
  campaignIdentifier?: string | null | undefined;
  campaignAudienceId?: string | null | undefined;
  campaignAudienceIdentifier?: string | null | undefined;
  campaignVariantId?: string | null | undefined;
  campaignVariantIdentifier?: string | null | undefined;
  campaignAssignmentId?: string | null | undefined;
  } | undefined;
  }

Response

JSON response shape

{ report: IosReleaseReadinessReport;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentIosReleaseReadiness.

GET /agent/apps/:appId/provider-events

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ provider?: "stripe" | "google_play" | "apple" | undefined;
  status?: "failed" | "received" | "processing" | "processed" | "ignored" | undefined;
  providerEventType?: string | undefined;
  replayable?: "false" | "true" | undefined;
  limit?: unknown;
  offset?: unknown;
  }

Response

JSON response shape

{ events: { canReplay: boolean;
  diagnostic?: { exactPurchase: { providerTransactionId: string | null;
  id: string;
  customerId: string;
  ownershipType: "purchased" | "family_shared" | "unknown";
  } | null;
  originalChain: { originalTransactionId: string | null;
  count: number;
  familySharedCount: number;
  } | null;
  notificationType: string | null;
  notificationSubtype: string | null;
  appleEnvironment: string | null;
  bundleId: string | null;
  signedDate: string | null;
  transactionId: string | null;
  originalTransactionId: string | null;
  appTransactionId: string | null;
  offerIdentifier: string | null;
  offerType: number | null;
  offerDiscountType: string | null;
  productId: string | null;
  ownershipType: string | null;
  transactionType: string | null;
  transactionReason: string | null;
  appAccountTokenPresent: boolean;
  purchaseDate: number | null;
  originalPurchaseDate: number | null;
  expiresDate: number | null;
  revocationDate: number | null;
  revocationType: string | null;
  } | undefined;
  id: string;
  provider: "stripe" | "google_play" | "apple";
  providerEventType: string | null;
  status: "failed" | "received" | "processing" | "processed" | "ignored";
  attemptCount: number;
  receivedAt: string;
  processedAt: string;
  lastError: string | null;
  replayCount: number;
  lastReplayedAt: string | null;
  lastReplayedByPlatformUserId: string | null;
  }[];
  hasMore: boolean;
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentProviderEvents.

GET /agent/apps/:appId/crash-reports/groups

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ environment?: "test" | "live" | undefined;
  appVersion?: string | undefined;
  buildNumber?: string | undefined;
  startAt?: string | undefined;
  endAt?: string | undefined;
  limit?: unknown;
  }

Response

JSON response shape

{ legacySignals: LegacyCrashSignalSummary;
  groups: CrashReportGroup[];
  versions: CrashReportVersionSummary[];
  totals: { crashCount: number;
  groupCount: number;
  affectedCustomers: number;
  };
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentCrashReportGroups.

GET /agent/apps/:appId/crash-reports/groups/:fingerprint

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), fingerprint (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

string

{ appVersion: string;
  buildNumber: string;
  environment?: "test" | "live" | undefined;
  }

Response

JSON response shape

{ group: CrashReportGroup;
  representative: CrashReportSummary & { formattedReport: string;
  };
  osVersions: CrashReportBreakdownItem[];
  devices: CrashReportBreakdownItem[];
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentCrashReportGroup.

GET /agent/apps/:appId/query

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ resource: "products" | "customers" | "subscriptions" | "support_threads" | "webhook_deliveries" | "notification_deliveries" | "events" | "billing_identity_conflicts" | "apple_purchaser_links" | "transactions" | "entitlement_grants" | "acquisition_touchpoints";
  id?: string | undefined;
  customerId?: string | undefined;
  billingTransactionId?: string | undefined;
  providerTransactionId?: string | undefined;
  status?: string | undefined;
  type?: string | undefined;
  provider?: string | undefined;
  search?: string | undefined;
  includeDebugMetadata?: boolean | "false" | "true" | undefined;
  from?: string | undefined;
  to?: string | undefined;
  limit?: unknown;
  offset?: unknown;
  }

"account" | "app_store"

{ version: 1;
  observedAt: string;
  policy: "account" | "app_store";
  verification: "unavailable" | "authoritative" | "verified_entitlements" | "cached";
  benefits: { identifier: string;
  source: "manual" | "apple" | "account" | "support_purchaser" | "preserved_import";
  effectiveUntil?: number | null | undefined;
  verifiedAt?: string | null | undefined;
  }[];
  truncated: boolean;
  providerEnvironment?: "Production" | "Sandbox" | "Xcode" | null | undefined;
  operationId?: string | null | undefined;
  attemptId?: string | null | undefined;
  requestId?: string | null | undefined;
  accessContextExpiresAt?: number | null | undefined;
  appleEvidence?: { observedAt: string;
  acquisition: "unavailable" | "rejected" | "app_transaction" | "receipt";
  purchaserComparison: "unavailable" | "first_observation" | "same" | "changed";
  collectionComplete: boolean;
  priorTransactionCount: number;
  submittedTransactionCount: number;
  retainedTransactionCount: number;
  missingProductIdentifiers: string[];
  previousPurchaserHash?: string | null | undefined;
  currentPurchaserHash?: string | null | undefined;
  acquisitionFailureStage?: string | null | undefined;
  } | null | undefined;
  }

{ version: 1;
  id: string;
  requestId: string;
  operationId: string | null;
  route: "access" | "evidence";
  receivedAt: string;
  finishedAt: string;
  verifiedAt: string | null;
  policy: "account" | "app_store" | null;
  configurationRevision: string | null;
  providerEnvironment: "Production" | "Sandbox" | null;
  outcome: "failed" | "partial" | "verified";
  completeness: "failed" | "complete" | "partial" | "submitted_evidence";
  acquisitionVerified: boolean | null;
  transactionCounts: { submitted: number;
  verified: number | null;
  active: number | null;
  inactive: number | null;
  unverified: number | null;
  unmapped: number | null;
  } | null;
  entitlements: { identifier: string;
  expiresAt: number | null;
  source: "manual" | "apple";
  }[];
  entitlementsTruncated: boolean;
  responseExpiresAt: number | null;
  accessContextExpiresAt: number | null;
  stage: "completed" | "acquisition" | "configuration" | "transactions" | "mapping" | "purchaser_link" | "context_signing" | "contract_validation";
  failure: { code: "invalid_contract" | "verification_rejected" | "service_error";
  httpStatus: number;
  retryable: boolean;
  } | null;
  appVersion: string | null;
  sdkVersion: string | null;
  deviceModel: string | null;
  osVersion: string | null;
  versionProvenance: "unknown" | "request_headers";
  attemptId?: string | null | undefined;
  evidenceIssues?: { source: "renewal" | "acquisition" | "transaction" | "mapping";
  reason: "verification_failed" | "claims_invalid" | "device_mismatch" | "environment_mismatch" | "unmatched_renewal" | "catalog_mapping_failed";
  index?: number | undefined;
  }[] | undefined;
  }

Response

JSON response shape

{ paidAccessPolicy?: "account" | "app_store" | undefined;
  applePurchasers?: { id: string;
  appId: string;
  customerId: string;
  providerEnvironment: "sandbox" | "production";
  appTransactionId: string;
  originalAppVersion: string | null;
  originalPurchaseDate: string | null;
  deviceName: string | null;
  firstVerifiedAt: string;
  lastVerifiedAt: string;
  }[] | undefined;
  accessObservations?: CustomerAccessObservations | undefined;
  resource: AgentAppQueryResource;
  items: Array<Record<string, unknown>>;
  pagination: { limit: number;
  offset: number;
  returned: number;
  hasMore: boolean;
  };
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleQueryAgentAppData.

POST /agent/apps/:appId/customers/:customerId/usage/query

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), customerId (string). Every target must belong to the authenticated app or workspace.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ appId: string;
  customerId: string;
  query: { from: string;
  to: string;
  view: "summary";
  metrics?: { key: string;
  definitionRevision: number;
  }[] | undefined;
  } | { from: string;
  to: string;
  kind: "session" | "daily";
  limit: number;
  view: "records";
  cursor?: { usageDate: string;
  lastObservedAt: string;
  id: string;
  } | undefined;
  };
  }

{ from: string;
  to: string;
  metrics?: { key: string;
  definitionRevision: number;
  }[] | undefined;
  }

{ from: string;
  to: string;
  kind: "session" | "daily";
  limit: number;
  cursor?: { usageDate: string;
  lastObservedAt: string;
  id: string;
  } | undefined;
  }

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  };
  customerId: string;
  metrics: { key: string;
  revision: number;
  label: string;
  unit: "duration" | "count" | "bytes" | "credits";
  scale: number;
  allowedSources: ("server" | "client")[];
  dimensionKeys: string[];
  entitlementId: string | null;
  isActive: boolean;
  }[];
  usage: UsageReadPage | UsageSummary;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleQueryAgentCustomerUsage.

GET /agent/apps/:appId/app-store/catalog-audit

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ productId?: string | undefined;
  productKind?: "subscription" | "in_app_purchase" | undefined;
  referenceTerritory?: string | undefined;
  }

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  audit: { operationId: string;
  appId: string;
  externalAppId: string;
  products: AppStoreConnectProduct[];
  currentSchedules: { productId: string;
  productKind: "subscription" | "in_app_purchase";
  productResourceId: string;
  prices: AppStoreConnectCurrentPrice[];
  }[];
  referencePricePoints: { productId: string;
  productKind: AppStoreConnectProduct["kind"];
  territory: string;
  pricePoints: AppStoreConnectPricePoint[];
  } | null;
  issues: { code: string;
  productId: string;
  message: string;
  }[];
  pricingReferences: { purchasingPowerParity: { version: string;
  indicator: string;
  source: string;
  lastUpdated: string;
  priceLevelIndicator: string;
  priceLevelSource: string;
  priceLevelLastUpdated: string;
  };
  fourTierRegional: { version: string;
  source: string;
  };
  missingPppTerritories: string[];
  };
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleAuditAgentAppStoreCatalog.

POST /agent/apps/:appId/app-store/pricing-previews

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ productId: string;
  productKind: "subscription" | "in_app_purchase";
  effectiveDate: string;
  strategy: { kind: "apple_equalized";
  referenceTerritory: string;
  referencePricePointId: string;
  } | { kind: "purchasing_power_parity";
  referenceTerritory: string;
  referencePricePointId: string;
  datasetVersion: string;
  overrides?: { territory: string;
  pricePointId: string;
  }[] | undefined;
  } | { kind: "four_tier_regional";
  referenceTerritory: string;
  classificationVersion: string;
  pricePointIds: { high: string;
  upperMiddle: string;
  lowerMiddle: string;
  low: string;
  };
  overrides?: { territory: string;
  pricePointId: string;
  }[] | undefined;
  };
  subscriberPricePolicy?: "preserve_existing" | "change_existing" | undefined;
  }

Response

JSON response shape

{ plan: { appId: string | null;
  workspaceId: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  status: "failed" | "queued" | "running" | "succeeded" | "cancelled" | "expired";
  completedAt: string | null;
  startedAt: string | null;
  connectionId: string;
  accountId: string | null;
  appMappingId: string | null;
  parentOperationId: string | null;
  actorPlatformUserId: string | null;
  operationType: "validate" | "sync" | "import_preview" | "import_apply" | "secret_rotate" | "connection_revoke" | "resource_mutation_preview" | "resource_mutation_apply" | "resource_destructive_preview" | "resource_destructive_apply";
  idempotencyKey: string | null;
  resourceType: string | null;
  resourceId: string | null;
  request: ProviderConnectionOperationData;
  beforeState: ProviderConnectionOperationData | null;
  requestedState: ProviderConnectionOperationData | null;
  providerResponse: ProviderConnectionOperationData | null;
  errorCode: string | null;
  errorMessage: string | null;
  queuedAt: string;
  expiresAt: string | null;
  appliedAt: string | null;
  };
  preview: AppStorePricingPreview;
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handlePreviewAgentAppStorePricing.

GET /agent/apps/:appId/app-store/pricing-previews/:planId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), planId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.planId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ plan: { appId: string | null;
  workspaceId: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  status: "failed" | "queued" | "running" | "succeeded" | "cancelled" | "expired";
  completedAt: string | null;
  startedAt: string | null;
  connectionId: string;
  accountId: string | null;
  appMappingId: string | null;
  parentOperationId: string | null;
  actorPlatformUserId: string | null;
  operationType: "validate" | "sync" | "import_preview" | "import_apply" | "secret_rotate" | "connection_revoke" | "resource_mutation_preview" | "resource_mutation_apply" | "resource_destructive_preview" | "resource_destructive_apply";
  idempotencyKey: string | null;
  resourceType: string | null;
  resourceId: string | null;
  request: ProviderConnectionOperationData;
  beforeState: ProviderConnectionOperationData | null;
  requestedState: ProviderConnectionOperationData | null;
  providerResponse: ProviderConnectionOperationData | null;
  errorCode: string | null;
  errorMessage: string | null;
  queuedAt: string;
  expiresAt: string | null;
  appliedAt: string | null;
  };
  preview: AppStorePricingPreview;
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentAppStorePricingPlan.

GET /agent/apps/:appId/app-store/pricing-operations/:operationId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), operationId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.operationId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  operation: { appId: string | null;
  workspaceId: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  status: "failed" | "queued" | "running" | "succeeded" | "cancelled" | "expired";
  completedAt: string | null;
  startedAt: string | null;
  connectionId: string;
  accountId: string | null;
  appMappingId: string | null;
  parentOperationId: string | null;
  actorPlatformUserId: string | null;
  operationType: "validate" | "sync" | "import_preview" | "import_apply" | "secret_rotate" | "connection_revoke" | "resource_mutation_preview" | "resource_mutation_apply" | "resource_destructive_preview" | "resource_destructive_apply";
  idempotencyKey: string | null;
  resourceType: string | null;
  resourceId: string | null;
  request: ProviderConnectionOperationData;
  beforeState: ProviderConnectionOperationData | null;
  requestedState: ProviderConnectionOperationData | null;
  providerResponse: ProviderConnectionOperationData | null;
  errorCode: string | null;
  errorMessage: string | null;
  queuedAt: string;
  expiresAt: string | null;
  appliedAt: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentAppStorePricingOperation.

GET /agent/apps/:appId/product-offers

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  offers: { codeBatches: { id: string;
  productOfferId: string;
  providerBatchId: string | null;
  providerEnvironment: "sandbox" | "production";
  requestedCodeCount: number;
  ingestedCodeCount: number;
  expiresAt: string;
  allocatableAt: string;
  status: "failed" | "provisioning" | "deactivated" | "ready" | "expired";
  ingestionAttemptCount: number;
  lastIngestionErrorCode: string | null;
  lastIngestedAt: string | null;
  lastSyncedAt: string | null;
  createdAt: string;
  readyCodeCount: number;
  assignedCodeCount: number;
  redeemedCodeCount: number;
  expiredCodeCount: number;
  supersededCodeCount: number;
  }[];
  readyCodeCount: number;
  assignedCodeCount: number;
  redeemedCodeCount: number;
  expiredCodeCount: number;
  supersededCodeCount: number;
  id: string;
  identifier: string;
  productId: string;
  productPriceId: string;
  productName: string;
  productIdentifier: string;
  providerProductId: string;
  regularUnitAmount: number | null;
  regularCurrency: string | null;
  regularBillingPeriod: "month" | "year" | null;
  provider: "apple_app_store";
  providerOfferId: string | null;
  providerReferenceName: string | null;
  offerKind: "subscription_offer_code" | "in_app_purchase_offer_code";
  status: "active" | "failed" | "draft" | "provisioning" | "paused" | "deactivated";
  exclusiveGroupIdentifier: string | null;
  providerConfig: ProductOfferProviderConfig | null;
  createdAt: string;
  updatedAt: string;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentProductOffers.

GET /agent/apps/:appId/product-offers-discovery

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  discovery: { appId: string;
  externalAppId: string;
  products: { productId: string;
  productResourceId: string;
  name: string;
  kind: AppStoreConnectProduct["kind"];
  state: string;
  oneProductId: string | null;
  oneProductPriceId: string | null;
  offers: AppStoreConnectOfferCode[];
  }[];
  localOfferCount: number;
  appleOfferCount: number;
  issues: { code: string;
  productId: string;
  offerReferenceName: string;
  message: string;
  }[];
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleDiscoverAgentProductOffers.

GET /agent/apps/:appId/product-offers/:productOfferId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), productOfferId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.productOfferId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  offer: { codeBatches: { id: string;
  productOfferId: string;
  providerBatchId: string | null;
  providerEnvironment: "sandbox" | "production";
  requestedCodeCount: number;
  ingestedCodeCount: number;
  expiresAt: string;
  allocatableAt: string;
  status: "failed" | "provisioning" | "deactivated" | "ready" | "expired";
  ingestionAttemptCount: number;
  lastIngestionErrorCode: string | null;
  lastIngestedAt: string | null;
  lastSyncedAt: string | null;
  createdAt: string;
  readyCodeCount: number;
  assignedCodeCount: number;
  redeemedCodeCount: number;
  expiredCodeCount: number;
  supersededCodeCount: number;
  }[];
  readyCodeCount: number;
  assignedCodeCount: number;
  redeemedCodeCount: number;
  expiredCodeCount: number;
  supersededCodeCount: number;
  id: string;
  identifier: string;
  productId: string;
  productPriceId: string;
  productName: string;
  productIdentifier: string;
  providerProductId: string;
  regularUnitAmount: number | null;
  regularCurrency: string | null;
  regularBillingPeriod: "month" | "year" | null;
  provider: "apple_app_store";
  providerOfferId: string | null;
  providerReferenceName: string | null;
  offerKind: "subscription_offer_code" | "in_app_purchase_offer_code";
  status: "active" | "failed" | "draft" | "provisioning" | "paused" | "deactivated";
  exclusiveGroupIdentifier: string | null;
  providerConfig: ProductOfferProviderConfig | null;
  createdAt: string;
  updatedAt: string;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentProductOffer.

POST /agent/apps/:appId/product-offer-operation-previews

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ operation: "create_offer";
  identifier: string;
  productPriceId: string;
  referenceName: string;
  terms: { kind: "in_app_purchase";
  customerEligibilities: ("NON_SPENDER" | "ACTIVE_SPENDER" | "CHURNED_SPENDER")[];
  prices: { territory: string;
  pricePointId: string;
  }[];
  } | { kind: "subscription";
  customerEligibilities: ("NEW" | "EXISTING" | "EXPIRED")[];
  offerEligibility: "STACK_WITH_INTRO_OFFERS" | "REPLACE_INTRO_OFFERS";
  duration: "THREE_DAYS" | "ONE_WEEK" | "TWO_WEEKS" | "ONE_MONTH" | "TWO_MONTHS" | "THREE_MONTHS" | "SIX_MONTHS" | "ONE_YEAR";
  offerMode: "FREE_TRIAL" | "PAY_AS_YOU_GO" | "PAY_UP_FRONT";
  numberOfPeriods: number;
  prices: { territory: string;
  pricePointId: string;
  }[];
  autoRenewEnabled?: boolean | undefined;
  targetSubscriptionPlanType?: "MONTHLY" | "UPFRONT" | undefined;
  };
  exclusiveGroupIdentifier?: string | undefined;
  } | { operation: "create_batch";
  productOfferId: string;
  providerEnvironment: "sandbox" | "production";
  requestedCodeCount: number;
  expirationDate: string;
  } | { operation: "refresh_offer";
  productOfferId: string;
  } | { operation: "deactivate_offer";
  productOfferId: string;
  } | { operation: "deactivate_batch";
  productOfferId: string;
  batchId: string;
  }

Response

JSON response shape

{ preview: { id: string;
  operationType: "validate" | "sync" | "import_preview" | "import_apply" | "secret_rotate" | "connection_revoke" | "resource_mutation_preview" | "resource_mutation_apply" | "resource_destructive_preview" | "resource_destructive_apply";
  status: "failed" | "queued" | "running" | "succeeded" | "cancelled" | "expired";
  resourceType: string | null;
  resourceId: string | null;
  beforeState: ProviderConnectionOperationData | null;
  requestedState: ProviderConnectionOperationData | null;
  createdAt: string;
  expiresAt: string | null;
  };
  digest: string;
  expiresAt: string;
  plan: ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { operation: "create_offer";
  productOfferId: string;
  identifier: string;
  productId: string;
  productPriceId: string;
  providerProductId: string;
  providerProductResourceId: string;
  referenceName: string;
  exclusiveGroupIdentifier?: string;
  terms: z.infer<z.ZodDiscriminatedUnion<[z.ZodObject<{ kind: z.ZodLiteral<"in_app_purchase">;
  customerEligibilities: z.ZodArray<z.ZodEnum<{ NON_SPENDER: "NON_SPENDER";
  ACTIVE_SPENDER: "ACTIVE_SPENDER";
  CHURNED_SPENDER: "CHURNED_SPENDER";
  }>>;
  prices: z.ZodArray<z.ZodObject<{ territory: z.ZodString;
  pricePointId: z.ZodString;
  }, z.core.$strict>>;
  }, z.core.$strict>, z.ZodObject<{ kind: z.ZodLiteral<"subscription">;
  customerEligibilities: z.ZodArray<z.ZodEnum<{ NEW: "NEW";
  EXISTING: "EXISTING";
  EXPIRED: "EXPIRED";
  }>>;
  offerEligibility: z.ZodEnum<{ STACK_WITH_INTRO_OFFERS: "STACK_WITH_INTRO_OFFERS";
  REPLACE_INTRO_OFFERS: "REPLACE_INTRO_OFFERS";
  }>;
  duration: z.ZodEnum<{ THREE_DAYS: "THREE_DAYS";
  ONE_WEEK: "ONE_WEEK";
  TWO_WEEKS: "TWO_WEEKS";
  ONE_MONTH: "ONE_MONTH";
  TWO_MONTHS: "TWO_MONTHS";
  THREE_MONTHS: "THREE_MONTHS";
  SIX_MONTHS: "SIX_MONTHS";
  ONE_YEAR: "ONE_YEAR";
  }>;
  offerMode: z.ZodEnum<{ FREE_TRIAL: "FREE_TRIAL";
  PAY_AS_YOU_GO: "PAY_AS_YOU_GO";
  PAY_UP_FRONT: "PAY_UP_FRONT";
  }>;
  numberOfPeriods: z.ZodNumber;
  autoRenewEnabled: z.ZodOptional<z.ZodBoolean>;
  targetSubscriptionPlanType: z.ZodOptional<z.ZodEnum<{ MONTHLY: "MONTHLY";
  UPFRONT: "UPFRONT";
  }>>;
  prices: z.ZodArray<z.ZodObject<{ territory: z.ZodString;
  pricePointId: z.ZodString;
  }, z.core.$strict>>;
  }, z.core.$strict>], "kind">>;
  existingProviderOfferIds: string[];
  }) | ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { productOfferId: string;
  providerOfferId: string;
  providerProductResourceId: string;
  productKind: AppStoreConnectProduct["kind"];
  } & { operation: "create_batch";
  batchId: string;
  providerEnvironment: AppleProviderEnvironment;
  requestedCodeCount: number;
  expirationDate: string;
  existingProviderBatchIds: string[];
  }) | ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { productOfferId: string;
  providerOfferId: string;
  providerProductResourceId: string;
  productKind: AppStoreConnectProduct["kind"];
  } & { operation: "refresh_offer";
  priceSchedule: AppStoreConnectOfferPriceDetails[];
  }) | ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { productOfferId: string;
  providerOfferId: string;
  providerProductResourceId: string;
  productKind: AppStoreConnectProduct["kind"];
  } & { operation: "deactivate_offer";
  priceSchedule: AppStoreConnectOfferPriceDetails[];
  }) | ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { productOfferId: string;
  providerOfferId: string;
  providerProductResourceId: string;
  productKind: AppStoreConnectProduct["kind"];
  } & { operation: "deactivate_batch";
  batchId: string;
  providerBatchId: string;
  });
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handlePreviewAgentProductOfferOperation.

GET /agent/apps/:appId/product-offer-operation-previews/:previewId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), previewId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.previewId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ preview: { id: string;
  operationType: "validate" | "sync" | "import_preview" | "import_apply" | "secret_rotate" | "connection_revoke" | "resource_mutation_preview" | "resource_mutation_apply" | "resource_destructive_preview" | "resource_destructive_apply";
  status: "failed" | "queued" | "running" | "succeeded" | "cancelled" | "expired";
  resourceType: string | null;
  resourceId: string | null;
  beforeState: ProviderConnectionOperationData | null;
  requestedState: ProviderConnectionOperationData | null;
  createdAt: string;
  expiresAt: string | null;
  };
  digest: string;
  expiresAt: string | null;
  plan: ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { operation: "create_offer";
  productOfferId: string;
  identifier: string;
  productId: string;
  productPriceId: string;
  providerProductId: string;
  providerProductResourceId: string;
  referenceName: string;
  exclusiveGroupIdentifier?: string;
  terms: z.infer<z.ZodDiscriminatedUnion<[z.ZodObject<{ kind: z.ZodLiteral<"in_app_purchase">;
  customerEligibilities: z.ZodArray<z.ZodEnum<{ NON_SPENDER: "NON_SPENDER";
  ACTIVE_SPENDER: "ACTIVE_SPENDER";
  CHURNED_SPENDER: "CHURNED_SPENDER";
  }>>;
  prices: z.ZodArray<z.ZodObject<{ territory: z.ZodString;
  pricePointId: z.ZodString;
  }, z.core.$strict>>;
  }, z.core.$strict>, z.ZodObject<{ kind: z.ZodLiteral<"subscription">;
  customerEligibilities: z.ZodArray<z.ZodEnum<{ NEW: "NEW";
  EXISTING: "EXISTING";
  EXPIRED: "EXPIRED";
  }>>;
  offerEligibility: z.ZodEnum<{ STACK_WITH_INTRO_OFFERS: "STACK_WITH_INTRO_OFFERS";
  REPLACE_INTRO_OFFERS: "REPLACE_INTRO_OFFERS";
  }>;
  duration: z.ZodEnum<{ THREE_DAYS: "THREE_DAYS";
  ONE_WEEK: "ONE_WEEK";
  TWO_WEEKS: "TWO_WEEKS";
  ONE_MONTH: "ONE_MONTH";
  TWO_MONTHS: "TWO_MONTHS";
  THREE_MONTHS: "THREE_MONTHS";
  SIX_MONTHS: "SIX_MONTHS";
  ONE_YEAR: "ONE_YEAR";
  }>;
  offerMode: z.ZodEnum<{ FREE_TRIAL: "FREE_TRIAL";
  PAY_AS_YOU_GO: "PAY_AS_YOU_GO";
  PAY_UP_FRONT: "PAY_UP_FRONT";
  }>;
  numberOfPeriods: z.ZodNumber;
  autoRenewEnabled: z.ZodOptional<z.ZodBoolean>;
  targetSubscriptionPlanType: z.ZodOptional<z.ZodEnum<{ MONTHLY: "MONTHLY";
  UPFRONT: "UPFRONT";
  }>>;
  prices: z.ZodArray<z.ZodObject<{ territory: z.ZodString;
  pricePointId: z.ZodString;
  }, z.core.$strict>>;
  }, z.core.$strict>], "kind">>;
  existingProviderOfferIds: string[];
  }) | ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { productOfferId: string;
  providerOfferId: string;
  providerProductResourceId: string;
  productKind: AppStoreConnectProduct["kind"];
  } & { operation: "create_batch";
  batchId: string;
  providerEnvironment: AppleProviderEnvironment;
  requestedCodeCount: number;
  expirationDate: string;
  existingProviderBatchIds: string[];
  }) | ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { productOfferId: string;
  providerOfferId: string;
  providerProductResourceId: string;
  productKind: AppStoreConnectProduct["kind"];
  } & { operation: "refresh_offer";
  priceSchedule: AppStoreConnectOfferPriceDetails[];
  }) | ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { productOfferId: string;
  providerOfferId: string;
  providerProductResourceId: string;
  productKind: AppStoreConnectProduct["kind"];
  } & { operation: "deactivate_offer";
  priceSchedule: AppStoreConnectOfferPriceDetails[];
  }) | ({ version: 1;
  kind: "apple_product_offer_mutation";
  workspaceId: string;
  appId: string;
  connectionId: string;
  accountId: string;
  appMappingId: string;
  externalAppId: string;
  connectionUpdatedAt: string;
  mappingUpdatedAt: string;
  providerFingerprint: string;
  blockers: Array<{ code: string;
  message: string;
  }>;
  } & { productOfferId: string;
  providerOfferId: string;
  providerProductResourceId: string;
  productKind: AppStoreConnectProduct["kind"];
  } & { operation: "deactivate_batch";
  batchId: string;
  providerBatchId: string;
  });
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentProductOfferOperationPreview.

GET /agent/apps/:appId/product-offer-operations/:operationId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), operationId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.operationId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  operation: { appId: string | null;
  workspaceId: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  status: "failed" | "queued" | "running" | "succeeded" | "cancelled" | "expired";
  completedAt: string | null;
  startedAt: string | null;
  connectionId: string;
  accountId: string | null;
  appMappingId: string | null;
  parentOperationId: string | null;
  actorPlatformUserId: string | null;
  operationType: "validate" | "sync" | "import_preview" | "import_apply" | "secret_rotate" | "connection_revoke" | "resource_mutation_preview" | "resource_mutation_apply" | "resource_destructive_preview" | "resource_destructive_apply";
  idempotencyKey: string | null;
  resourceType: string | null;
  resourceId: string | null;
  request: ProviderConnectionOperationData;
  beforeState: ProviderConnectionOperationData | null;
  requestedState: ProviderConnectionOperationData | null;
  providerResponse: ProviderConnectionOperationData | null;
  errorCode: string | null;
  errorMessage: string | null;
  queuedAt: string;
  expiresAt: string | null;
  appliedAt: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentProductOfferOperation.

GET /agent/apps/:appId/app-store-reviews

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: from, to, timeZone, path.appId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ reviews: AppStoreReview[];
  complete: boolean;
  fetchedAt: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentAppReviews.

GET /agent/app-store-reports/sources

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ sources: { oneAppId: string;
  appleAppId: string;
  name: string;
  bundleId: string | null;
  sku: string | null;
  vendorNumber: string;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentAppStoreReportingSources.

GET /agent/apps/:appId/app-store-reports/analytics/requests

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

"ONGOING" | "ONE_TIME_SNAPSHOT" | undefined

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  requests: AnalyticsReportRequest[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentAppStoreAnalyticsRequests.

GET /agent/apps/:appId/app-store-reports/analytics/reports

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

string

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  reports: AnalyticsReport[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentAppStoreAnalyticsReports.

GET /agent/apps/:appId/app-store-reports/analytics/instances

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ requestId: string;
  reportId: string;
  granularity?: "MONTHLY" | "DAILY" | "WEEKLY" | undefined;
  processingDate?: string | undefined;
  }

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  instances: AnalyticsReportInstance[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentAppStoreAnalyticsInstances.

GET /agent/apps/:appId/app-store-reports/analytics/segments

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ requestId: string;
  reportId: string;
  instanceId: string;
  }

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  segments: { id: string;
  checksum?: string;
  sizeInBytes?: number;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentAppStoreAnalyticsSegments.

GET /agent/apps/:appId/app-store-reports/analytics/download

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ requestId: string;
  reportId: string;
  instanceId: string;
  segmentId: string;
  }

Response

A report download response. Preserve the returned content type and stream the payload; do not parse a binary/compressed download as JSON.

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleDownloadAgentAppStoreAnalyticsSegment.

GET /agent/apps/:appId/app-store-reports/sales

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ reportType: "SALES" | "PRE_ORDER" | "SUBSCRIPTION" | "SUBSCRIPTION_EVENT";
  reportSubType: "SUMMARY" | "DETAILED" | "OPT_IN";
  frequency: "MONTHLY" | "DAILY" | "WEEKLY" | "YEARLY";
  reportDate: string;
  version: string;
  }

Response

A report download response. Preserve the returned content type and stream the payload; do not parse a binary/compressed download as JSON.

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleDownloadAgentAppStoreSalesReport.

GET /agent/apps/:appId/support/threads

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ status?: "open" | "resolved" | undefined;
  category?: "message" | "bug" | "feature" | undefined;
  needsReply?: "false" | "true" | undefined;
  limit?: unknown;
  cursor?: string | undefined;
  }

Response

JSON response shape

{ threads: WorkspaceSupportThreadListItem[];
  nextCursor: string | null;
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentSupportThreads.

GET /agent/apps/:appId/support/threads/:threadId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), threadId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.threadId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  thread: SupportThreadDetailResponse & { projectId: string;
  messages: Array<SupportMessageResponse & { customerReadAt: string | null;
  }>;
  appId: string;
  appName: string;
  environment: "test" | "live";
  labels: WorkspaceSupportLabel[];
  workspaceMarkedUnreadAt: string | null;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentSupportThread.

GET /agent/apps/:appId/support/threads/:threadId/investigation

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), threadId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ resource: "subscriptions" | "notification_deliveries" | "events" | "transactions" | "messages" | "entitlement_grants" | "related_threads" | "related_thread" | "crash_groups" | "crash_group";
  search: string | null;
  offset: number;
  eventId: string | null;
  appIndex: number;
  threadId: string;
  }

{ [x: string]: unknown;
  appIndex: number;
  threadId: string;
  }

{ reply: string;
  appIndex: number;
  threadId: string;
  }

{ attachmentId: string;
  offset: number;
  appIndex: number;
  threadId: string;
  }

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  evidence: AskOneContentBlock[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleAgentSupportInvestigation.

GET /agent/apps/:appId/support/threads/:threadId/attachments/:attachmentId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), threadId (string), attachmentId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ offset?: unknown;
  length?: unknown;
  }

Response

JSON response shape

{ appId: string;
  threadId: string;
  attachmentId: string;
  fileName: string;
  contentType: string;
  byteSize: number;
  offset: number;
  returnedBytes: number;
  hasMore: boolean;
  dataBase64: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleReadAgentSupportAttachment.

POST /agent/apps/:appId/support/threads/:threadId/notes

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), threadId (string). Every target must belong to the authenticated app or workspace.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ body: string;
  clientMessageId?: string | undefined;
  }

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  thread: SupportThreadDetailResponse & { projectId: string;
  messages: Array<SupportMessageResponse & { customerReadAt: string | null;
  }>;
  appId: string;
  appName: string;
  environment: "test" | "live";
  labels: WorkspaceSupportLabel[];
  workspaceMarkedUnreadAt: string | null;
  };
  message: SupportMessageResponse;
  created: boolean;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleCreateAgentSupportNote.

POST /agent/action-plans

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ action: string;
  request: Record<string, unknown>;
  plan: Record<string, unknown>;
  expiresAt: string;
  appId?: string | null | undefined;
  environment?: "test" | "live" | null | undefined;
  }

{ operation: "delete";
  resource?: "product" | undefined;
  id?: string | undefined;
  identifier?: string | undefined;
  key?: string | undefined;
  }

{ name?: string | undefined;
  emailPasswordEnabled?: boolean | undefined;
  magicLinkEnabled?: boolean | undefined;
  emailChangeMode?: "verification_link" | "password_confirmed" | undefined;
  allowedRedirectUris?: string[] | undefined;
  accountDeletion?: { mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  } | undefined;
  restoreDeletedCredentialsOnSignup?: boolean | undefined;
  expectedAccountDeletion?: { mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  } | null | undefined;
  expectedAccountDeletionConfigurationStatus?: "invalid" | "absent" | "configured" | undefined;
  expectedAccountDeletionFingerprint?: string | undefined;
  expectedRestoreDeletedCredentialsOnSignup?: boolean | null | undefined;
  expectedAppUpdatedAt?: string | undefined;
  }

{ enabled: boolean;
  appVersions: string[];
  customerIds: string[];
  captureHours: number;
  retentionDays: number;
  maxCaptures: number;
  successSampleLimit?: number | undefined;
  }

{ name?: string | undefined;
  appearance?: unknown;
  bundleId?: string | null | undefined;
  webOrigin?: string | null | undefined;
  } | { emailPasswordEnabled?: boolean | undefined;
  magicLinkEnabled?: boolean | undefined;
  redirectUrls?: string[] | undefined;
  sessionMode?: "persistent" | "rolling" | "absolute" | undefined;
  sessionInactivityDays?: number | null | undefined;
  sessionAbsoluteDays?: number | null | undefined;
  recentAuthenticationWindowSeconds?: number | null | undefined;
  passwordMaxAgeDays?: number | null | undefined;
  accountDeletion?: { mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  } | undefined;
  restoreDeletedCredentialsOnSignup?: boolean | undefined;
  emailChangeMode?: "verification_link" | "password_confirmed" | undefined;
  } | { contactMode: "optional_email" | "required_email" | "authenticated_account";
  emailVerificationMode: "none" | "optional" | "required";
  } | { operation: "create";
  values: { identifier: string;
  name: string;
  description?: string | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { name?: string | undefined;
  description?: string | null | undefined;
  };
  } | { operation: "create";
  values: { identifier: string;
  name: string;
  title?: string | null | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  subject?: string | null | undefined;
  variables?: string | Record<string, unknown> | null | undefined;
  channel?: "email" | "push" | undefined;
  locale?: string | undefined;
  bodyText?: string | null | undefined;
  contentSource?: string | null | undefined;
  contentHtml?: string | undefined;
  dataPayload?: string | Record<string, unknown> | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { title?: string | null | undefined;
  name?: string | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  subject?: string | null | undefined;
  variables?: string | Record<string, unknown> | null | undefined;
  locale?: string | undefined;
  bodyText?: string | null | undefined;
  contentSource?: string | null | undefined;
  contentHtml?: string | undefined;
  dataPayload?: string | Record<string, unknown> | null | undefined;
  };
  } | { operation: "create";
  values: { identifier: string;
  name: string;
  source?: "manual" | "auth" | "event" | "billing" | "api" | undefined;
  eventType?: string | null | undefined;
  enabled?: boolean | undefined;
  delaySeconds?: number | undefined;
  cooldownSeconds?: number | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { identifier?: string | undefined;
  name?: string | undefined;
  source?: "manual" | "auth" | "event" | "billing" | "api" | undefined;
  eventType?: string | null | undefined;
  enabled?: boolean | undefined;
  delaySeconds?: number | undefined;
  cooldownSeconds?: number | undefined;
  };
  } | { id: string;
  triggerId: string | null;
  } | { operation: "create";
  values: { name: string;
  url: string;
  enabled?: boolean | undefined;
  eventTypes?: ("identity_attached" | "signin" | "signup" | "signout" | "paywall_shown" | "paywall_product_selected" | "checkout_started" | "purchase_started" | "customer_first_seen" | "email_changed" | "password_changed" | "account_deleted" | "purchase_revoked" | "purchase_refunded" | "billing_operation_failed" | "apple_access_observed" | "subscription_cancellation_scheduled" | "subscription_reactivated" | "subscription_started" | "purchase_verified" | "app_activity" | "session_start" | "session_end" | "deep_link_open" | "milestone_recorded" | "onboarding_step_viewed" | "paywall_requested" | "paywall_closed" | "paywall_screen_changed" | "product_offer_redemption_updated" | "paywall_checkout_requested" | "purchase_already_entitled" | "purchase_cancelled" | "purchase_pending" | "purchase_failed" | "purchase_sync_failed" | "purchase_succeeded" | "restore_started" | "restore_succeeded" | "restore_failed" | "sdk_access_observed" | "restore_operation_updated" | "apple_order_recovery_succeeded" | "surface_impression" | "subscription_trial_started" | "subscription_trial_converted" | "purchase_refund_reversed" | "purchase_refund_declined" | "subscription_renewed" | "subscription_renewal_extended" | "subscription_renewal_preference_changed" | "subscription_renewal_failed" | "subscription_expired" | "subscription_cancelled" | "subscription_paused" | "subscription_resumed" | "price_change_detected" | "grace_period_started" | "grace_period_ended" | "purchase_refund_requested" | "offer_redeemed" | "entitlement_granted" | "entitlement_revoked" | "notification_sent" | "notification_opened" | "webhook_delivered" | "webhook_failed" | "customer_note_added" | "app_crash_reported" | "app_error_reported")[] | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { name?: string | undefined;
  url?: string | undefined;
  enabled?: boolean | undefined;
  eventTypes?: ("identity_attached" | "signin" | "signup" | "signout" | "paywall_shown" | "paywall_product_selected" | "checkout_started" | "purchase_started" | "customer_first_seen" | "email_changed" | "password_changed" | "account_deleted" | "purchase_revoked" | "purchase_refunded" | "billing_operation_failed" | "apple_access_observed" | "subscription_cancellation_scheduled" | "subscription_reactivated" | "subscription_started" | "purchase_verified" | "app_activity" | "session_start" | "session_end" | "deep_link_open" | "milestone_recorded" | "onboarding_step_viewed" | "paywall_requested" | "paywall_closed" | "paywall_screen_changed" | "product_offer_redemption_updated" | "paywall_checkout_requested" | "purchase_already_entitled" | "purchase_cancelled" | "purchase_pending" | "purchase_failed" | "purchase_sync_failed" | "purchase_succeeded" | "restore_started" | "restore_succeeded" | "restore_failed" | "sdk_access_observed" | "restore_operation_updated" | "apple_order_recovery_succeeded" | "surface_impression" | "subscription_trial_started" | "subscription_trial_converted" | "purchase_refund_reversed" | "purchase_refund_declined" | "subscription_renewed" | "subscription_renewal_extended" | "subscription_renewal_preference_changed" | "subscription_renewal_failed" | "subscription_expired" | "subscription_cancelled" | "subscription_paused" | "subscription_resumed" | "price_change_detected" | "grace_period_started" | "grace_period_ended" | "purchase_refund_requested" | "offer_redeemed" | "entitlement_granted" | "entitlement_revoked" | "notification_sent" | "notification_opened" | "webhook_delivered" | "webhook_failed" | "customer_note_added" | "app_crash_reported" | "app_error_reported")[] | undefined;
  };
  } | { id: string;
  } | { id: string;
  } | { name?: string | undefined;
  slug?: string | undefined;
  } | { id: string;
  name: string;
  } | { id: string;
  role: "owner" | "admin" | "member";
  } | { id: string;
  } | { id: string;
  values: { name?: string | undefined;
  status?: "active" | "disabled" | undefined;
  };
  } | { id: string;
  connectionId: string;
  values: { externalAppName?: string | undefined;
  enabled?: boolean | undefined;
  };
  } | { enabled: boolean;
  replaceCredentials: boolean;
  publicConfig: { accountId: string;
  sendingDomain: string;
  fromAddress: string;
  fromName?: string | undefined;
  replyTo?: string | undefined;
  };
  } | { enabled: boolean;
  replaceCredentials: false;
  useExistingBinding: true;
  publicConfig: { fromAddress: string;
  fromName?: string | undefined;
  replyTo?: string | undefined;
  };
  } | { operation: "create";
  values: { title: string;
  color: "slate" | "blue" | "green" | "amber" | "rose" | "violet";
  };
  } | { operation: "update";
  id: string;
  values: { title: string;
  color: "slate" | "blue" | "green" | "amber" | "rose" | "violet";
  };
  } | { id: string;
  status: "open" | "resolved";
  } | { id: string;
  read: boolean;
  } | { id: string;
  labelIds: string[];
  }

{ id: string;
  triggerId: string | null;
  }

{ enabled: boolean;
  replaceCredentials: boolean;
  publicConfig: { accountId: string;
  sendingDomain: string;
  fromAddress: string;
  fromName?: string | undefined;
  replyTo?: string | undefined;
  };
  } | { enabled: boolean;
  replaceCredentials: false;
  useExistingBinding: true;
  publicConfig: { fromAddress: string;
  fromName?: string | undefined;
  replyTo?: string | undefined;
  };
  }

{ operation: "create";
  values: { identifier: string;
  name: string;
  title?: string | null | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  subject?: string | null | undefined;
  variables?: string | Record<string, unknown> | null | undefined;
  channel?: "email" | "push" | undefined;
  locale?: string | undefined;
  bodyText?: string | null | undefined;
  contentSource?: string | null | undefined;
  contentHtml?: string | undefined;
  dataPayload?: string | Record<string, unknown> | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { title?: string | null | undefined;
  name?: string | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  subject?: string | null | undefined;
  variables?: string | Record<string, unknown> | null | undefined;
  locale?: string | undefined;
  bodyText?: string | null | undefined;
  contentSource?: string | null | undefined;
  contentHtml?: string | undefined;
  dataPayload?: string | Record<string, unknown> | null | undefined;
  };
  }

{ id: string;
  labelIds: string[];
  }

{ definition: { key: string;
  revision: number;
  label: string;
  unit: "duration" | "count" | "bytes" | "credits";
  scale: number;
  allowedSources: ("server" | "client")[];
  dimensionKeys: string[];
  entitlementId: string | null;
  isActive: boolean;
  };
  }

{ definition: { key: string;
  allowedValues: string[];
  };
  }

{ policy: "account" | "app_store";
  preservedImport?: { revision: string;
  enabled: boolean;
  entitlementIdentifier: string;
  members: { grantId: string;
  customerId: string;
  }[];
  } | null | undefined;
  appPurchaseRules?: { entitlementIdentifiers: string[];
  originalAppVersionFormat?: "integer" | "dotted" | undefined;
  originalAppVersionBefore?: string | undefined;
  originalPurchaseDateBefore?: string | undefined;
  }[] | undefined;
  }

"account" | "app_store"

{ operation: "create";
  values: { identifier: string;
  name: string;
  status: "active" | "inactive" | "archived";
  config: unknown;
  delivery: { maxPresentationsPerCustomer: number;
  cooldownSeconds: number;
  allowManualRepeats: boolean;
  };
  description?: string | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { status?: "active" | "inactive" | "archived" | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  config?: unknown;
  delivery?: { maxPresentationsPerCustomer: number;
  cooldownSeconds: number;
  allowManualRepeats: boolean;
  } | undefined;
  };
  } | { operation: "new_round";
  id: string;
  }

{ provider: "apple_app_store_connect";
  category: "catalog";
  resource: "app_store_pricing_plan";
  operation: "apply";
  providerPlanId: string;
  digest: string;
  }

{ provider: "google";
  category: "auth";
  publicConfig: { clientId: string;
  };
  enabled?: boolean | undefined;
  } | { provider: "apple";
  category: "auth";
  publicConfig: { clientId: string;
  teamId?: string | undefined;
  keyId?: string | undefined;
  };
  enabled?: boolean | undefined;
  }

{ operation: "update";
  resource: "product_offer";
  id: string;
  values: { paused: boolean;
  };
  }

{ operation: "update" | "delete" | "create";
  resource?: "paywall" | undefined;
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  config?: unknown;
  status?: "active" | "inactive" | "archived" | undefined;
  isDefault?: boolean | undefined;
  productIdentifiers?: string[] | undefined;
  } | undefined;
  } | { operation: "update";
  resource: "placement_fallback";
  placementIdentifier: string;
  fallbackPaywallIdentifier: string;
  } | { operation: "upsert";
  resource: "placement";
  identifier: string;
  name: string;
  fallbackPaywallIdentifier: string;
  description?: string | null | undefined;
  } | { operation: "update" | "delete" | "create";
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  surfaceType?: string | undefined;
  status?: "active" | "inactive" | "archived" | undefined;
  enabled?: boolean | undefined;
  config?: unknown;
  } | undefined;
  }

{ operation: "update" | "delete" | "create";
  resource?: "paywall" | undefined;
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  config?: unknown;
  status?: "active" | "inactive" | "archived" | undefined;
  isDefault?: boolean | undefined;
  productIdentifiers?: string[] | undefined;
  } | undefined;
  }

{ operation: "upsert";
  resource: "placement";
  identifier: string;
  name: string;
  fallbackPaywallIdentifier: string;
  description?: string | null | undefined;
  }

{ operation: "update" | "delete" | "create";
  id?: string | undefined;
  expectedUpdatedAt?: string | undefined;
  values?: { identifier?: string | null | undefined;
  name?: string | undefined;
  subject?: string | null | undefined;
  channel?: "email" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  locale?: string | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  contentSource?: string | undefined;
  contentHtml?: string | undefined;
  variables?: unknown;
  } | undefined;
  }

{ providerTransactionId: string;
  billingTransactionId: string;
  subscriptionId: string;
  customerId: string;
  canonicalEventId: string;
  expectedPurchasedAt: string;
  expectedPeriodEnd: string;
  duplicateEventIds?: string[] | undefined;
  }

{ customerId: string;
  grantId: string;
  entitlementIdentifier: string;
  sourceBillingTransactionId: string | null;
  expectedRevokedAt: null;
  }

{ entitlementId: string;
  startsAt: unknown;
  endsAt: unknown;
  customerId: string;
  expectedPolicy: "account" | "app_store";
  source: "manual";
  applePurchaserLinkId?: string | undefined;
  note?: string | undefined;
  }

{ entitlementIdentifiers: string[];
  originalAppVersionFormat?: "integer" | "dotted" | undefined;
  originalAppVersionBefore?: string | undefined;
  originalPurchaseDateBefore?: string | undefined;
  }[]

{ authUserId: string;
  normalizedEmail: string;
  expectedUpdatedAt: string;
  expectedProviders: { providerId: string;
  accountCount: number;
  hasPassword: boolean;
  passwordUpdatedAt: string | null;
  }[];
  expectedCustomerCount: 0;
  expectedWorkspaceCustomerCount: 0;
  expectedSessionCount: number;
  expectedActiveSessionCount: 0;
  expectedChallengeCount: number;
  expectedActiveChallengeCount: 0;
  }

Validation schemas: createAgentActionPlanSchema in the downloadable schema registry.

Response

JSON response shape

{ plan: { appId: string | null;
  environment: "test" | "live" | null;
  platformUserId: string;
  workspaceId: string;
  agentAccessTokenId: string;
  action: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  request: Record<string, unknown>;
  expiresAt: string;
  appliedAt: string | null;
  plan: Record<string, unknown>;
  };
  requiredScope: "workspace:read" | "workspace:write" | "apps:read" | "apps:write" | "reports:read" | "catalog:read" | "catalog:write" | "paywalls:read" | "paywalls:write" | "messaging:read" | "messaging:write" | "campaigns:read" | "campaigns:write" | "remote_config:read" | "remote_config:write" | "surfaces:read" | "surfaces:write" | "surveys:read" | "surveys:write" | "rules:read" | "rules:write" | "webhooks:read" | "webhooks:write" | "integrations:read" | "integrations:write" | "auth:read" | "auth:write" | "audit:read";
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleCreateAgentActionPlan.

POST /agent/action-plans/:planId/apply

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: planId (string). Every target must belong to the authenticated app or workspace.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ secrets?: Record<string, unknown> | undefined;
  } | undefined

{ operation: "delete";
  resource?: "product" | undefined;
  id?: string | undefined;
  identifier?: string | undefined;
  key?: string | undefined;
  }

{ operation: "create";
  values: { identifier: string;
  name: string;
  status: "active" | "inactive" | "archived";
  config: unknown;
  delivery: { maxPresentationsPerCustomer: number;
  cooldownSeconds: number;
  allowManualRepeats: boolean;
  };
  description?: string | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { status?: "active" | "inactive" | "archived" | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  config?: unknown;
  delivery?: { maxPresentationsPerCustomer: number;
  cooldownSeconds: number;
  allowManualRepeats: boolean;
  } | undefined;
  };
  } | { operation: "new_round";
  id: string;
  }

{ updatedAt: string;
  collectionRound: number;
  }

{ definition: { key: string;
  revision: number;
  label: string;
  unit: "duration" | "count" | "bytes" | "credits";
  scale: number;
  allowedSources: ("server" | "client")[];
  dimensionKeys: string[];
  entitlementId: string | null;
  isActive: boolean;
  };
  }

{ definition: { key: string;
  allowedValues: string[];
  };
  }

{ projectId: string;
  name: string;
  platform: "ios" | "android" | "web" | "windows" | "macos";
  bundleId?: string | null | undefined;
  webOrigin?: string | null | undefined;
  }

{ name?: string | undefined;
  emailPasswordEnabled?: boolean | undefined;
  magicLinkEnabled?: boolean | undefined;
  emailChangeMode?: "verification_link" | "password_confirmed" | undefined;
  allowedRedirectUris?: string[] | undefined;
  accountDeletion?: { mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  } | undefined;
  restoreDeletedCredentialsOnSignup?: boolean | undefined;
  expectedAccountDeletion?: { mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  } | null | undefined;
  expectedAccountDeletionConfigurationStatus?: "invalid" | "absent" | "configured" | undefined;
  expectedAccountDeletionFingerprint?: string | undefined;
  expectedRestoreDeletedCredentialsOnSignup?: boolean | null | undefined;
  expectedAppUpdatedAt?: string | undefined;
  }

{ provider: "apple_app_store_connect";
  category: "catalog";
  resource: "app_store_pricing_plan";
  operation: "apply";
  providerPlanId: string;
  digest: string;
  } | { provider: "google";
  category: "auth";
  publicConfig: { clientId: string;
  };
  enabled?: boolean | undefined;
  } | { provider: "apple";
  category: "auth";
  publicConfig: { clientId: string;
  teamId?: string | undefined;
  keyId?: string | undefined;
  };
  enabled?: boolean | undefined;
  } | { provider: "apple_ads";
  category: "acquisition";
  resource: "workspace_provider_connection";
  operation: "validate";
  connectionId: string;
  } | { provider: "apple_ads";
  category: "acquisition";
  resource: "workspace_provider_connection";
  operation: "map_app";
  connectionId: string;
  accountExternalId: string;
  externalAppId: string;
  settings: { [x: string]: unknown;
  acquisition?: { roasTargetBps?: number | undefined;
  roasWindowDays?: number | undefined;
  paybackTargetDays?: number | undefined;
  minimumAttributedAcquisitionOpens?: number | undefined;
  minimumFirstTimePayers?: number | undefined;
  scaleThresholdBps?: number | undefined;
  reduceThresholdBps?: number | undefined;
  } | undefined;
  appleAds?: { basicPromotionIds?: string[] | undefined;
  } | undefined;
  };
  externalAppName?: string | undefined;
  } | { provider: "apple_ads";
  category: "acquisition";
  resource: "workspace_provider_connection";
  operation: "backfill_attribution";
  connectionId: string;
  limit?: number | undefined;
  } | { provider: "apple_ads";
  category: "acquisition";
  resource: "workspace_provider_connection";
  operation: "reconcile";
  connectionId: string;
  fromDate?: string | undefined;
  } | { provider: "apple_ads";
  category: "acquisition";
  resource: "workspace_provider_connection";
  operation: "sync";
  connectionId: string;
  kind: "incremental" | "backfill";
  asOfDate?: string | undefined;
  } | { provider: "apple_ads";
  category: "acquisition";
  resource: "workspace_provider_connection";
  operation: "cancel_sync";
  connectionId: string;
  operationId: string;
  } | { provider: "apns";
  category: "messaging";
  publicConfig: { bundleId: string;
  environment: "production" | "development";
  environments?: ("production" | "development")[] | undefined;
  keyId?: string | undefined;
  teamId?: string | undefined;
  };
  enabled?: boolean | undefined;
  } | { provider: "stripe";
  category: "payments";
  enabled?: boolean | undefined;
  publicConfig?: { publishableKey?: string | undefined;
  } | undefined;
  } | { provider: "apple_app_store_connect";
  category: "catalog";
  resource: "product_offer_operation";
  operation: "apply";
  providerPreviewId: string;
  digest: string;
  }

{ previewId: string;
  digest: string;
  }

{ stripeSecretKey: string;
  stripeWebhookSecret?: string | undefined;
  }

{ keyId: string;
  teamId: string;
  apnsPrivateKey: string;
  }

{ operation: "update";
  resource: "product_offer";
  id: string;
  values: { paused: boolean;
  };
  } | { operation: "update";
  resource: "product_price";
  id?: string | undefined;
  productIdentifier?: string | undefined;
  provider?: "stripe" | "apple_app_store" | "google_play" | "microsoft_store" | undefined;
  values?: { active?: boolean | undefined;
  providerProductId?: string | undefined;
  providerPriceId?: string | null | undefined;
  currency?: string | null | undefined;
  unitAmount?: number | null | undefined;
  billingPeriod?: "month" | "year" | null | undefined;
  trialConfig?: Record<string, unknown> | undefined;
  familySharingEnabled?: boolean | undefined;
  isDefault?: boolean | undefined;
  priority?: number | undefined;
  } | undefined;
  } | { operation: "update" | "delete" | "create";
  resource: "product";
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  pricingType?: "subscription" | "non_consumable" | "consumable" | "free" | undefined;
  pricingPeriod?: "month" | "year" | null | undefined;
  variants?: { provider: "stripe" | "apple_app_store" | "google_play" | "microsoft_store";
  providerProductId: string;
  trialConfig?: Record<string, unknown> | undefined;
  familySharingEnabled?: boolean | undefined;
  }[] | undefined;
  entitlementIdentifiers?: string[] | undefined;
  } | undefined;
  } | { operation: "create";
  resource: "product_price";
  values: { productId: string;
  provider: "stripe" | "apple_app_store" | "google_play" | "microsoft_store";
  providerProductId: string;
  platform?: "ios" | "android" | "web" | "windows" | "macos" | null | undefined;
  providerPriceId?: string | null | undefined;
  currency?: string | null | undefined;
  unitAmount?: number | null | undefined;
  billingPeriod?: "month" | "year" | null | undefined;
  trialConfig?: { version: "1.0";
  enabled: false;
  } | { version: "1.0";
  enabled: true;
  trialPeriodDays: number;
  } | { version: "1.0";
  enabled: true;
  appleSubscriptionGroupId: string;
  } | undefined;
  familySharingEnabled?: boolean | undefined;
  active?: boolean | undefined;
  isDefault?: boolean | undefined;
  priority?: number | undefined;
  };
  }

{ operation: "update" | "delete" | "create";
  resource?: "paywall" | undefined;
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  config?: unknown;
  status?: "active" | "inactive" | "archived" | undefined;
  isDefault?: boolean | undefined;
  productIdentifiers?: string[] | undefined;
  } | undefined;
  } | { operation: "update";
  resource: "placement_fallback";
  placementIdentifier: string;
  fallbackPaywallIdentifier: string;
  } | { operation: "upsert";
  resource: "placement";
  identifier: string;
  name: string;
  fallbackPaywallIdentifier: string;
  description?: string | null | undefined;
  }

{ operation: "update" | "delete" | "create";
  id?: string | undefined;
  expectedUpdatedAt?: string | undefined;
  values?: { identifier?: string | null | undefined;
  name?: string | undefined;
  subject?: string | null | undefined;
  channel?: "email" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  locale?: string | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  contentSource?: string | undefined;
  contentHtml?: string | undefined;
  variables?: unknown;
  } | undefined;
  }

{ operation: "update" | "delete" | "create";
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  priority?: number | undefined;
  status?: "active" | "inactive" | "archived" | undefined;
  isActive?: boolean | undefined;
  placements?: string[] | undefined;
  audiences?: { identifier: string;
  name: string;
  id?: string | undefined;
  description?: string | null | undefined;
  sortOrder?: number | undefined;
  enabled?: boolean | undefined;
  audienceRule?: Record<string, unknown> | null | undefined;
  cooldownSeconds?: number | undefined;
  maxMatchesPerCustomer?: number | null | undefined;
  maxMatchesPerWindow?: number | null | undefined;
  windowSeconds?: number | null | undefined;
  variants?: { identifier: string;
  name: string;
  id?: string | undefined;
  targetType?: "paywall" | "in_app_surface" | "survey" | "custom" | "none" | undefined;
  surveyId?: string | undefined;
  paywallId?: string | undefined;
  paywallIdentifier?: string | undefined;
  inAppSurfaceId?: string | undefined;
  inAppSurfaceIdentifier?: string | undefined;
  trafficPercent?: number | undefined;
  allocationPercent?: number | undefined;
  isControl?: boolean | undefined;
  payload?: Record<string, unknown> | null | undefined;
  }[] | undefined;
  }[] | undefined;
  variants?: { identifier: string;
  name: string;
  id?: string | undefined;
  targetType?: "paywall" | "in_app_surface" | "survey" | "custom" | "none" | undefined;
  surveyId?: string | undefined;
  paywallId?: string | undefined;
  paywallIdentifier?: string | undefined;
  inAppSurfaceId?: string | undefined;
  inAppSurfaceIdentifier?: string | undefined;
  trafficPercent?: number | undefined;
  allocationPercent?: number | undefined;
  isControl?: boolean | undefined;
  payload?: Record<string, unknown> | null | undefined;
  }[] | undefined;
  } | undefined;
  }

{ operation: "update" | "delete" | "upsert";
  key: string;
  value?: string | undefined;
  description?: string | null | undefined;
  }

{ operation: "update" | "delete" | "create";
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  surfaceType?: string | undefined;
  status?: "active" | "inactive" | "archived" | undefined;
  enabled?: boolean | undefined;
  config?: unknown;
  } | undefined;
  }

{ operation: "update" | "delete" | "create";
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { name?: string | undefined;
  identifier?: string | undefined;
  enabled?: boolean | undefined;
  eventTypes?: string[] | null | undefined;
  trigger?: "event" | "sdk_call" | undefined;
  rule?: Record<string, unknown> | undefined;
  actionConfig?: Record<string, unknown> | null | undefined;
  webhookConfig?: { url: string;
  method?: "POST" | "PUT" | "PATCH" | undefined;
  headers?: Record<string, string> | undefined;
  } | null | undefined;
  } | undefined;
  }

{ operation: "update" | "delete" | "create";
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  type?: "action" | "webhook" | "check" | undefined;
  trigger?: "event" | "sdk_call" | undefined;
  rule?: Record<string, unknown> | undefined;
  eventTypes?: string[] | null | undefined;
  actionConfig?: Record<string, unknown> | null | undefined;
  webhookConfig?: { url: string;
  method?: "POST" | "PUT" | "PATCH" | undefined;
  headers?: Record<string, string> | undefined;
  } | null | undefined;
  enabled?: boolean | undefined;
  } | undefined;
  }

{ provider: "apple";
  eventIds: string[];
  }

{ providerTransactionId: string;
  billingTransactionId: string;
  subscriptionId: string;
  customerId: string;
  canonicalEventId: string;
  expectedPurchasedAt: string;
  expectedPeriodEnd: string;
  duplicateEventIds?: string[] | undefined;
  }

{ entitlementId: string;
  startsAt: unknown;
  endsAt: unknown;
  customerId: string;
  expectedPolicy: "account" | "app_store";
  source: "manual";
  applePurchaserLinkId?: string | undefined;
  note?: string | undefined;
  }

{ customerId: string;
  grantId: string;
  entitlementIdentifier: string;
  sourceBillingTransactionId: string | null;
  expectedRevokedAt: null;
  }

{ authUserId: string;
  normalizedEmail: string;
  expectedUpdatedAt: string;
  expectedProviders: { providerId: string;
  accountCount: number;
  hasPassword: boolean;
  passwordUpdatedAt: string | null;
  }[];
  expectedCustomerCount: 0;
  expectedWorkspaceCustomerCount: 0;
  expectedSessionCount: number;
  expectedActiveSessionCount: 0;
  expectedChallengeCount: number;
  expectedActiveChallengeCount: 0;
  }

Response

JSON response shape

{ plan: { appId: string | null;
  environment: "test" | "live" | null;
  platformUserId: string;
  workspaceId: string;
  agentAccessTokenId: string;
  action: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  request: Record<string, unknown>;
  expiresAt: string;
  appliedAt: string | null;
  plan: Record<string, unknown>;
  };
  result: Record<string, unknown>;
  requiredScope: "workspace:read" | "workspace:write" | "apps:read" | "apps:write" | "reports:read" | "catalog:read" | "catalog:write" | "paywalls:read" | "paywalls:write" | "messaging:read" | "messaging:write" | "campaigns:read" | "campaigns:write" | "remote_config:read" | "remote_config:write" | "surfaces:read" | "surfaces:write" | "surveys:read" | "surveys:write" | "rules:read" | "rules:write" | "webhooks:read" | "webhooks:write" | "integrations:read" | "integrations:write" | "auth:read" | "auth:write" | "audit:read";
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleApplyAgentActionPlan.

GET /agent/action-plans/:planId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: planId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.planId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ plan: { appId: string | null;
  environment: "test" | "live" | null;
  platformUserId: string;
  workspaceId: string;
  agentAccessTokenId: string;
  action: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  request: Record<string, unknown>;
  expiresAt: string;
  appliedAt: string | null;
  plan: Record<string, unknown>;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentActionPlan.

GET /agent/apps/:appId/usage/definitions

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ appId: string;
  }

Response

JSON response shape

{ categories: { key: string;
  allowedValues: string[] | null;
  }[];
  entitlements: { id: string;
  name: string;
  }[];
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  };
  metrics: { key: string;
  revision: number;
  label: string;
  unit: "duration" | "count" | "bytes" | "credits";
  scale: number;
  allowedSources: ("server" | "client")[];
  dimensionKeys: string[];
  entitlementId: string | null;
  isActive: boolean;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentUsageDefinitions.

GET /agent/apps/:appId/refunds/requests

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ appId: string;
  transactionId?: string | undefined;
  cursor?: string | undefined;
  }

{ version: number;
  mode: "disabled" | "preview";
  disclosureVersion: string;
  effectiveAt: string;
  consentProcessEvidence: string;
  eligibleCustomerCreatedAfter: string | null;
  rules: { id: string;
  metric: { key: string;
  definitionRevision: number;
  };
  minimumScaledValue: string;
  deliveryStatus: "DELIVERED" | "UNDELIVERED_QUALITY_ISSUE" | "UNDELIVERED_WRONG_ITEM" | "UNDELIVERED_SERVER_OUTAGE" | "UNDELIVERED_OTHER";
  deliveryEvidence: string;
  sampleContentProvided: boolean;
  sampleEvidence: string;
  refundPreference: "GRANT_FULL" | "DECLINE";
  }[];
  }

Response

JSON response shape

{ requests: { id: string;
  transactionId: string | null;
  customerId: string | null;
  deadlineAt: string;
  receivedAt: string;
  status: "failed" | "sent" | "pending" | "skipped_no_consent_or_disabled";
  snapshot: Record<string, unknown> | null;
  }[];
  nextCursor: string | null;
  sendingEnabled: boolean;
  policy: { version: number;
  mode: "disabled" | "preview";
  disclosureVersion: string;
  effectiveAt: string;
  consentProcessEvidence: string;
  eligibleCustomerCreatedAfter: string | null;
  rules: { id: string;
  metric: { key: string;
  definitionRevision: number;
  };
  minimumScaledValue: string;
  deliveryStatus: "DELIVERED" | "UNDELIVERED_QUALITY_ISSUE" | "UNDELIVERED_WRONG_ITEM" | "UNDELIVERED_SERVER_OUTAGE" | "UNDELIVERED_OTHER";
  deliveryEvidence: string;
  sampleContentProvided: boolean;
  sampleEvidence: string;
  refundPreference: "GRANT_FULL" | "DECLINE";
  }[];
  } | null;
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentRefundRequests.

POST /agent/admin/query

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ resource: "projects" | "entitlements" | "api_keys" | "support_labels" | "notification_senders" | "webhook_destinations" | "webhook_deliveries" | "notification_templates" | "notification_triggers" | "workspace" | "members" | "app_settings" | "auth_settings" | "support_settings" | "agent_tokens" | "provider_connections" | "provider_accounts" | "provider_mappings" | "support_thread_state" | "email_integration";
  appId?: string | undefined;
  id?: string | undefined;
  connectionId?: string | undefined;
  limit?: number | undefined;
  }

Validation schemas: agentAdminQuerySchema in the downloadable schema registry.

Response

Returns { records, hasMore }. records contains the selected resource: settings objects, template/trigger records, destination summaries, credential metadata, provider summaries, or Support state. Resource shapes differ; use the resource names and action contracts in Admin configuration. hasMore requires narrowing the request; it never means the remaining records were loaded.

JSON response shape

{ records: unknown[];
  hasMore: boolean;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleQueryAgentAdminConfiguration.

GET /agent/admin/contract

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Use the path parameters above and any query options described below.

Handler inputs: action. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ actions: string[];
  resources: readonly ["app_settings", "auth_settings", "support_settings", "entitlements", "notification_templates", "notification_triggers", "notification_senders", "webhook_destinations", "webhook_deliveries", "workspace", "projects", "members", "api_keys", "agent_tokens", "provider_connections", "provider_accounts", "provider_mappings", "support_labels", "support_thread_state", "email_integration"];
  snapshotActions: readonly ["apps.configure", "apps.configure_auth", "apps.configure_support", "catalog.manage_entitlement", "messaging.manage_template", "messaging.manage_trigger", "messaging.bind_template_trigger", "webhooks.manage_destination", "webhooks.test_destination", "webhooks.retry_delivery", "workspace.update_settings", "workspace.update_project", "workspace.update_member_role", "integrations.validate_connection", "integrations.update_connection", "integrations.update_mapping", "integrations.configure_email", "messaging.manage_support_label", "messaging.set_support_status", "messaging.set_support_read_state", "messaging.set_support_labels"];
  rules: string[];
  action?: undefined;
  requestSchema?: undefined;
  validation?: undefined;
  } | { action: string;
  requestSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{ name: z.ZodOptional<z.ZodString>;
  appearance: z.ZodOptional<z.ZodType<AppAppearance, unknown, z.core.$ZodTypeInternals<AppAppearance, unknown>>>;
  bundleId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
  webOrigin: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
  }, z.core.$strict> | z.ZodObject<{ emailPasswordEnabled: z.ZodOptional<z.ZodBoolean>;
  magicLinkEnabled: z.ZodOptional<z.ZodBoolean>;
  redirectUrls: z.ZodOptional<z.ZodArray<z.ZodURL>>;
  sessionMode: z.ZodOptional<z.ZodEnum<{ persistent: "persistent";
  rolling: "rolling";
  absolute: "absolute";
  }>>;
  sessionInactivityDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
  sessionAbsoluteDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
  recentAuthenticationWindowSeconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
  passwordMaxAgeDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
  accountDeletion: z.ZodOptional<z.ZodObject<{ mode: z.ZodEnum<{ delete_customer: "delete_customer";
  delete_credential: "delete_credential";
  }>;
  requireCurrentPassword: z.ZodBoolean;
  scrubCustomerProfile: z.ZodBoolean;
  detachCustomerAuthUser: z.ZodBoolean;
  detachWorkspaceCustomer: z.ZodBoolean;
  deleteCustomerAuthUserWhenUnused: z.ZodBoolean;
  credentialProviderIds: z.ZodArray<z.ZodString>;
  }, z.core.$strict>>;
  restoreDeletedCredentialsOnSignup: z.ZodOptional<z.ZodBoolean>;
  emailChangeMode: z.ZodOptional<z.ZodEnum<{ verification_link: "verification_link";
  password_confirmed: "password_confirmed";
  }>>;
  }, z.core.$strict> | z.ZodObject<{ contactMode: z.ZodEnum<{ optional_email: "optional_email";
  required_email: "required_email";
  authenticated_account: "authenticated_account";
  }>;
  emailVerificationMode: z.ZodEnum<{ none: "none";
  optional: "optional";
  required: "required";
  }>;
  }, z.core.$strict> | z.ZodDiscriminatedUnion<[z.ZodObject<{ operation: z.ZodLiteral<"create">;
  values: z.ZodObject<{ identifier: z.ZodString;
  name: z.ZodString;
  description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  }, z.core.$strict>;
  }, z.core.$strict>, z.ZodObject<{ operation: z.ZodLiteral<"update">;
  id: z.ZodString;
  values: z.ZodObject<{ name: z.ZodOptional<z.ZodString>;
  description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  }, z.core.$strict>;
  }, z.core.$strict>], "operation"> | z.ZodDiscriminatedUnion<[z.ZodObject<{ operation: z.ZodLiteral<"create">;
  values: z.ZodObject<{ title: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  identifier: z.ZodString;
  name: z.ZodString;
  enabled: z.ZodDefault<z.ZodBoolean>;
  contentType: z.ZodDefault<z.ZodEnum<{ text: "text";
  push: "push";
  mjml: "mjml";
  html: "html";
  }>>;
  category: z.ZodDefault<z.ZodEnum<{ system: "system";
  transactional: "transactional";
  lifecycle: "lifecycle";
  marketing: "marketing";
  }>>;
  subject: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  variables: z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
  channel: z.ZodDefault<z.ZodEnum<{ email: "email";
  push: "push";
  }>>;
  locale: z.ZodDefault<z.ZodString>;
  bodyText: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  contentSource: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  contentHtml: z.ZodOptional<z.ZodString>;
  dataPayload: z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
  }, z.core.$strict>;
  }, z.core.$strict>, z.ZodObject<{ operation: z.ZodLiteral<"update">;
  id: z.ZodString;
  values: z.ZodObject<{ title: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  name: z.ZodOptional<z.ZodString>;
  enabled: z.ZodOptional<z.ZodBoolean>;
  contentType: z.ZodOptional<z.ZodEnum<{ text: "text";
  push: "push";
  mjml: "mjml";
  html: "html";
  }>>;
  category: z.ZodOptional<z.ZodEnum<{ system: "system";
  transactional: "transactional";
  lifecycle: "lifecycle";
  marketing: "marketing";
  }>>;
  subject: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  variables: z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
  locale: z.ZodOptional<z.ZodString>;
  bodyText: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  contentSource: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  contentHtml: z.ZodOptional<z.ZodString>;
  dataPayload: z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
  }, z.core.$strict>;
  }, z.core.$strict>], "operation"> | z.ZodDiscriminatedUnion<[z.ZodObject<{ operation: z.ZodLiteral<"create">;
  values: z.ZodObject<{ identifier: z.ZodString;
  name: z.ZodString;
  source: z.ZodDefault<z.ZodEnum<{ billing: "billing";
  manual: "manual";
  auth: "auth";
  api: "api";
  event: "event";
  }>>;
  eventType: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  enabled: z.ZodDefault<z.ZodBoolean>;
  delaySeconds: z.ZodDefault<z.ZodNumber>;
  cooldownSeconds: z.ZodDefault<z.ZodNumber>;
  }, z.core.$strict>;
  }, z.core.$strict>, z.ZodObject<{ operation: z.ZodLiteral<"update">;
  id: z.ZodString;
  values: z.ZodObject<{ identifier: z.ZodOptional<z.ZodString>;
  name: z.ZodOptional<z.ZodString>;
  source: z.ZodOptional<z.ZodEnum<{ billing: "billing";
  manual: "manual";
  auth: "auth";
  api: "api";
  event: "event";
  }>>;
  eventType: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  enabled: z.ZodOptional<z.ZodBoolean>;
  delaySeconds: z.ZodOptional<z.ZodNumber>;
  cooldownSeconds: z.ZodOptional<z.ZodNumber>;
  }, z.core.$strict>;
  }, z.core.$strict>], "operation"> | z.ZodObject<{ id: z.ZodString;
  triggerId: z.ZodNullable<z.ZodString>;
  }, z.core.$strict> | z.ZodDiscriminatedUnion<[z.ZodObject<{ operation: z.ZodLiteral<"create">;
  values: z.ZodObject<{ name: z.ZodString;
  url: z.ZodURL;
  enabled: z.ZodOptional<z.ZodBoolean>;
  eventTypes: z.ZodOptional<z.ZodArray<z.ZodEnum<{ session_start: "session_start";
  session_end: "session_end";
  deep_link_open: "deep_link_open";
  app_activity: "app_activity";
  milestone_recorded: "milestone_recorded";
  onboarding_step_viewed: "onboarding_step_viewed";
  paywall_requested: "paywall_requested";
  paywall_shown: "paywall_shown";
  paywall_closed: "paywall_closed";
  paywall_product_selected: "paywall_product_selected";
  paywall_screen_changed: "paywall_screen_changed";
  product_offer_redemption_updated: "product_offer_redemption_updated";
  paywall_checkout_requested: "paywall_checkout_requested";
  checkout_started: "checkout_started";
  purchase_started: "purchase_started";
  purchase_already_entitled: "purchase_already_entitled";
  purchase_cancelled: "purchase_cancelled";
  purchase_pending: "purchase_pending";
  purchase_failed: "purchase_failed";
  purchase_sync_failed: "purchase_sync_failed";
  purchase_succeeded: "purchase_succeeded";
  restore_started: "restore_started";
  restore_succeeded: "restore_succeeded";
  restore_failed: "restore_failed";
  sdk_access_observed: "sdk_access_observed";
  restore_operation_updated: "restore_operation_updated";
  apple_order_recovery_succeeded: "apple_order_recovery_succeeded";
  apple_access_observed: "apple_access_observed";
  billing_operation_failed: "billing_operation_failed";
  surface_impression: "surface_impression";
  subscription_started: "subscription_started";
  subscription_trial_started: "subscription_trial_started";
  subscription_trial_converted: "subscription_trial_converted";
  purchase_verified: "purchase_verified";
  purchase_refunded: "purchase_refunded";
  purchase_refund_reversed: "purchase_refund_reversed";
  purchase_refund_declined: "purchase_refund_declined";
  subscription_renewed: "subscription_renewed";
  subscription_renewal_extended: "subscription_renewal_extended";
  subscription_renewal_preference_changed: "subscription_renewal_preference_changed";
  subscription_renewal_failed: "subscription_renewal_failed";
  subscription_expired: "subscription_expired";
  subscription_cancelled: "subscription_cancelled";
  subscription_cancellation_scheduled: "subscription_cancellation_scheduled";
  subscription_reactivated: "subscription_reactivated";
  subscription_paused: "subscription_paused";
  subscription_resumed: "subscription_resumed";
  purchase_revoked: "purchase_revoked";
  price_change_detected: "price_change_detected";
  grace_period_started: "grace_period_started";
  grace_period_ended: "grace_period_ended";
  purchase_refund_requested: "purchase_refund_requested";
  offer_redeemed: "offer_redeemed";
  entitlement_granted: "entitlement_granted";
  entitlement_revoked: "entitlement_revoked";
  notification_sent: "notification_sent";
  notification_opened: "notification_opened";
  webhook_delivered: "webhook_delivered";
  webhook_failed: "webhook_failed";
  email_changed: "email_changed";
  password_changed: "password_changed";
  signup: "signup";
  signin: "signin";
  signout: "signout";
  account_deleted: "account_deleted";
  customer_note_added: "customer_note_added";
  app_crash_reported: "app_crash_reported";
  app_error_reported: "app_error_reported";
  identity_attached: "identity_attached";
  customer_first_seen: "customer_first_seen";
  }>>>;
  }, z.core.$strict>;
  }, z.core.$strict>, z.ZodObject<{ operation: z.ZodLiteral<"update">;
  id: z.ZodString;
  values: z.ZodObject<{ name: z.ZodOptional<z.ZodString>;
  url: z.ZodOptional<z.ZodURL>;
  enabled: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
  eventTypes: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodEnum<{ session_start: "session_start";
  session_end: "session_end";
  deep_link_open: "deep_link_open";
  app_activity: "app_activity";
  milestone_recorded: "milestone_recorded";
  onboarding_step_viewed: "onboarding_step_viewed";
  paywall_requested: "paywall_requested";
  paywall_shown: "paywall_shown";
  paywall_closed: "paywall_closed";
  paywall_product_selected: "paywall_product_selected";
  paywall_screen_changed: "paywall_screen_changed";
  product_offer_redemption_updated: "product_offer_redemption_updated";
  paywall_checkout_requested: "paywall_checkout_requested";
  checkout_started: "checkout_started";
  purchase_started: "purchase_started";
  purchase_already_entitled: "purchase_already_entitled";
  purchase_cancelled: "purchase_cancelled";
  purchase_pending: "purchase_pending";
  purchase_failed: "purchase_failed";
  purchase_sync_failed: "purchase_sync_failed";
  purchase_succeeded: "purchase_succeeded";
  restore_started: "restore_started";
  restore_succeeded: "restore_succeeded";
  restore_failed: "restore_failed";
  sdk_access_observed: "sdk_access_observed";
  restore_operation_updated: "restore_operation_updated";
  apple_order_recovery_succeeded: "apple_order_recovery_succeeded";
  apple_access_observed: "apple_access_observed";
  billing_operation_failed: "billing_operation_failed";
  surface_impression: "surface_impression";
  subscription_started: "subscription_started";
  subscription_trial_started: "subscription_trial_started";
  subscription_trial_converted: "subscription_trial_converted";
  purchase_verified: "purchase_verified";
  purchase_refunded: "purchase_refunded";
  purchase_refund_reversed: "purchase_refund_reversed";
  purchase_refund_declined: "purchase_refund_declined";
  subscription_renewed: "subscription_renewed";
  subscription_renewal_extended: "subscription_renewal_extended";
  subscription_renewal_preference_changed: "subscription_renewal_preference_changed";
  subscription_renewal_failed: "subscription_renewal_failed";
  subscription_expired: "subscription_expired";
  subscription_cancelled: "subscription_cancelled";
  subscription_cancellation_scheduled: "subscription_cancellation_scheduled";
  subscription_reactivated: "subscription_reactivated";
  subscription_paused: "subscription_paused";
  subscription_resumed: "subscription_resumed";
  purchase_revoked: "purchase_revoked";
  price_change_detected: "price_change_detected";
  grace_period_started: "grace_period_started";
  grace_period_ended: "grace_period_ended";
  purchase_refund_requested: "purchase_refund_requested";
  offer_redeemed: "offer_redeemed";
  entitlement_granted: "entitlement_granted";
  entitlement_revoked: "entitlement_revoked";
  notification_sent: "notification_sent";
  notification_opened: "notification_opened";
  webhook_delivered: "webhook_delivered";
  webhook_failed: "webhook_failed";
  email_changed: "email_changed";
  password_changed: "password_changed";
  signup: "signup";
  signin: "signin";
  signout: "signout";
  account_deleted: "account_deleted";
  customer_note_added: "customer_note_added";
  app_crash_reported: "app_crash_reported";
  app_error_reported: "app_error_reported";
  identity_attached: "identity_attached";
  customer_first_seen: "customer_first_seen";
  }>>>>;
  }, z.core.$strict>;
  }, z.core.$strict>], "operation"> | z.ZodObject<{ id: z.ZodString;
  }, z.core.$strict> | z.ZodObject<{ id: z.ZodString;
  }, z.core.$strict> | z.ZodObject<{ name: z.ZodOptional<z.ZodString>;
  slug: z.ZodOptional<z.ZodString>;
  }, z.core.$strict> | z.ZodObject<{ id: z.ZodString;
  name: z.ZodString;
  }, z.core.$strict> | z.ZodObject<{ id: z.ZodString;
  role: z.ZodEnum<{ owner: "owner";
  admin: "admin";
  member: "member";
  }>;
  }, z.core.$strict> | z.ZodObject<{ id: z.ZodString;
  }, z.core.$strict> | z.ZodObject<{ id: z.ZodString;
  values: z.ZodObject<{ name: z.ZodOptional<z.ZodString>;
  status: z.ZodOptional<z.ZodEnum<{ active: "active";
  disabled: "disabled";
  }>>;
  }, z.core.$strict>;
  }, z.core.$strict> | z.ZodObject<{ id: z.ZodString;
  connectionId: z.ZodString;
  values: z.ZodObject<{ externalAppName: z.ZodOptional<z.ZodString>;
  enabled: z.ZodOptional<z.ZodBoolean>;
  }, z.core.$strict>;
  }, z.core.$strict> | z.ZodUnion<readonly [z.ZodObject<{ enabled: z.ZodBoolean;
  replaceCredentials: z.ZodBoolean;
  publicConfig: z.ZodObject<{ accountId: z.ZodString;
  sendingDomain: z.ZodString;
  fromAddress: z.ZodEmail;
  fromName: z.ZodOptional<z.ZodString>;
  replyTo: z.ZodOptional<z.ZodEmail>;
  }, z.core.$strict>;
  }, z.core.$strict>, z.ZodObject<{ enabled: z.ZodBoolean;
  replaceCredentials: z.ZodLiteral<false>;
  useExistingBinding: z.ZodLiteral<true>;
  publicConfig: z.ZodObject<{ fromAddress: z.ZodEmail;
  fromName: z.ZodOptional<z.ZodString>;
  replyTo: z.ZodOptional<z.ZodEmail>;
  }, z.core.$strict>;
  }, z.core.$strict>]> | z.ZodDiscriminatedUnion<[z.ZodObject<{ operation: z.ZodLiteral<"create">;
  values: z.ZodObject<{ title: z.ZodString;
  color: z.ZodEnum<{ slate: "slate";
  blue: "blue";
  green: "green";
  amber: "amber";
  rose: "rose";
  violet: "violet";
  }>;
  }, z.core.$strict>;
  }, z.core.$strict>, z.ZodObject<{ operation: z.ZodLiteral<"update">;
  id: z.ZodString;
  values: z.ZodObject<{ title: z.ZodString;
  color: z.ZodEnum<{ slate: "slate";
  blue: "blue";
  green: "green";
  amber: "amber";
  rose: "rose";
  violet: "violet";
  }>;
  }, z.core.$strict>;
  }, z.core.$strict>], "operation"> | z.ZodObject<{ id: z.ZodString;
  status: z.ZodEnum<{ open: "open";
  resolved: "resolved";
  }>;
  }, z.core.$strict> | z.ZodObject<{ id: z.ZodString;
  read: z.ZodBoolean;
  }, z.core.$strict> | z.ZodObject<{ id: z.ZodString;
  labelIds: z.ZodArray<z.ZodString>;
  }, z.core.$strict> | z.ZodObject<{ operation: z.ZodEnum<{ update: "update";
  delete: "delete";
  create: "create";
  }>;
  id: z.ZodOptional<z.ZodString>;
  identifier: z.ZodOptional<z.ZodString>;
  values: z.ZodOptional<z.ZodObject<{ identifier: z.ZodOptional<z.ZodString>;
  name: z.ZodOptional<z.ZodString>;
  description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  priority: z.ZodOptional<z.ZodNumber>;
  status: z.ZodOptional<z.ZodEnum<{ active: "active";
  inactive: "inactive";
  archived: "archived";
  }>>;
  isActive: z.ZodOptional<z.ZodBoolean>;
  placements: z.ZodOptional<z.ZodArray<z.ZodString>>;
  audiences: z.ZodOptional<z.ZodArray<z.ZodObject<{ id: z.ZodOptional<z.ZodString>;
  identifier: z.ZodString;
  name: z.ZodString;
  description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  sortOrder: z.ZodOptional<z.ZodNumber>;
  enabled: z.ZodOptional<z.ZodBoolean>;
  audienceRule: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
  cooldownSeconds: z.ZodOptional<z.ZodNumber>;
  maxMatchesPerCustomer: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
  maxMatchesPerWindow: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
  windowSeconds: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
  variants: z.ZodOptional<z.ZodArray<z.ZodObject<{ id: z.ZodOptional<z.ZodString>;
  identifier: z.ZodString;
  name: z.ZodString;
  targetType: z.ZodOptional<z.ZodEnum<{ paywall: "paywall";
  in_app_surface: "in_app_surface";
  survey: "survey";
  custom: "custom";
  none: "none";
  }>>;
  surveyId: z.ZodOptional<z.ZodString>;
  paywallId: z.ZodOptional<z.ZodString>;
  paywallIdentifier: z.ZodOptional<z.ZodString>;
  inAppSurfaceId: z.ZodOptional<z.ZodString>;
  inAppSurfaceIdentifier: z.ZodOptional<z.ZodString>;
  trafficPercent: z.ZodOptional<z.ZodNumber>;
  allocationPercent: z.ZodOptional<z.ZodNumber>;
  isControl: z.ZodOptional<z.ZodBoolean>;
  payload: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
  }, z.core.$strip>>>;
  }, z.core.$strip>>>;
  variants: z.ZodOptional<z.ZodArray<z.ZodObject<{ id: z.ZodOptional<z.ZodString>;
  identifier: z.ZodString;
  name: z.ZodString;
  targetType: z.ZodOptional<z.ZodEnum<{ paywall: "paywall";
  in_app_surface: "in_app_surface";
  survey: "survey";
  custom: "custom";
  none: "none";
  }>>;
  surveyId: z.ZodOptional<z.ZodString>;
  paywallId: z.ZodOptional<z.ZodString>;
  paywallIdentifier: z.ZodOptional<z.ZodString>;
  inAppSurfaceId: z.ZodOptional<z.ZodString>;
  inAppSurfaceIdentifier: z.ZodOptional<z.ZodString>;
  trafficPercent: z.ZodOptional<z.ZodNumber>;
  allocationPercent: z.ZodOptional<z.ZodNumber>;
  isControl: z.ZodOptional<z.ZodBoolean>;
  payload: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
  }, z.core.$strip>>>;
  }, z.core.$strip>>;
  }, z.core.$strip> | z.ZodObject<{ operation: z.ZodEnum<{ update: "update";
  delete: "delete";
  upsert: "upsert";
  }>;
  key: z.ZodString;
  value: z.ZodOptional<z.ZodString>;
  description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
  }, z.core.$strip> | z.ZodObject<{ operation: z.ZodEnum<{ update: "update";
  delete: "delete";
  create: "create";
  }>;
  id: z.ZodOptional<z.ZodString>;
  identifier: z.ZodOptional<z.ZodString>;
  values: z.ZodOptional<z.ZodObject<{ identifier: z.ZodOptional<z.ZodString>;
  name: z.ZodOptional<z.ZodString>;
  type: z.ZodOptional<z.ZodEnum<{ action: "action";
  webhook: "webhook";
  check: "check";
  }>>;
  trigger: z.ZodOptional<z.ZodEnum<{ event: "event";
  sdk_call: "sdk_call";
  }>>;
  rule: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
  eventTypes: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodString>>>;
  actionConfig: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
  webhookConfig: z.ZodNullable<z.ZodOptional<z.ZodObject<{ url: z.ZodURL;
  method: z.ZodOptional<z.ZodEnum<{ POST: "POST";
  PUT: "PUT";
  PATCH: "PATCH";
  }>>;
  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
  }, z.core.$strip>>>;
  enabled: z.ZodOptional<z.ZodBoolean>;
  }, z.core.$strip>>;
  }, z.core.$strip>>;
  validation: string;
  actions?: undefined;
  resources?: undefined;
  snapshotActions?: undefined;
  rules?: undefined;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentAdminContract.

POST /agent/admin/plans

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ action: "apps.configure" | "apps.configure_auth" | "apps.configure_support" | "catalog.manage_entitlement" | "messaging.manage_template" | "messaging.manage_trigger" | "messaging.bind_template_trigger" | "webhooks.manage_destination" | "webhooks.test_destination" | "webhooks.retry_delivery" | "workspace.update_settings" | "workspace.update_project" | "workspace.update_member_role" | "integrations.validate_connection" | "integrations.update_connection" | "integrations.update_mapping" | "integrations.configure_email" | "messaging.manage_support_label" | "messaging.set_support_status" | "messaging.set_support_read_state" | "messaging.set_support_labels";
  request: Record<string, unknown>;
  expiresAt: string;
  appId?: string | undefined;
  environment?: "test" | "live" | undefined;
  }

{ operation: "delete";
  resource?: "product" | undefined;
  id?: string | undefined;
  identifier?: string | undefined;
  key?: string | undefined;
  }

{ name?: string | undefined;
  emailPasswordEnabled?: boolean | undefined;
  magicLinkEnabled?: boolean | undefined;
  emailChangeMode?: "verification_link" | "password_confirmed" | undefined;
  allowedRedirectUris?: string[] | undefined;
  accountDeletion?: { mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  } | undefined;
  restoreDeletedCredentialsOnSignup?: boolean | undefined;
  expectedAccountDeletion?: { mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  } | null | undefined;
  expectedAccountDeletionConfigurationStatus?: "invalid" | "absent" | "configured" | undefined;
  expectedAccountDeletionFingerprint?: string | undefined;
  expectedRestoreDeletedCredentialsOnSignup?: boolean | null | undefined;
  expectedAppUpdatedAt?: string | undefined;
  }

{ enabled: boolean;
  appVersions: string[];
  customerIds: string[];
  captureHours: number;
  retentionDays: number;
  maxCaptures: number;
  successSampleLimit?: number | undefined;
  }

{ name?: string | undefined;
  appearance?: unknown;
  bundleId?: string | null | undefined;
  webOrigin?: string | null | undefined;
  } | { emailPasswordEnabled?: boolean | undefined;
  magicLinkEnabled?: boolean | undefined;
  redirectUrls?: string[] | undefined;
  sessionMode?: "persistent" | "rolling" | "absolute" | undefined;
  sessionInactivityDays?: number | null | undefined;
  sessionAbsoluteDays?: number | null | undefined;
  recentAuthenticationWindowSeconds?: number | null | undefined;
  passwordMaxAgeDays?: number | null | undefined;
  accountDeletion?: { mode: "delete_credential" | "delete_customer";
  requireCurrentPassword: boolean;
  scrubCustomerProfile: boolean;
  detachCustomerAuthUser: boolean;
  detachWorkspaceCustomer: boolean;
  deleteCustomerAuthUserWhenUnused: boolean;
  credentialProviderIds: string[];
  } | undefined;
  restoreDeletedCredentialsOnSignup?: boolean | undefined;
  emailChangeMode?: "verification_link" | "password_confirmed" | undefined;
  } | { contactMode: "optional_email" | "required_email" | "authenticated_account";
  emailVerificationMode: "none" | "optional" | "required";
  } | { operation: "create";
  values: { identifier: string;
  name: string;
  description?: string | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { name?: string | undefined;
  description?: string | null | undefined;
  };
  } | { operation: "create";
  values: { identifier: string;
  name: string;
  title?: string | null | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  subject?: string | null | undefined;
  variables?: string | Record<string, unknown> | null | undefined;
  channel?: "email" | "push" | undefined;
  locale?: string | undefined;
  bodyText?: string | null | undefined;
  contentSource?: string | null | undefined;
  contentHtml?: string | undefined;
  dataPayload?: string | Record<string, unknown> | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { title?: string | null | undefined;
  name?: string | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  subject?: string | null | undefined;
  variables?: string | Record<string, unknown> | null | undefined;
  locale?: string | undefined;
  bodyText?: string | null | undefined;
  contentSource?: string | null | undefined;
  contentHtml?: string | undefined;
  dataPayload?: string | Record<string, unknown> | null | undefined;
  };
  } | { operation: "create";
  values: { identifier: string;
  name: string;
  source?: "manual" | "auth" | "event" | "billing" | "api" | undefined;
  eventType?: string | null | undefined;
  enabled?: boolean | undefined;
  delaySeconds?: number | undefined;
  cooldownSeconds?: number | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { identifier?: string | undefined;
  name?: string | undefined;
  source?: "manual" | "auth" | "event" | "billing" | "api" | undefined;
  eventType?: string | null | undefined;
  enabled?: boolean | undefined;
  delaySeconds?: number | undefined;
  cooldownSeconds?: number | undefined;
  };
  } | { id: string;
  triggerId: string | null;
  } | { operation: "create";
  values: { name: string;
  url: string;
  enabled?: boolean | undefined;
  eventTypes?: ("identity_attached" | "signin" | "signup" | "signout" | "paywall_shown" | "paywall_product_selected" | "checkout_started" | "purchase_started" | "customer_first_seen" | "email_changed" | "password_changed" | "account_deleted" | "purchase_revoked" | "purchase_refunded" | "billing_operation_failed" | "apple_access_observed" | "subscription_cancellation_scheduled" | "subscription_reactivated" | "subscription_started" | "purchase_verified" | "app_activity" | "session_start" | "session_end" | "deep_link_open" | "milestone_recorded" | "onboarding_step_viewed" | "paywall_requested" | "paywall_closed" | "paywall_screen_changed" | "product_offer_redemption_updated" | "paywall_checkout_requested" | "purchase_already_entitled" | "purchase_cancelled" | "purchase_pending" | "purchase_failed" | "purchase_sync_failed" | "purchase_succeeded" | "restore_started" | "restore_succeeded" | "restore_failed" | "sdk_access_observed" | "restore_operation_updated" | "apple_order_recovery_succeeded" | "surface_impression" | "subscription_trial_started" | "subscription_trial_converted" | "purchase_refund_reversed" | "purchase_refund_declined" | "subscription_renewed" | "subscription_renewal_extended" | "subscription_renewal_preference_changed" | "subscription_renewal_failed" | "subscription_expired" | "subscription_cancelled" | "subscription_paused" | "subscription_resumed" | "price_change_detected" | "grace_period_started" | "grace_period_ended" | "purchase_refund_requested" | "offer_redeemed" | "entitlement_granted" | "entitlement_revoked" | "notification_sent" | "notification_opened" | "webhook_delivered" | "webhook_failed" | "customer_note_added" | "app_crash_reported" | "app_error_reported")[] | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { name?: string | undefined;
  url?: string | undefined;
  enabled?: boolean | undefined;
  eventTypes?: ("identity_attached" | "signin" | "signup" | "signout" | "paywall_shown" | "paywall_product_selected" | "checkout_started" | "purchase_started" | "customer_first_seen" | "email_changed" | "password_changed" | "account_deleted" | "purchase_revoked" | "purchase_refunded" | "billing_operation_failed" | "apple_access_observed" | "subscription_cancellation_scheduled" | "subscription_reactivated" | "subscription_started" | "purchase_verified" | "app_activity" | "session_start" | "session_end" | "deep_link_open" | "milestone_recorded" | "onboarding_step_viewed" | "paywall_requested" | "paywall_closed" | "paywall_screen_changed" | "product_offer_redemption_updated" | "paywall_checkout_requested" | "purchase_already_entitled" | "purchase_cancelled" | "purchase_pending" | "purchase_failed" | "purchase_sync_failed" | "purchase_succeeded" | "restore_started" | "restore_succeeded" | "restore_failed" | "sdk_access_observed" | "restore_operation_updated" | "apple_order_recovery_succeeded" | "surface_impression" | "subscription_trial_started" | "subscription_trial_converted" | "purchase_refund_reversed" | "purchase_refund_declined" | "subscription_renewed" | "subscription_renewal_extended" | "subscription_renewal_preference_changed" | "subscription_renewal_failed" | "subscription_expired" | "subscription_cancelled" | "subscription_paused" | "subscription_resumed" | "price_change_detected" | "grace_period_started" | "grace_period_ended" | "purchase_refund_requested" | "offer_redeemed" | "entitlement_granted" | "entitlement_revoked" | "notification_sent" | "notification_opened" | "webhook_delivered" | "webhook_failed" | "customer_note_added" | "app_crash_reported" | "app_error_reported")[] | undefined;
  };
  } | { id: string;
  } | { id: string;
  } | { name?: string | undefined;
  slug?: string | undefined;
  } | { id: string;
  name: string;
  } | { id: string;
  role: "owner" | "admin" | "member";
  } | { id: string;
  } | { id: string;
  values: { name?: string | undefined;
  status?: "active" | "disabled" | undefined;
  };
  } | { id: string;
  connectionId: string;
  values: { externalAppName?: string | undefined;
  enabled?: boolean | undefined;
  };
  } | { enabled: boolean;
  replaceCredentials: boolean;
  publicConfig: { accountId: string;
  sendingDomain: string;
  fromAddress: string;
  fromName?: string | undefined;
  replyTo?: string | undefined;
  };
  } | { enabled: boolean;
  replaceCredentials: false;
  useExistingBinding: true;
  publicConfig: { fromAddress: string;
  fromName?: string | undefined;
  replyTo?: string | undefined;
  };
  } | { operation: "create";
  values: { title: string;
  color: "slate" | "blue" | "green" | "amber" | "rose" | "violet";
  };
  } | { operation: "update";
  id: string;
  values: { title: string;
  color: "slate" | "blue" | "green" | "amber" | "rose" | "violet";
  };
  } | { id: string;
  status: "open" | "resolved";
  } | { id: string;
  read: boolean;
  } | { id: string;
  labelIds: string[];
  }

{ id: string;
  triggerId: string | null;
  }

{ enabled: boolean;
  replaceCredentials: boolean;
  publicConfig: { accountId: string;
  sendingDomain: string;
  fromAddress: string;
  fromName?: string | undefined;
  replyTo?: string | undefined;
  };
  } | { enabled: boolean;
  replaceCredentials: false;
  useExistingBinding: true;
  publicConfig: { fromAddress: string;
  fromName?: string | undefined;
  replyTo?: string | undefined;
  };
  }

{ operation: "create";
  values: { identifier: string;
  name: string;
  title?: string | null | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  subject?: string | null | undefined;
  variables?: string | Record<string, unknown> | null | undefined;
  channel?: "email" | "push" | undefined;
  locale?: string | undefined;
  bodyText?: string | null | undefined;
  contentSource?: string | null | undefined;
  contentHtml?: string | undefined;
  dataPayload?: string | Record<string, unknown> | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { title?: string | null | undefined;
  name?: string | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  subject?: string | null | undefined;
  variables?: string | Record<string, unknown> | null | undefined;
  locale?: string | undefined;
  bodyText?: string | null | undefined;
  contentSource?: string | null | undefined;
  contentHtml?: string | undefined;
  dataPayload?: string | Record<string, unknown> | null | undefined;
  };
  }

{ id: string;
  labelIds: string[];
  }

{ definition: { key: string;
  revision: number;
  label: string;
  unit: "duration" | "count" | "bytes" | "credits";
  scale: number;
  allowedSources: ("server" | "client")[];
  dimensionKeys: string[];
  entitlementId: string | null;
  isActive: boolean;
  };
  }

{ definition: { key: string;
  allowedValues: string[];
  };
  }

{ policy: "account" | "app_store";
  preservedImport?: { revision: string;
  enabled: boolean;
  entitlementIdentifier: string;
  members: { grantId: string;
  customerId: string;
  }[];
  } | null | undefined;
  appPurchaseRules?: { entitlementIdentifiers: string[];
  originalAppVersionFormat?: "integer" | "dotted" | undefined;
  originalAppVersionBefore?: string | undefined;
  originalPurchaseDateBefore?: string | undefined;
  }[] | undefined;
  }

{ operation: "create";
  values: { identifier: string;
  name: string;
  status: "active" | "inactive" | "archived";
  config: unknown;
  delivery: { maxPresentationsPerCustomer: number;
  cooldownSeconds: number;
  allowManualRepeats: boolean;
  };
  description?: string | null | undefined;
  };
  } | { operation: "update";
  id: string;
  values: { status?: "active" | "inactive" | "archived" | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  config?: unknown;
  delivery?: { maxPresentationsPerCustomer: number;
  cooldownSeconds: number;
  allowManualRepeats: boolean;
  } | undefined;
  };
  } | { operation: "new_round";
  id: string;
  }

{ provider: "apple_app_store_connect";
  category: "catalog";
  resource: "app_store_pricing_plan";
  operation: "apply";
  providerPlanId: string;
  digest: string;
  }

{ provider: "google";
  category: "auth";
  publicConfig: { clientId: string;
  };
  enabled?: boolean | undefined;
  } | { provider: "apple";
  category: "auth";
  publicConfig: { clientId: string;
  teamId?: string | undefined;
  keyId?: string | undefined;
  };
  enabled?: boolean | undefined;
  }

{ operation: "update";
  resource: "product_offer";
  id: string;
  values: { paused: boolean;
  };
  }

{ operation: "update" | "delete" | "create";
  resource?: "paywall" | undefined;
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  config?: unknown;
  status?: "active" | "inactive" | "archived" | undefined;
  isDefault?: boolean | undefined;
  productIdentifiers?: string[] | undefined;
  } | undefined;
  } | { operation: "update";
  resource: "placement_fallback";
  placementIdentifier: string;
  fallbackPaywallIdentifier: string;
  } | { operation: "upsert";
  resource: "placement";
  identifier: string;
  name: string;
  fallbackPaywallIdentifier: string;
  description?: string | null | undefined;
  } | { operation: "update" | "delete" | "create";
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  surfaceType?: string | undefined;
  status?: "active" | "inactive" | "archived" | undefined;
  enabled?: boolean | undefined;
  config?: unknown;
  } | undefined;
  }

{ operation: "update" | "delete" | "create";
  resource?: "paywall" | undefined;
  id?: string | undefined;
  identifier?: string | undefined;
  values?: { identifier?: string | undefined;
  name?: string | undefined;
  description?: string | null | undefined;
  config?: unknown;
  status?: "active" | "inactive" | "archived" | undefined;
  isDefault?: boolean | undefined;
  productIdentifiers?: string[] | undefined;
  } | undefined;
  }

{ operation: "upsert";
  resource: "placement";
  identifier: string;
  name: string;
  fallbackPaywallIdentifier: string;
  description?: string | null | undefined;
  }

{ operation: "update" | "delete" | "create";
  id?: string | undefined;
  expectedUpdatedAt?: string | undefined;
  values?: { identifier?: string | null | undefined;
  name?: string | undefined;
  subject?: string | null | undefined;
  channel?: "email" | undefined;
  category?: "transactional" | "lifecycle" | "marketing" | "system" | undefined;
  locale?: string | undefined;
  enabled?: boolean | undefined;
  contentType?: "push" | "mjml" | "html" | "text" | undefined;
  contentSource?: string | undefined;
  contentHtml?: string | undefined;
  variables?: unknown;
  } | undefined;
  }

{ providerTransactionId: string;
  billingTransactionId: string;
  subscriptionId: string;
  customerId: string;
  canonicalEventId: string;
  expectedPurchasedAt: string;
  expectedPeriodEnd: string;
  duplicateEventIds?: string[] | undefined;
  }

{ customerId: string;
  grantId: string;
  entitlementIdentifier: string;
  sourceBillingTransactionId: string | null;
  expectedRevokedAt: null;
  }

{ entitlementId: string;
  startsAt: unknown;
  endsAt: unknown;
  customerId: string;
  expectedPolicy: "account" | "app_store";
  source: "manual";
  applePurchaserLinkId?: string | undefined;
  note?: string | undefined;
  }

{ authUserId: string;
  normalizedEmail: string;
  expectedUpdatedAt: string;
  expectedProviders: { providerId: string;
  accountCount: number;
  hasPassword: boolean;
  passwordUpdatedAt: string | null;
  }[];
  expectedCustomerCount: 0;
  expectedWorkspaceCustomerCount: 0;
  expectedSessionCount: number;
  expectedActiveSessionCount: 0;
  expectedChallengeCount: number;
  expectedActiveChallengeCount: 0;
  }

Validation schemas: agentAdminPlanInputSchema in the downloadable schema registry.

Response

JSON response shape

{ plan: { appId: string | null;
  environment: "test" | "live" | null;
  platformUserId: string;
  workspaceId: string;
  agentAccessTokenId: string;
  action: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  request: Record<string, unknown>;
  expiresAt: string;
  appliedAt: string | null;
  plan: Record<string, unknown>;
  };
  requiredScope: "workspace:read" | "workspace:write" | "apps:read" | "apps:write" | "reports:read" | "catalog:read" | "catalog:write" | "paywalls:read" | "paywalls:write" | "messaging:read" | "messaging:write" | "campaigns:read" | "campaigns:write" | "remote_config:read" | "remote_config:write" | "surfaces:read" | "surfaces:write" | "surveys:read" | "surveys:write" | "rules:read" | "rules:write" | "webhooks:read" | "webhooks:write" | "integrations:read" | "integrations:write" | "auth:read" | "auth:write" | "audit:read";
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handlePlanAgentAdminChange.

GET /agent/apps/:appId/surveys

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  surveys: { id: string;
  appId: string;
  identifier: string;
  name: string;
  description: string | null;
  status: "active" | "inactive" | "archived";
  config: SurveyConfig;
  delivery: SurveyDeliverySettings;
  collectionRound: number;
  createdAt: string;
  updatedAt: string;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListAgentSurveys.

GET /agent/apps/:appId/surveys/:surveyId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), surveyId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.appId, path.surveyId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  survey: { id: string;
  appId: string;
  identifier: string;
  name: string;
  description: string | null;
  status: "active" | "inactive" | "archived";
  config: SurveyConfig;
  delivery: SurveyDeliverySettings;
  collectionRound: number;
  createdAt: string;
  updatedAt: string;
  };
  revisions: { appId: string;
  id: string;
  createdAt: string;
  label: string | null;
  source: "publish" | "restore";
  config: AnyPaywallConfig | AnyInAppSurfaceConfig | SurveyConfig;
  creativeType: "paywall" | "in_app_surface" | "survey";
  creativeId: string;
  configVersion: string;
  createdByPlatformUserId: string | null;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentSurvey.

GET /agent/apps/:appId/surveys/:surveyId/results

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), surveyId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ includeQuestionSummary?: "false" | "true" | undefined;
  limit?: unknown;
  before?: string | undefined;
  revisionId?: string | undefined;
  collectionRound?: unknown;
  platform?: "ios" | "android" | "web" | "windows" | "macos" | undefined;
  }

unknown

Validation schemas: surveyResultsQuerySchema in the downloadable schema registry.

Response

JSON response shape

SurveyResultsPage | { format: string;
  csv: string;
  nextCursor: string | null;
  responseCount: number;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentSurveyResults.

GET /agent/apps/:appId/surveys/:surveyId/results/export

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), surveyId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ includeQuestionSummary?: "false" | "true" | undefined;
  limit?: unknown;
  before?: string | undefined;
  revisionId?: string | undefined;
  collectionRound?: unknown;
  platform?: "ios" | "android" | "web" | "windows" | "macos" | undefined;
  }

unknown

Validation schemas: surveyResultsQuerySchema in the downloadable schema registry.

Response

JSON response shape

SurveyResultsPage | { format: string;
  csv: string;
  nextCursor: string | null;
  responseCount: number;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleExportAgentSurveyResults.

GET /agent/apps/:appId/purchase-health

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ days?: "1" | "7" | "30" | undefined;
  }

Validation schemas: purchaseHealthQuerySchema in the downloadable schema registry.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  report: PurchaseHealthReport;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetAgentPurchaseHealth.

GET /agent/apps/:appId/purchase-captures

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ version: 1;
  id: string;
  requestId: string;
  operationId: string | null;
  route: "access" | "evidence";
  receivedAt: string;
  finishedAt: string;
  verifiedAt: string | null;
  policy: "account" | "app_store" | null;
  configurationRevision: string | null;
  providerEnvironment: "Production" | "Sandbox" | null;
  outcome: "failed" | "partial" | "verified";
  completeness: "failed" | "complete" | "partial" | "submitted_evidence";
  acquisitionVerified: boolean | null;
  transactionCounts: { submitted: number;
  verified: number | null;
  active: number | null;
  inactive: number | null;
  unverified: number | null;
  unmapped: number | null;
  } | null;
  entitlements: { identifier: string;
  expiresAt: number | null;
  source: "manual" | "apple";
  }[];
  entitlementsTruncated: boolean;
  responseExpiresAt: number | null;
  accessContextExpiresAt: number | null;
  stage: "completed" | "acquisition" | "configuration" | "transactions" | "mapping" | "purchaser_link" | "context_signing" | "contract_validation";
  failure: { code: "invalid_contract" | "verification_rejected" | "service_error";
  httpStatus: number;
  retryable: boolean;
  } | null;
  appVersion: string | null;
  sdkVersion: string | null;
  deviceModel: string | null;
  osVersion: string | null;
  versionProvenance: "unknown" | "request_headers";
  attemptId?: string | null | undefined;
  evidenceIssues?: { source: "renewal" | "acquisition" | "transaction" | "mapping";
  reason: "verification_failed" | "claims_invalid" | "device_mismatch" | "environment_mismatch" | "unmatched_renewal" | "catalog_mapping_failed";
  index?: number | undefined;
  }[] | undefined;
  }

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  policy: { appId: string;
  revision: string;
  enabled: boolean;
  appVersions: string[];
  customerIds: string[];
  captureUntil: string;
  retentionDays: number;
  maxCaptures: number;
  successSampleLimit: number;
  successSampleCount: number;
  capturedCount: number;
  updatedBy: string;
  updatedAt: string;
  } | null;
  captures: { serverDecision: { accessReturned: boolean;
  complete: boolean;
  failed: boolean;
  } | null;
  id: string;
  customerId: string;
  appVersion: string | null;
  sdkVersion: string | null;
  operationId: string | null;
  requestId: string;
  route: string;
  status: "failed" | "ready" | "pending";
  outcome: string;
  createdAt: string;
  expiresAt: string;
  sizeBytes: number | null;
  failureCode: string | null;
  }[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: inline route handler.

GET /agent/apps/:appId/purchase-captures/:captureId

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), captureId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ observedAt: string;
  stage: string;
  nativeDomain: string;
  nativeCode: number;
  storeKitCase?: string | null | undefined;
  underlying?: { domain: string;
  code: number;
  }[] | undefined;
  }[]

Response

JSON response shape

{ customerId: string;
  headline: string;
  explanation: string;
  evidence: { environment: "live" | "test";
  route: "access" | "evidence";
  failed: boolean;
  failureStage?: string;
  clientDiagnostics?: AppleClientDiagnostic[];
  failure?: { code: string;
  statusCode?: number;
  };
  serverFailures?: Array<{ kind: string;
  failure?: { code: string;
  statusCode?: number;
  };
  }>;
  submittedTransactions: number;
  hasAppTransaction: boolean;
  hasReceipt: boolean;
  transactionsComplete: boolean;
  acquisition?: { source: "app_transaction" | "receipt";
  originalAppVersion?: string;
  originalPurchaseDate?: string;
  purchaserComparable: boolean;
  };
  decision: { complete: boolean;
  acquisitionVerified: boolean;
  entitlementIdentifiers: string[];
  acquisitionEntitlementIdentifiers: string[];
  manualEntitlementIdentifiers: string[];
  };
  limitation: string;
  };
  historicalPurchases: unknown;
  receiptPurchases?: ReceiptPurchaseInspection;
  app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  captureId: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: inline route handler.

POST /agent/apps/:appId/purchase-captures/:captureId/replay

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string), captureId (string). Every target must belong to the authenticated app or workspace.

Request

No JSON body is required.

Handler inputs: path.appId, path.captureId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ app: { id: string;
  name: string;
  environment: IdEnvironment;
  liveAppId: string | null;
  };
  captureId: string;
  replay: { original: { complete: boolean;
  acquisitionVerified: boolean;
  entitlementIdentifiers: string[];
  acquisitionEntitlementIdentifiers: string[];
  manualEntitlementIdentifiers: string[];
  transactionResults: { index: number | undefined;
  status: string | undefined;
  entitlementIdentifiers: string[];
  expiresAt: string | null | undefined;
  }[];
  };
  replayed: { complete: boolean;
  acquisitionVerified: boolean;
  entitlementIdentifiers: string[];
  acquisitionEntitlementIdentifiers: string[];
  manualEntitlementIdentifiers: string[];
  transactionResults: { index: number | undefined;
  status: string | undefined;
  entitlementIdentifiers: string[];
  expiresAt: string | null | undefined;
  }[];
  };
  mode: "recorded-inputs";
  signatureVerification: "recorded-outcome";
  matches: boolean;
  sequenceMatches: boolean;
  failed: boolean;
  stage: string | undefined;
  originalFailed: boolean;
  originalStage: string | undefined;
  originalFailure: CapturedAppleFailure | undefined;
  recordedFailures: { kind: string;
  failure: CapturedAppleFailure | undefined;
  }[];
  limitation: string;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: inline route handler.

GET /agent/apps/:appId/purchases/apple-order

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Path parameters: appId (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ appId: string;
  orderId?: string | undefined;
  providerEventId?: string | undefined;
  }

Validation schemas: agentAppleOrderLookupInputSchema in the downloadable schema registry.

Response

Requires apps:read and reports:read for the selected Live app. Supply an Apple orderId of 1–255 characters. This read verifies Apple-signed transactions and returns their existing app customer; customerId: null means the order verified but no purchase record matched. Apple errors and conflicting customers are errors. The lookup never imports purchases or changes access, and it does not establish email or current Apple-account ownership. Check entitlement grants separately.

JSON response shape

{ customerId: string | null;
  transactionIds: string[];
  originalTransactionIds: string[];
  appId: string;
  environment: "live";
  applePurchaseFound: boolean;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleLookupAgentAppleOrder.

POST /agent/apple-ads/report

Authentication: Scoped Agent bearer token. App-restricted tokens can access only allowed apps; workspace operations require workspace-wide access.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ appId: string;
  from: string;
  to: string;
  view: "provider" | "summary" | "breakdown" | "cohorts";
  connectionId?: string | undefined;
  dimension?: "campaign" | "app" | "country" | "placement" | "ad_group" | "ad" | "keyword" | "search_term" | undefined;
  limit?: number | undefined;
  offset?: number | undefined;
  }

Validation schemas: agentAppleAdsReportSchema in the downloadable schema registry.

Response

JSON response shape

{ rows: { campaignId: string;
  campaignName: string;
  country: string | null;
  spendMinorUnits: number;
  impressions: number;
  taps: number;
  installs: number;
  newDownloads: number;
  redownloads: number;
  }[];
  totalRows: number;
  hasMore: boolean;
  nextOffset: number | null;
  source: "apple_ads_api";
  appId: string;
  connectionId: string;
  from: string;
  to: string;
  fetchedAt: string;
  currency: string;
  timezone: string;
  campaignCount: number;
  totals: { spendMinorUnits: number;
  impressions: number;
  taps: number;
  installs: number;
  newDownloads: number;
  redownloads: number;
  };
  warnings: string[];
  view: "provider";
  } | { provider: "apple_ads" | "meta_ads" | "google_ads" | "tiktok_ads";
  appIds: string[];
  period: { startDate: string;
  endDate: string;
  };
  metrics: { spendUsdCents: number;
  providerInstallCount: number;
  providerAcquisitionInstallCount: number;
  providerReactivationInstallCount: number;
  attributedOpenCount: number;
  matchedAttributedOpenCount: number;
  matchedFirstTimePayerCount: number;
  decisionProviderInstallCount: number;
  decisionAttributedOpenCount: number;
  decisionFirstTimePayerCount: number;
  decisionD30GrossRevenueUsdCents: number;
  newDownloadCount: number;
  redownloadCount: number;
  payerCacUsdCents: number | null;
  d0RoasBps: number | null;
  d7RoasBps: number | null;
  d30RoasBps: number | null;
  d90RoasBps: number | null;
  paybackDays: number | null;
  paybackResolution: "checkpoint";
  attributionCoverageBps: number | null;
  proceedsCoverage: "unavailable" | "actual" | "estimated" | "mixed";
  decisionProceedsCoverage: "unavailable" | "actual" | "estimated" | "mixed";
  decisionSpendUsdCents: number;
  paywallViewCount: number;
  trialStartCount: number;
  firstTimePayerCount: number;
  refundCount: number;
  d0GrossRevenueUsdCents: number;
  d7GrossRevenueUsdCents: number;
  d30GrossRevenueUsdCents: number;
  d90GrossRevenueUsdCents: number;
  d0RefundUsdCents: number;
  d7RefundUsdCents: number;
  d30RefundUsdCents: number;
  d90RefundUsdCents: number;
  d0ProceedsUsdCents: number | null;
  d7ProceedsUsdCents: number | null;
  d30ProceedsUsdCents: number | null;
  d90ProceedsUsdCents: number | null;
  d0NetProceedsUsdCents: number | null;
  d7NetProceedsUsdCents: number | null;
  d30NetProceedsUsdCents: number | null;
  d90NetProceedsUsdCents: number | null;
  unpaidPositiveSpendCount: number;
  spendFxIncompleteCount: number;
  proceedsActualCount: number;
  proceedsEstimatedCount: number;
  proceedsMixedCount: number;
  proceedsUnavailableCount: number;
  latestComputedAt: string | null;
  };
  decisionPeriod: { coverageStartDate: string | null;
  startDate: string;
  matureEndDate: string;
  };
  recommendation: AcquisitionRecommendation | null;
  recommendationCounts: { scale: number;
  hold: number;
  reduce: number;
  insufficientData: number;
  };
  mappingRecommendations: { appId: string;
  appMappingId: string;
  recommendation: AcquisitionRecommendation;
  }[];
  decisionWarnings: string[];
  sourceCoverage: { [k: string]: { spendUsdCents: number;
  providerInstallCount: number;
  attributedOpenCount: number;
  newDownloadCount: number;
  redownloadCount: number;
  };
  };
  exactPeriodWarnings: { code: "exact_period_excluded";
  reportSource: "api" | "file_import" | "unresolved";
  granularity: "period" | "day" | "week";
  excludedRowCount: number;
  }[];
  dataFreshness: { reportsPublishedAt: string | null;
  cohortsComputedAt: string | null;
  };
  dataQuality: { attemptedCount: number;
  attributedCount: number;
  developerTestExcludedCount: number;
  retryableErrorCount: number;
  diagnosticMetadataCount: number;
  advancedReportingAvailable: boolean;
  basicReportingAvailable: boolean;
  basicImportedSpendUsdCents: number;
  basicImportedInstallCount: number;
  basicImportedPeriodStart: string | null;
  basicImportedPeriodEnd: string | null;
  };
  appId: string;
  view: "summary";
  } | { rows: { spendUsdCents: number;
  providerInstallCount: number;
  attributedOpenCount: number;
  proceedsCoverage: "unavailable" | "actual" | "estimated" | "mixed";
  paybackDays: number | null;
  paybackResolution: "checkpoint";
  recommendation: AcquisitionRecommendation;
  observedSpendUsdCents: number;
  observedProviderInstallCount: number;
  observedAttributedOpenCount: number;
  observedFirstTimePayerCount: number;
  observedD30GrossRevenueUsdCents: number;
  observedSpendFxComplete: boolean;
  controlsEnabled: boolean;
  allowedActions: string[];
  resourceControl: Record<string, unknown> | null;
  providerAcquisitionInstallCount: number;
  providerReactivationInstallCount: number;
  newDownloadCount: number;
  redownloadCount: number;
  paywallViewCount: number;
  trialStartCount: number;
  firstTimePayerCount: number;
  refundCount: number;
  d0GrossRevenueUsdCents: number;
  d7GrossRevenueUsdCents: number;
  d30GrossRevenueUsdCents: number;
  d90GrossRevenueUsdCents: number;
  d0RefundUsdCents: number;
  d7RefundUsdCents: number;
  d30RefundUsdCents: number;
  d90RefundUsdCents: number;
  d0ProceedsUsdCents: number | null;
  d7ProceedsUsdCents: number | null;
  d30ProceedsUsdCents: number | null;
  d90ProceedsUsdCents: number | null;
  d0NetProceedsUsdCents: number | null;
  d7NetProceedsUsdCents: number | null;
  d30NetProceedsUsdCents: number | null;
  d90NetProceedsUsdCents: number | null;
  unpaidPositiveSpendCount: number;
  spendFxIncompleteCount: number;
  proceedsActualCount: number;
  proceedsEstimatedCount: number;
  proceedsMixedCount: number;
  proceedsUnavailableCount: number;
  latestComputedAt: string | null;
  appId: string;
  appMappingId: string | null;
  reportSource: "api" | "file_import" | "unresolved";
  cohortType: "acquisition" | "reactivation";
  dimension: "campaign" | "app" | "country" | "placement" | "ad_group" | "ad" | "keyword" | "search_term";
  dimensionKey: string;
  dimensionLabel: string | null;
  parentDimension: "campaign" | "app" | "country" | "placement" | "ad_group" | "ad" | "keyword" | "search_term" | null;
  parentDimensionKey: string | null;
  parentDimensionLabel: string | null;
  }[] | { paybackDays: number | null;
  paybackResolution: "checkpoint";
  spendUsdCents: number;
  providerInstallCount: number;
  providerAcquisitionInstallCount: number;
  providerReactivationInstallCount: number;
  attributedOpenCount: number;
  newDownloadCount: number;
  redownloadCount: number;
  paywallViewCount: number;
  trialStartCount: number;
  firstTimePayerCount: number;
  refundCount: number;
  d0GrossRevenueUsdCents: number;
  d7GrossRevenueUsdCents: number;
  d30GrossRevenueUsdCents: number;
  d90GrossRevenueUsdCents: number;
  d0RefundUsdCents: number;
  d7RefundUsdCents: number;
  d30RefundUsdCents: number;
  d90RefundUsdCents: number;
  d0ProceedsUsdCents: number | null;
  d7ProceedsUsdCents: number | null;
  d30ProceedsUsdCents: number | null;
  d90ProceedsUsdCents: number | null;
  d0NetProceedsUsdCents: number | null;
  d7NetProceedsUsdCents: number | null;
  d30NetProceedsUsdCents: number | null;
  d90NetProceedsUsdCents: number | null;
  unpaidPositiveSpendCount: number;
  spendFxIncompleteCount: number;
  proceedsActualCount: number;
  proceedsEstimatedCount: number;
  proceedsMixedCount: number;
  proceedsUnavailableCount: number;
  latestComputedAt: string | null;
  appId: string;
  appMappingId: string | null;
  reportSource: "api" | "file_import" | "unresolved";
  periodStart: string;
  periodEnd: string;
  granularity: "period" | "day" | "week";
  cohortType: "acquisition" | "reactivation";
  }[];
  totalRows: number;
  hasMore: boolean;
  nextOffset: number | null;
  provider: "apple_ads" | "meta_ads" | "google_ads" | "tiktok_ads";
  decisionWarnings: never[];
  sourceCoverage: Record<string, { rowCount: number;
  spendUsdCents: number;
  attributedOpenCount: number;
  }>;
  exactPeriodWarnings: { code: "exact_period_excluded";
  reportSource: "api" | "file_import" | "unresolved";
  granularity: "period" | "day" | "week";
  excludedRowCount: number;
  }[];
  appId: string;
  view: "breakdown" | "cohorts";
  } | { rows: { spendUsdCents: number;
  providerInstallCount: number;
  attributedOpenCount: number;
  proceedsCoverage: "unavailable" | "actual" | "estimated" | "mixed";
  paybackDays: number | null;
  paybackResolution: "checkpoint";
  recommendation: AcquisitionRecommendation;
  observedSpendUsdCents: number;
  observedProviderInstallCount: number;
  observedAttributedOpenCount: number;
  observedFirstTimePayerCount: number;
  observedD30GrossRevenueUsdCents: number;
  observedSpendFxComplete: boolean;
  controlsEnabled: boolean;
  allowedActions: string[];
  resourceControl: Record<string, unknown> | null;
  providerAcquisitionInstallCount: number;
  providerReactivationInstallCount: number;
  newDownloadCount: number;
  redownloadCount: number;
  paywallViewCount: number;
  trialStartCount: number;
  firstTimePayerCount: number;
  refundCount: number;
  d0GrossRevenueUsdCents: number;
  d7GrossRevenueUsdCents: number;
  d30GrossRevenueUsdCents: number;
  d90GrossRevenueUsdCents: number;
  d0RefundUsdCents: number;
  d7RefundUsdCents: number;
  d30RefundUsdCents: number;
  d90RefundUsdCents: number;
  d0ProceedsUsdCents: number | null;
  d7ProceedsUsdCents: number | null;
  d30ProceedsUsdCents: number | null;
  d90ProceedsUsdCents: number | null;
  d0NetProceedsUsdCents: number | null;
  d7NetProceedsUsdCents: number | null;
  d30NetProceedsUsdCents: number | null;
  d90NetProceedsUsdCents: number | null;
  unpaidPositiveSpendCount: number;
  spendFxIncompleteCount: number;
  proceedsActualCount: number;
  proceedsEstimatedCount: number;
  proceedsMixedCount: number;
  proceedsUnavailableCount: number;
  latestComputedAt: string | null;
  appId: string;
  appMappingId: string | null;
  reportSource: "api" | "file_import" | "unresolved";
  cohortType: "acquisition" | "reactivation";
  dimension: "campaign" | "app" | "country" | "placement" | "ad_group" | "ad" | "keyword" | "search_term";
  dimensionKey: string;
  dimensionLabel: string | null;
  parentDimension: "campaign" | "app" | "country" | "placement" | "ad_group" | "ad" | "keyword" | "search_term" | null;
  parentDimensionKey: string | null;
  parentDimensionLabel: string | null;
  }[] | { paybackDays: number | null;
  paybackResolution: "checkpoint";
  spendUsdCents: number;
  providerInstallCount: number;
  providerAcquisitionInstallCount: number;
  providerReactivationInstallCount: number;
  attributedOpenCount: number;
  newDownloadCount: number;
  redownloadCount: number;
  paywallViewCount: number;
  trialStartCount: number;
  firstTimePayerCount: number;
  refundCount: number;
  d0GrossRevenueUsdCents: number;
  d7GrossRevenueUsdCents: number;
  d30GrossRevenueUsdCents: number;
  d90GrossRevenueUsdCents: number;
  d0RefundUsdCents: number;
  d7RefundUsdCents: number;
  d30RefundUsdCents: number;
  d90RefundUsdCents: number;
  d0ProceedsUsdCents: number | null;
  d7ProceedsUsdCents: number | null;
  d30ProceedsUsdCents: number | null;
  d90ProceedsUsdCents: number | null;
  d0NetProceedsUsdCents: number | null;
  d7NetProceedsUsdCents: number | null;
  d30NetProceedsUsdCents: number | null;
  d90NetProceedsUsdCents: number | null;
  unpaidPositiveSpendCount: number;
  spendFxIncompleteCount: number;
  proceedsActualCount: number;
  proceedsEstimatedCount: number;
  proceedsMixedCount: number;
  proceedsUnavailableCount: number;
  latestComputedAt: string | null;
  appId: string;
  appMappingId: string | null;
  reportSource: "api" | "file_import" | "unresolved";
  periodStart: string;
  periodEnd: string;
  granularity: "period" | "day" | "week";
  cohortType: "acquisition" | "reactivation";
  }[];
  totalRows: number;
  hasMore: boolean;
  nextOffset: number | null;
  provider: "apple_ads" | "meta_ads" | "google_ads" | "tiktok_ads";
  dimension: "campaign" | "app" | "country" | "placement" | "ad_group" | "ad" | "keyword" | "search_term";
  decisionWarnings: string[];
  sourceCoverage: Record<string, { rowCount: number;
  spendUsdCents: number;
  attributedOpenCount: number;
  }>;
  exactPeriodWarnings: { code: "exact_period_excluded";
  reportSource: "api" | "file_import" | "unresolved";
  granularity: "period" | "day" | "week";
  excludedRowCount: number;
  }[];
  decisionPeriod: { coverageStartDate: string | null;
  startDate: string;
  matureEndDate: string;
  };
  appId: string;
  view: "breakdown" | "cohorts";
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: inline POST /apple-ads/report.