events 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.

POST /v1/events

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

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

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ error: string;
  message: string;
  retryAfterSeconds: number;
  scope: SdkRateLimitScope;
  }

JSON response shape

{ eventId: string;
  wasDeduped: 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: handleCreateEvent.

POST /v1/events/batch

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

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

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

{ operationId: string;
  state: "cancelled" | "exhausted" | "pending" | "started" | "retrying" | "confirmed" | "no_matching_purchase" | "interrupted";
  attempt: number;
  observedAt: string;
  parentOperationId?: string | null | undefined;
  }

{ 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;
  }

{ occurrenceId: string;
  phase: "startup" | "runtime";
  operation: string;
  domain: string;
  code: string;
  message: string;
  underlyingErrors: { domain: string;
  code: string;
  message: string;
  }[];
  appVersion: string;
  buildNumber: string;
  truncated: boolean;
  stage?: string | undefined;
  migrationIdentifier?: string | undefined;
  relatedCrashReportId?: string | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ error: string;
  message: string;
  retryAfterSeconds: number;
  scope: SdkRateLimitScope;
  }

JSON response shape

{ results: ({ clientId: string;
  status: "accepted" | "deduped" | "rejected";
  eventId?: string;
  error?: string;
  } | 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: handleCreateEventBatch.