usage 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/usage/daily

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.

{ usageDate: string;
  platform: "ios" | "android" | "web" | "windows" | "macos";
  deviceId: string;
  sessionCount: number;
  foregroundSeconds: number;
  firstActiveAt?: string | undefined;
  lastActiveAt?: string | undefined;
  metadata?: { device_model?: string | undefined;
  os_version?: string | undefined;
  app_version?: string | undefined;
  sdk_version?: string | undefined;
  source?: string | undefined;
  } | undefined;
  }

Validation schemas: recordDailyUsageSchema in the downloadable schema registry.

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ ok: true;
  id: 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: handleRecordDailyUsage.

POST /v1/usage/snapshots

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.

{ deviceId: string;
  snapshots: ({ contractVersion: 2;
  producerId: string;
  revision: string;
  usageDate: string;
  firstObservedAt: string;
  lastObservedAt: string;
  instrumentationRevision: string;
  supportedMetrics: { key: string;
  definitionRevision: number;
  }[];
  coverage: "partial" | "measured";
  droppedMeasurementCount: number;
  droppedDiagnosticCount: number;
  measurements: { key: string;
  definitionRevision: number;
  scaledValue: string;
  firstObservedAt: string;
  lastObservedAt: string;
  dimensions: Record<string, string>;
  purchaseContext?: string | undefined;
  }[];
  diagnostics: { metric: { key: string;
  definitionRevision: number;
  };
  reasonDimension: string;
  reason: string;
  occurrences: number;
  firstObservedAt: string;
  lastObservedAt: string;
  recovered: boolean;
  affectedItemCount?: string | undefined;
  }[];
  kind: "daily";
  sessionCount: number;
  foregroundSeconds: number;
  legacySessionBaseline?: number | undefined;
  legacyForegroundBaseline?: number | undefined;
  } | { contractVersion: 2;
  producerId: string;
  revision: string;
  usageDate: string;
  firstObservedAt: string;
  lastObservedAt: string;
  instrumentationRevision: string;
  supportedMetrics: { key: string;
  definitionRevision: number;
  }[];
  coverage: "partial" | "measured";
  droppedMeasurementCount: number;
  droppedDiagnosticCount: number;
  measurements: { key: string;
  definitionRevision: number;
  scaledValue: string;
  firstObservedAt: string;
  lastObservedAt: string;
  dimensions: Record<string, string>;
  purchaseContext?: string | undefined;
  }[];
  diagnostics: { metric: { key: string;
  definitionRevision: number;
  };
  reasonDimension: string;
  reason: string;
  occurrences: number;
  firstObservedAt: string;
  lastObservedAt: string;
  recovered: boolean;
  affectedItemCount?: string | undefined;
  }[];
  kind: "session";
  sessionId: string;
  startedAt: string;
  endedAt: string | null;
  endReason: "explicit" | "background" | "identity_changed" | null;
  foregroundSeconds: number;
  legacySessionBaseline?: number | undefined;
  legacyForegroundBaseline?: number | undefined;
  })[];
  }

{ version: 2;
  appId: string;
  customerId: string;
  transactionId: string;
  entitlementId: string;
  periodStart: string;
  periodEnd: string | null;
  }

Validation schemas: usageSnapshotBatchSchema in the downloadable schema registry.

Response

JSON response shape

{ ok: true;
  records: { sessionId?: string | undefined;
  id: string;
  producerId: string;
  kind: "session" | "daily";
  usageDate: string;
  revision: 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: handleRecordUsageSnapshots.