openapi: 3.1.1 info: version: 1.0.0 title: Corbado API description: | # Introduction This documentation gives an overview of all Corbado API calls to implement authentication observe. contact: name: Corbado team email: support@corbado.com url: https://www.corbado.com servers: - url: https://api.cloud.corbado.io/v1 tags: - name: ObserveFlow description: Flow search and related APIs x-group: Journeys and users - name: ObserveSubFlow description: Subflow search and related APIs x-group: Journeys and users - name: ObserveUser description: User search and related APIs x-group: Journeys and users - name: ObserveClientEnv description: Client environment search APIs x-group: Journeys and users - name: ObserveTimeSeries description: Time series query APIs x-group: Metrics and funnels - name: ObserveFunnel description: Historical funnel metrics, dictionaries and coverage. x-group: Metrics and funnels - name: ObserveEvent description: Event ingestion and event feed APIs x-group: Events - name: ObserveError description: Named authentication errors and recommendations. x-group: Error management - name: ObserveErrorFlavour description: Error variants and their impact on authentication outcomes. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: Annotation APIs (dated notes for analytics context) x-group: Annotations - name: ObserveTableExport description: Table export file listing and download APIs x-group: Data exports - name: ObserveTimeSeriesExport description: Time-series export generation and downloads. x-group: Data exports - name: ObserveDataExport description: Data export APIs x-group: User data - name: ObserveDataDeletionJob description: Data deletion job APIs x-group: User data - name: ObserveFlowTypeDefinition description: Flow type definitions used in authentication journeys. x-group: Catalogs and labels - name: ObserveCatalog description: Catalog APIs x-group: Catalogs and labels - name: OpenAPI description: Downloadable API specification - name: ProjectOperationExecution description: Project-scoped operation history and pipeline health - name: ObserveClassification description: Flow and subflow classification APIs - name: ObserveIntegrationStats description: Integration stats APIs - name: ObserveTimeSeriesPrecalculation description: Time series precalculation APIs - name: ObserveIDList x-group: Saved ID lists description: Stored ID-list selection APIs - name: ObserveDataContext description: Schema-loose data context APIs for agent and debugging tooling - name: ObserveData description: Observe data administration APIs - name: ObserveTrackingStats description: Tracking ingestion stats APIs - name: ObserveExperiment x-group: Experiments description: Experiment catalog and run APIs - name: ObserveDataPolicy description: Project data policy catalogue (retention selected by the SDK's meta.dataPolicy code) - name: ObserveMetadata x-group: Metadata description: Authenticator metadata APIs (FIDO MDS + passkey AAGUID) - name: ObservePasskey x-group: Passkey analysis description: Observed passkey search and cohort analysis. paths: /openapi.yaml: get: x-excluded: true summary: Download the Observe OpenAPI specification operationId: OpenAPISpecGet tags: - OpenAPI security: [] responses: "200": description: Bundled OpenAPI document with local references and documentation exclusion flags content: application/yaml: schema: type: string /operationExecutions/search: post: x-excluded: true operationId: ProjectOperationExecutionSearch summary: Search operation execution history tags: - ProjectOperationExecution security: - bearerAuth: - project:operations:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/operationExecutionSearchReq" responses: "200": description: Project-scoped result content: application/json: schema: $ref: "#/components/schemas/operationExecutionSearchRsp" default: $ref: "#/components/responses/error" description: 'Required API key permission: `project:operations:read`.' /operationExecutions/stats: post: x-excluded: true operationId: ProjectOperationExecutionStats summary: Aggregate execution outcomes and runtime distributions tags: - ProjectOperationExecution security: - bearerAuth: - project:operations:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/operationExecutionStatsReq" responses: "200": description: Project-scoped result content: application/json: schema: $ref: "#/components/schemas/operationExecutionStatsRsp" default: $ref: "#/components/responses/error" description: 'Required API key permission: `project:operations:read`.' /operationExecutions/{executionID}: get: x-excluded: true operationId: ProjectOperationExecutionGet summary: Get an operation execution tags: - ProjectOperationExecution security: - bearerAuth: - project:operations:read parameters: - name: executionID in: path required: true schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ope responses: "200": description: Execution in the authenticated project content: application/json: schema: $ref: "#/components/schemas/operationExecution" default: $ref: "#/components/responses/error" description: 'Required API key permission: `project:operations:read`.' /observe/pipelineQueueState: get: x-excluded: true operationId: ProjectOperationExecutionQueueState summary: Current classification and precalculation queues description: |- Pending work is partitioned into due and deferred. Oldest due time excludes the classification eligibility delay and future scheduled precalculation jobs. Required API key permission: `project:operations:read`. tags: - ProjectOperationExecution security: - bearerAuth: - project:operations:read responses: "200": description: Current project queue state, including explicit zeros for empty queues content: application/json: schema: $ref: "#/components/schemas/operationQueueState" default: $ref: "#/components/responses/error" /observe/config/{projectID}: get: x-excluded: true summary: Get SDK reliability configuration description: Returns the same project configuration and version as event ingestion, without submitting events. Native SDK names select the app policy; omitted or other names select the browser policy. Origin authorization follows the ingestion endpoint. Clients manage configuration freshness locally. operationId: ObserveEventConfigGet tags: - ObserveEvent security: [] parameters: - name: sdkName in: query required: false description: SDK name, matching ingestion sdk.name. observe-android and observe-ios select native app configuration; other values preserve browser configuration. schema: type: string - name: projectID in: path required: true description: ID of project schema: description: ID of project type: string x-oapi-codegen-extra-tags: validate: required,id=pro responses: "200": description: Browser or native app SDK reliability configuration, selected by sdkName. content: application/json: schema: oneOf: - $ref: "#/components/schemas/observeEventCreateRes" - $ref: "#/components/schemas/observeSdkConfigApp" default: $ref: "#/components/responses/error" /observe/events/{projectID}: post: x-excluded: true summary: Create new events description: This event ingestion endpoint does not require authentication and is intended for use by the Corbado Observe SDK. An authenticated version of this endpoint is also available, offering greater flexibility to the caller. operationId: ObserveEventCreateUnauthenticated tags: - ObserveEvent security: [] parameters: - name: projectID in: path required: true description: ID of project schema: description: ID of project type: string x-oapi-codegen-extra-tags: validate: required,id=pro requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeEventCreateReq" responses: "200": description: >- SDK reliability configuration (returned only when the X-Corbado-Observe-Config header is set). The shape depends on the requesting SDK: web SDKs receive observeEventCreateRes, native app SDKs (request `sdk.name` observe-android/observe-ios) receive the app-specific observeSdkConfigApp. content: application/json: schema: oneOf: - $ref: "#/components/schemas/observeEventCreateRes" - $ref: "#/components/schemas/observeSdkConfigApp" "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/events: post: x-mint: href: /api-reference/observe/send-events summary: Create new events description: |- Ingests events from your backend using an API key. For browser and native collection, use the [Observe SDKs](/sdks/overview) and their separate project-scoped transport. ### Server-side enrichment Attach a user reference or tags, such as a risk or bot verdict, to a flow without sending them through the browser. Target a flow by event ID or temporal matching; authenticated enrichment allows a symmetric 10-second matching tolerance. A request accepts at most 2,000 events and low-level events combined. Required API key permission: `observe:events:write`. operationId: ObserveEventCreateAuthenticated tags: - ObserveEvent security: - bearerAuth: - observe:events:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeEventCreateReq" responses: "200": description: >- SDK reliability configuration (returned only when the X-Corbado-Observe-Config header is set). The shape depends on the requesting SDK: web SDKs receive observeEventCreateRes, native app SDKs (request `sdk.name` observe-android/observe-ios) receive the app-specific observeSdkConfigApp. content: application/json: schema: oneOf: - $ref: "#/components/schemas/observeEventCreateRes" - $ref: "#/components/schemas/observeSdkConfigApp" "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/events/feed: get: x-excluded: true summary: List recent events description: |- Lists recent events with classification status computed from latest completed session-classification jobs. Required API key permission: `observe:events:read`. operationId: ObserveEventFeedList tags: - ObserveEvent security: - bearerAuth: - observe:events:read parameters: - name: ingestedAfter in: query required: true description: Filter events ingested after this unix timestamp (in milliseconds). Must be within the last 7 days. schema: type: integer format: int64 x-oapi-codegen-extra-tags: validate: required,min=0 - name: limit in: query required: false description: Maximum number of events to return schema: type: integer format: int32 minimum: 1 maximum: 1000 default: 100 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=1000 - name: sessionID in: query required: false description: Filter events by session ID (UUID format) schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,uuid responses: "200": description: List of recent events with classification status content: application/json: schema: type: array items: $ref: "#/components/schemas/observeEventFeedEntry" default: $ref: "#/components/responses/error" /observe/classifications/run: post: x-excluded: true summary: Run classification for sessions description: |- Runs Observe flow and subflow classification for the provided session IDs. Required API key permission: `observe:classifications:run`. operationId: ObserveClassificationRun tags: - ObserveClassification security: - bearerAuth: - observe:classifications:run requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeClassificationRunReq" responses: "200": description: Classification run completed content: application/json: schema: $ref: "#/components/schemas/observeClassificationRun" default: $ref: "#/components/responses/error" /observe/classifications/ensure: post: x-excluded: true summary: Ensure the latest three sessions of one user are classified description: >- Repairs only missing or outdated ownership data for the user's latest three sessions. Exactly one of userID or externalID is required. Transaction-linked sessions may also be affected. Returns explicit per-session readiness; does not run time-series processing. Required API key permission: `observe:classifications:run`. operationId: ObserveClassificationEnsure tags: - ObserveClassification security: - bearerAuth: - observe:classifications:run requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeClassificationEnsureReq" responses: "200": description: Readiness results for the selected and any affected linked sessions. content: application/json: schema: $ref: "#/components/schemas/observeClassificationEnsure" default: $ref: "#/components/responses/error" /observe/classifications/schedule: get: x-excluded: true summary: Get scheduled classification jobs description: |- Returns the classification jobs scheduled for the authenticated project that have not started yet and when the last of them starts. Use it to see when a scheduled batch will be finished. Required API key permission: `observe:classifications:read`. operationId: ObserveClassificationScheduleGet tags: - ObserveClassification security: - bearerAuth: - observe:classifications:read responses: "200": description: The current backlog. content: application/json: schema: $ref: "#/components/schemas/observeClassificationScheduleBacklog" default: $ref: "#/components/responses/error" post: x-excluded: true summary: Schedule classification jobs for sessions description: |- Schedules one classification job per session for the authenticated project. Jobs start at the project's `manualJobsPerMinute` rate and are added after already scheduled jobs, so you can send a large list of sessions in several calls. Duplicate session IDs are removed. Unknown sessions and sessions with a pending job are skipped, so retrying a call is safe. Required API key permission: `observe:classifications:run`. operationId: ObserveClassificationSchedule tags: - ObserveClassification security: - bearerAuth: - observe:classifications:run requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeClassificationScheduleReq" responses: "200": description: Scheduling result. content: application/json: schema: $ref: "#/components/schemas/observeClassificationScheduleRsp" default: $ref: "#/components/responses/error" /observe/classifications/config: get: x-excluded: true summary: Get the classification config description: |- Returns the classification settings in effect for the authenticated project. Settings the project does not override show their default. Currently covers the scheduling settings, which are read-only. Required API key permission: `observe:classifications:read`. operationId: ObserveClassificationConfigGet tags: - ObserveClassification security: - bearerAuth: - observe:classifications:read responses: "200": description: The effective config. content: application/json: schema: $ref: "#/components/schemas/observeClassificationConfig" default: $ref: "#/components/responses/error" /observe/classificationErrors: get: x-excluded: true summary: List classification errors description: |- Returns a paginated list of classification errors for the authenticated project. Optionally filter by session public ID. Required API key permission: `observe:classifications:read`. operationId: ObserveClassificationErrorList tags: - ObserveClassification security: - bearerAuth: - observe:classifications:read parameters: - name: createdAfter in: query required: true description: Filter classification errors created after this unix timestamp (in milliseconds). schema: type: integer format: int64 x-oapi-codegen-extra-tags: validate: required,min=0 - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 - name: sessionID in: query required: false description: Filter by session public ID (UUID format) schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,uuid - name: type in: query required: false description: Filter by classification error type schema: type: string enum: - flow - sub_flow x-oapi-codegen-extra-tags: validate: omitempty,oneof=flow sub_flow - name: subType in: query required: false description: Filter by flow or subflow subtype (canonical Observe identifier) schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 responses: "200": description: Paginated list of classification errors content: application/json: schema: type: array items: $ref: "#/components/schemas/observeClassificationError" default: $ref: "#/components/responses/error" /observe/integrationStats/run: post: x-excluded: true summary: Trigger integration stats run description: |- Runs integration stats analysis updates time-series enablement. Required API key permission: `observe:integrationStats:run`. operationId: ObserveIntegrationStatsRun tags: - ObserveIntegrationStats security: - bearerAuth: - observe:integrationStats:run responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/integrationStats: get: x-excluded: true summary: Get integration stats description: |- Returns the latest integration stats snapshot. Required API key permission: `observe:integrationStats:read`. operationId: ObserveIntegrationStatsGet tags: - ObserveIntegrationStats security: - bearerAuth: - observe:integrationStats:read responses: "200": description: Integration stats. content: application/json: schema: $ref: "#/components/schemas/integrationStatsGetRsp" default: $ref: "#/components/responses/error" /observe/flowTypeDefinitions: get: x-mint: href: /api-reference/observe/flow-types summary: List flow type definitions description: |- Lists the flow types available for the authenticated project: the built-in definitions shared by all projects plus the project's own custom flow types, which are auto-discovered from the flow names sent during tracking. Required API key permission: `observe:flowTypeDefinitions:read`. operationId: ObserveFlowTypeDefinitionList tags: - ObserveFlowTypeDefinition security: - bearerAuth: - observe:flowTypeDefinitions:read responses: "200": description: Flow type definitions. content: application/json: schema: type: array items: $ref: "#/components/schemas/flowTypeDefinition" default: $ref: "#/components/responses/error" /observe/funnel/metricSeries: post: x-mint: href: /api-reference/observe/funnel-metrics summary: Calculate historical metrics for an exact journey position operationId: ObserveFunnelMetricSeriesGet tags: - ObserveFunnel security: - bearerAuth: - observe:timeSeries:read requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricSeriesRequest'} responses: '200': description: Daily or hourly metrics, including empty buckets content: application/json: schema: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricSeriesResponse'} '400': description: Invalid selection, filters, metrics or range '429': description: Shared history calculation capacity is busy description: 'Required API key permission: `observe:timeSeries:read`.' /observe/funnel/metricSeries/metadata: get: x-mint: href: /api-reference/observe/funnel-metadata summary: Get project-owned history dictionaries and coverage operationId: ObserveFunnelMetricSeriesMetadataGet tags: - ObserveFunnel security: - bearerAuth: - observe:timeSeries:read responses: '200': description: Project-owned history metadata content: application/json: schema: type: object additionalProperties: true description: 'Required API key permission: `observe:timeSeries:read`.' /observe/timeSeries: get: x-mint: href: /api-reference/observe/time-series summary: Get time series data description: |- Retrieves time series data for a project (grouped by time) Required API key permission: `observe:timeSeries:read`. operationId: ObserveTimeSeriesGet tags: - ObserveTimeSeries security: - bearerAuth: - observe:timeSeries:read parameters: - name: fromDate in: query required: true description: Range start as a local datetime without timezone, formatted as YYYY-MM-DDTHH:MM:SS (e.g. "2026-05-20T00:00:00"). schema: type: string pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$' example: "2026-05-20T00:00:00" x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 - name: toDate in: query required: true description: Range end as a local datetime without timezone, formatted as YYYY-MM-DDTHH:MM:SS (e.g. "2026-05-20T00:00:00"). schema: type: string pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$' example: "2026-05-20T00:00:00" x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 - name: interval in: query required: true description: > Aggregation interval. hourly, daily and monthly read the precalculated data. 1m and 5m are dynamic intervals: they are never stored, so the definition's query is run live over the whole range (at most 8 hours, buckets aligned to UTC) and every bucket is flagged live. Dynamic intervals cannot be combined with experimentRunID or flowListID. schema: $ref: "#/components/schemas/observeTimeSeriesReadInterval" x-oapi-codegen-extra-tags: validate: required,oneof=hourly daily monthly 1m 5m - name: name in: query required: true description: Time series name schema: type: string x-oapi-codegen-extra-tags: validate: required - name: groupBy in: query required: false description: > Comma-separated dimension keys to keep; collapsed dimensions are summed. Allowed: applicationId, browser, os, osVersion, customTag1..6, t1..t10. Omitted keeps full detail. schema: type: string example: "t2,applicationId" x-oapi-codegen-extra-tags: validate: omitempty - name: engagement in: query required: false description: > Flow-series filter: engaged keeps rows whose flow reached a subflow or nested flow, or resolved a decision; non-engaged keeps the rest, i.e. flows that were only routed and abandoned. Only valid for login, signup, enrollment, and recovery flow series. Defaults to all. schema: type: string enum: - all - engaged - non-engaged example: "engaged" x-oapi-codegen-extra-tags: validate: omitempty,oneof=all engaged non-engaged - name: experimentRunID in: query required: false description: |- Optional experiment run ID (format `exr-`). When set (and the run evaluates this series), each returned series is partitioned by the run's variants: every series carries an extra "variant" dimension (the variant ID, or "-" for the unexposed remainder), so summing across "variant" reproduces the unscoped series. When empty, the response is unchanged. schema: type: string example: "exr-123456" x-oapi-codegen-extra-tags: validate: omitempty - name: experimentExposure in: query required: false description: > Experiment exposure scope. "exposed" returns only the share of each series attributed to one of the run's variants: no "-" remainder is synthesized, and flows never assigned to the experiment are excluded entirely. Requires experimentRunID naming a run that evaluates this series. Defaults to all (remainder included). schema: type: string enum: - all - exposed example: "exposed" x-oapi-codegen-extra-tags: validate: omitempty,oneof=all exposed - name: flowListID in: query required: false description: |- Renders the series over an explicit cohort of flows instead of the precalculated data (format `idl-`, from POST /observe/idLists). The definition's own query is run on demand, scoped to those flow ids and with NO time predicate — the list is the selection, whenever those flows happened — so fromDate/toDate only set the (single) bucket the result is stamped with. The panel is otherwise identical in shape, including groupBy, facets and engagement filtering. Requires a flow-id capable definition (currently the flow series: login-flow-v1, signup-flow-v1, security-enrollment-flow-v1, recovery-flow-v1, custom-flow-v1); other definitions return a validation error. Cannot be combined with experimentRunID. The definition's own scoping still applies, so a list mixing flow types renders only the flows this series is about. schema: type: string example: "idl-123456" x-oapi-codegen-extra-tags: validate: omitempty,id=idl - name: live in: query required: false description: > Live recalculation of precalculated data. latest runs the definition's query live for the currently open bucket (the one containing now) instead of reading its stored, possibly stale snapshot; closed buckets keep reading the stored data. Has no effect when the range does not contain the open bucket. Only valid with the hourly interval and cannot be combined with experimentRunID or flowListID. schema: $ref: "#/components/schemas/observeTimeSeriesLiveMode" x-oapi-codegen-extra-tags: validate: omitempty,oneof=latest responses: "200": description: Time series data grouped by time content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesGetRsp" "429": description: Live read capacity is busy, retry later default: $ref: "#/components/responses/error" /observe/timeSeriesDefinitions: get: x-mint: href: /api-reference/observe/time-series-definitions summary: List time-series definitions description: |- Returns the full catalog of time-series definitions. Required API key permission: `observe:timeSeries:read`. operationId: ObserveTimeSeriesDefinitionList tags: - ObserveTimeSeries security: - bearerAuth: - observe:timeSeries:read responses: "200": description: Time-series definition catalog. content: application/json: schema: type: array maxItems: 10000 items: $ref: "#/components/schemas/observeTimeSeriesDefinition" default: $ref: "#/components/responses/error" /observe/timeSeriesPrecalculationConfig: get: x-excluded: true summary: Get time-series precalculation config description: |- Returns the time-series precalculation config for the authenticated project. Required API key permission: `observe:timeSeriesPrecalculation:read`. operationId: ObserveTimeSeriesPrecalculationConfigGet tags: - ObserveTimeSeriesPrecalculation security: - bearerAuth: - observe:timeSeriesPrecalculation:read responses: "200": description: The precalculation config. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationConfig" default: $ref: "#/components/responses/error" put: x-excluded: true summary: Update time-series precalculation config description: >- Updates the time-series precalculation config for the authenticated project. Definition settings are merged, not replaced: each entry in `definitions` upserts the settings for that definition, definitions not listed keep their current settings, and omitting `definitions` updates only the mode. Required API key permission: `observe:timeSeriesPrecalculation:write`. operationId: ObserveTimeSeriesPrecalculationConfigUpdate tags: - ObserveTimeSeriesPrecalculation security: - bearerAuth: - observe:timeSeriesPrecalculation:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationConfigUpdateReq" responses: "200": description: The updated precalculation config. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationConfig" default: $ref: "#/components/responses/error" /observe/timeSeriesPrecalculationConfig/schedule: post: x-excluded: true summary: Trigger time-series precalculation scheduler description: |- Triggers the precalculation scheduler for the authenticated project. Required API key permission: `observe:timeSeriesPrecalculation:write`. operationId: ObserveTimeSeriesPrecalculationScheduleTrigger tags: - ObserveTimeSeriesPrecalculation security: - bearerAuth: - observe:timeSeriesPrecalculation:write responses: "200": description: Number of jobs scheduled. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationScheduleRsp" default: $ref: "#/components/responses/error" /observe/timeSeriesPrecalculationConfig/manualSchedule: post: x-excluded: true summary: Schedule manual time-series precalculation jobs description: |- Enqueues one-off manual precalculation jobs for specific time-series definitions, intervals, and windows. Required API key permission: `observe:timeSeriesPrecalculation:write`. operationId: ObserveTimeSeriesPrecalculationManualSchedule tags: - ObserveTimeSeriesPrecalculation security: - bearerAuth: - observe:timeSeriesPrecalculation:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationManualScheduleReq" responses: "200": description: Number of jobs scheduled. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationScheduleRsp" default: $ref: "#/components/responses/error" /observe/timeSeriesPrecalculationJobSearch: post: x-excluded: true summary: Search time-series precalculation jobs description: |- Searches time-series precalculation jobs for the authenticated project. Required API key permission: `observe:timeSeriesPrecalculation:read`. operationId: ObserveTimeSeriesPrecalculationJobSearch tags: - ObserveTimeSeriesPrecalculation security: - bearerAuth: - observe:timeSeriesPrecalculation:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJobSearchReq" responses: "200": description: Matching precalculation jobs. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJobSearchRsp" default: $ref: "#/components/responses/error" /observe/timeSeriesPrecalculationJobCounts: get: x-excluded: true summary: Get time-series precalculation job counts description: |- Returns true precalculation job counts grouped by status for the authenticated project. Required API key permission: `observe:timeSeriesPrecalculation:read`. operationId: ObserveTimeSeriesPrecalculationJobCounts tags: - ObserveTimeSeriesPrecalculation security: - bearerAuth: - observe:timeSeriesPrecalculation:read responses: "200": description: Job counts per status. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJobCounts" default: $ref: "#/components/responses/error" /observe/timeSeriesPrecalculationJobs/{jobID}/run: post: x-excluded: true summary: Run a time-series precalculation job description: |- Runs a single precalculation job synchronously and returns its resulting status. Required API key permission: `observe:timeSeriesPrecalculation:write`. operationId: ObserveTimeSeriesPrecalculationJobRun tags: - ObserveTimeSeriesPrecalculation security: - bearerAuth: - observe:timeSeriesPrecalculation:write parameters: - name: jobID in: path required: true description: |- The ID of the precalculation job to run (format `tpj-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=tpj responses: "200": description: The job after running, with its resulting status. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJob" default: $ref: "#/components/responses/error" /observe/timeSeriesPrecalculationJobs/{jobID}: delete: x-excluded: true summary: Delete a pending time-series precalculation job description: |- Deletes a single still-pending precalculation job. Running, completed, and failed jobs cannot be deleted. Required API key permission: `observe:timeSeriesPrecalculation:delete`. operationId: ObserveTimeSeriesPrecalculationJobDelete tags: - ObserveTimeSeriesPrecalculation security: - bearerAuth: - observe:timeSeriesPrecalculation:delete parameters: - name: jobID in: path required: true description: |- The ID of the precalculation job to delete (format `tpj-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=tpj responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/timeSeries/precalculate: post: x-excluded: true summary: Precalculate time series data description: >- Runs on-demand time series precalculation for a project. Without a request body (or with an empty body) only the most recent window is recomputed. Provide fromDate and toDate together to recompute an explicit historical range (e.g. after backfilling events). Required API key permission: `observe:timeSeries:precalculate`. operationId: ObserveTimeSeriesPrecalculate tags: - ObserveTimeSeries security: - bearerAuth: - observe:timeSeries:precalculate requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculateReq" responses: "200": description: Time series precalculation completed content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesPrecalculate" default: $ref: "#/components/responses/error" /observe/timeSeries/export: post: x-mint: href: /api-reference/observe/create-time-series-export summary: Export time series to downloadable files description: |- Exports one or more precalculated time series as CSV or Parquet, one file per series, using a shared date range and interval. Each row represents a non-zero time-bucket and dimension combination, with `time`, `timeLocal`, retained dimensions in canonical order and `value`. `time` is the UTC bucket start (RFC 3339 in CSV, timestamp in Parquet); `timeLocal` uses the project timezone reported in `timeZone`. Dimensions in `excludeColumns` are collapsed and their values summed, as when omitted from `groupBy`. Generation runs while the request remains open. The response streams progress as `application/x-ndjson`; the final event is `completed` with the export descriptor or `failed`. Retrieve files using the [download-link endpoint](/api-reference/observe/time-series-export-download) before `expiresAtMs`. Validation errors return a regular JSON error before streaming starts. Exceeding the project's concurrent-export limit or daily quota returns HTTP 429. Required API key permission: `observe:timeSeries:read`. operationId: ObserveTimeSeriesExport tags: - ObserveTimeSeriesExport security: - bearerAuth: - observe:timeSeries:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesExportReq" responses: "200": description: Newline-delimited JSON progress stream; the final line carries the export descriptor. content: application/x-ndjson: schema: $ref: "#/components/schemas/observeTimeSeriesExportEvent" default: $ref: "#/components/responses/error" /observe/timeSeries/exports: get: x-mint: href: /api-reference/observe/time-series-exports summary: List time series exports description: |- Lists the project's time series exports, newest first. Exports whose files have been removed after their retention period are listed with status `expired`. Required API key permission: `observe:timeSeries:read`. operationId: ObserveTimeSeriesExportList tags: - ObserveTimeSeriesExport security: - bearerAuth: - observe:timeSeries:read parameters: - name: limit in: query required: false description: Maximum number of exports to return (default 25, maximum 100). schema: type: integer x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=100 - name: status in: query required: false description: Return only exports with this status. schema: $ref: "#/components/schemas/observeTimeSeriesExportStatus" x-oapi-codegen-extra-tags: validate: omitempty,oneof=pending running completed failed expired responses: "200": description: Time series exports of the project. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesExportList" default: $ref: "#/components/responses/error" /observe/timeSeries/exports/{exportID}: get: x-mint: href: /api-reference/observe/time-series-export summary: Get a time series export by ID operationId: ObserveTimeSeriesExportGet tags: - ObserveTimeSeriesExport security: - bearerAuth: - observe:timeSeries:read parameters: - name: exportID in: path required: true description: |- ID of the export (format `tse-`) schema: type: string x-oapi-codegen-extra-tags: validate: required,id=tse responses: "200": description: Time series export descriptor. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesExport" default: $ref: "#/components/responses/error" description: 'Required API key permission: `observe:timeSeries:read`.' /observe/timeSeries/exports/{exportID}/files/{fileName}/downloadLink: get: x-mint: href: /api-reference/observe/time-series-export-download summary: Get a download link for a time series export file description: |- Returns a short-lived download URL for one file of a completed time series export. The file name is the `file.name` of the export descriptor. Required API key permission: `observe:timeSeries:read`. operationId: ObserveTimeSeriesExportDownloadLinkGet tags: - ObserveTimeSeriesExport security: - bearerAuth: - observe:timeSeries:read parameters: - name: exportID in: path required: true description: |- ID of the export (format `tse-`) schema: type: string x-oapi-codegen-extra-tags: validate: required,id=tse - name: fileName in: path required: true description: File name as returned in the export descriptor, e.g. login-flow-v1.csv schema: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=255 responses: "200": description: Time series export file download link. content: application/json: schema: $ref: "#/components/schemas/observeTimeSeriesExportDownloadLink" default: $ref: "#/components/responses/error" /observe/dataDeletionJobs: post: description: |- Accepts 1 to 1,000 external user IDs and returns one asynchronous deletion job per ID. A successful response queues the jobs; use each job ID to check completion. See [User data requests](/api-reference/observe/user-data). Required API key permission: `observe:dataDeletionJobs:write`. x-mint: href: /api-reference/observe/delete-user-data summary: Create data deletion jobs operationId: ObserveDataDeletionJobCreate tags: - ObserveDataDeletionJob security: - bearerAuth: - observe:dataDeletionJobs:write requestBody: required: true content: application/json: example: externalIDs: - example-user-id schema: $ref: "#/components/schemas/observeDataDeletionJobCreateReq" responses: "200": description: Data deletion jobs created content: application/json: schema: type: array items: $ref: "#/components/schemas/observeDataDeletionJob" default: $ref: "#/components/responses/error" /observe/dataDeletionJobs/{dataDeletionJobID}: get: x-mint: href: /api-reference/observe/deletion-status summary: Get a data deletion job by ID operationId: ObserveDataDeletionJobGet tags: - ObserveDataDeletionJob security: - bearerAuth: - observe:dataDeletionJobs:read parameters: - name: dataDeletionJobID in: path required: true description: ID of the data deletion job schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ddj responses: "200": description: Data deletion job details content: application/json: schema: $ref: "#/components/schemas/observeDataDeletionJob" default: $ref: "#/components/responses/error" description: 'Required API key permission: `observe:dataDeletionJobs:read`.' /observe/dataExports/{externalID}: get: description: |- Use the external user ID supplied by your integration, not an internal Observe user ID. URL-encode it as one path segment. See [User data requests](/api-reference/observe/user-data). Required API key permission: `observe:dataExports:read`. x-mint: href: /api-reference/observe/export-user summary: Export observe data by external ID operationId: ObserveDataExportGet tags: - ObserveDataExport security: - bearerAuth: - observe:dataExports:read parameters: - name: externalID in: path required: true description: External user ID schema: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=255 responses: "200": description: Data export grouped by table name content: application/json: schema: $ref: "#/components/schemas/observeDataExport" default: $ref: "#/components/responses/error" /observe/tableExports: get: x-mint: href: /api-reference/observe/table-exports summary: List observe table export files description: |- Lists the daily table export files available for download for the authenticated project. With no query parameters, all available exports are returned. Use the optional filters to narrow the result to specific export dates or a specific table. `date`, `from`/`to`, and `lastDays` select export dates and are mutually exclusive. Dates are interpreted in the project's configured timezone. Required API key permission: `observe:tableExports:read`. operationId: ObserveTableExportList tags: - ObserveTableExport security: - bearerAuth: - observe:tableExports:read parameters: - name: date in: query required: false description: Return exports for this export date (YYYY-MM-DD). Cannot be combined with from/to or lastDays. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,datetime=2006-01-02 - name: from in: query required: false description: Start export date of an inclusive date range (YYYY-MM-DD). Must be combined with to. Cannot be combined with date or lastDays. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,datetime=2006-01-02 - name: to in: query required: false description: End export date of an inclusive date range (YYYY-MM-DD). Must be combined with from. Cannot be combined with date or lastDays. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,datetime=2006-01-02 - name: lastDays in: query required: false description: | Return exports for the most recent days, ending with yesterday (the current day is not included). Cannot be combined with date or from/to. Maximum 92. schema: type: integer x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=92 - name: table in: query required: false description: Return exports for this table only. Defaults to all exported tables. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=64 responses: "200": description: Observe table export files available for download. content: application/json: schema: $ref: "#/components/schemas/observeTableExportList" default: $ref: "#/components/responses/error" /observe/tableExports/{filename}/downloadLink: get: x-mint: href: /api-reference/observe/table-export-download summary: Get observe table export download link description: |- Returns a short-lived download URL for an Observe table export file. Slashes in the filename path parameter must be URL-encoded. Required API key permission: `observe:tableExports:read`. operationId: ObserveTableExportDownloadLinkGet tags: - ObserveTableExport security: - bearerAuth: - observe:tableExports:read parameters: - name: filename in: path required: true description: Table export filename as returned by /observe/tableExports, with slashes URL-encoded. schema: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=255 responses: "200": description: Observe table export download link. content: application/json: schema: $ref: "#/components/schemas/observeTableExportDownloadLink" default: $ref: "#/components/responses/error" /observe/decisions: get: x-mint: href: /api-reference/observe/decisions summary: List decisions description: |- Lists Observe decisions for the authenticated project. Required API key permission: `observe:catalog:read`. operationId: ObserveDecisionList tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:read responses: "200": description: Decisions. content: application/json: schema: type: array items: $ref: "#/components/schemas/observeDecision" default: $ref: "#/components/responses/error" /observe/decisionVariants: get: x-mint: href: /api-reference/observe/decision-variants summary: List decision variants description: |- Lists Observe decision variants for the authenticated project. Optionally filters variants by parent decision ID. Required API key permission: `observe:catalog:read`. operationId: ObserveDecisionVariantList tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:read parameters: - name: decisionID in: query required: false description: |- Filter variants by the parent decision ID returned by /observe/decisions (format `dec-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=dec responses: "200": description: Decision variants. content: application/json: schema: type: array items: $ref: "#/components/schemas/observeDecisionVariant" default: $ref: "#/components/responses/error" /observe/challengeVariants: get: x-mint: href: /api-reference/observe/challenge-variants summary: List challenge variants description: |- Lists Observe challenge/config variants (format `chv-`) for the authenticated project — the distinct WebAuthn request/response configurations observed per subflow type (e.g. a passkey-login request variant carries allowCredentialCount, timeout, userVerification, hints and the estimated authenticator names behind the allowlist). Optionally filters by subflow type. Use this to resolve the configVariantID returned by /observe/subFlows or the t8 dimension of the login-subflow-passkey-v1 time series into readable configuration data. Required API key permission: `observe:catalog:read`. operationId: ObserveChallengeVariantList tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:read parameters: - name: subFlowType in: query required: false description: Filter variants by subflow type. schema: type: string enum: - passkey-login - passkey-enrollment x-oapi-codegen-extra-tags: validate: "omitempty,oneof=passkey-login passkey-enrollment" responses: "200": description: Challenge variants. content: application/json: schema: type: array items: $ref: "#/components/schemas/observeChallengeVariant" default: $ref: "#/components/responses/error" /observe/metadata/mds: get: x-mint: href: /api-reference/observe/authenticator-metadata summary: List FIDO MDS authenticator metadata description: >- Returns FIDO Metadata Service (MDS) authenticator entries. Pass a comma-separated list of FIDO2 AAGUIDs to look up specific authenticators (AAGUIDs with no matching entry are omitted from the response), or omit the aaguids parameter to return the full catalog. Use this to display authenticator details (name, icon, transports, certification status) for passkey credentials, e.g. YubiKeys. This is global reference data and is not project-scoped. Required API key permission: `observe:metadata:read`. operationId: ObserveMetadataMdsList tags: - ObserveMetadata security: - bearerAuth: - observe:metadata:read parameters: - name: aaguids in: query required: false description: Optional comma-separated authenticator AAGUIDs (UUID format) to look up. If omitted, all entries are returned. style: form explode: false schema: type: array items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=100,dive,uuid responses: "200": description: FIDO MDS authenticator metadata entries. content: application/json: schema: type: array items: $ref: "#/components/schemas/observeMdsEntry" default: $ref: "#/components/responses/error" /observe/metadata/passkey-aaguid: get: x-mint: href: /api-reference/observe/passkey-authenticator-metadata summary: List passkey authenticator (AAGUID) metadata description: >- Returns passkey/platform-authenticator metadata (name + light/dark icons) from the community passkey-authenticator-aaguids catalog. Pass a comma-separated list of AAGUIDs to look up specific authenticators (AAGUIDs with no matching entry are omitted from the response), or omit the aaguids parameter to return the full catalog. Use this to display authenticator details for platform passkeys, e.g. iCloud Keychain or Google Password Manager. This is global reference data and is not project-scoped. Required API key permission: `observe:metadata:read`. operationId: ObserveMetadataPasskeyAaguidList tags: - ObserveMetadata security: - bearerAuth: - observe:metadata:read parameters: - name: aaguids in: query required: false description: Optional comma-separated authenticator AAGUIDs (UUID format) to look up. If omitted, all entries are returned. style: form explode: false schema: type: array items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=100,dive,uuid responses: "200": description: Passkey authenticator (AAGUID) metadata entries. content: application/json: schema: type: array items: $ref: "#/components/schemas/observePasskeyAaguid" default: $ref: "#/components/responses/error" /observe/idLists/{id}: get: x-mint: href: /api-reference/observe/id-list summary: Get Observe ID list description: |- Returns a project-scoped stored flow ID selection by ID-list handle. Required API key permission: `observe:idLists:read`. operationId: ObserveIDListGet tags: - ObserveIDList security: - bearerAuth: - observe:idLists:read parameters: - name: id in: path required: true description: |- ID-list handle (format `idl-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=idl responses: "200": description: Observe ID list. content: application/json: schema: $ref: "#/components/schemas/observeIDList" default: $ref: "#/components/responses/error" /observe/idLists: post: x-mint: href: /api-reference/observe/create-id-list summary: Create Observe ID list description: |- Stores a project-scoped flow ID selection and returns a short ID-list handle. Required API key permission: `observe:idLists:write`. operationId: ObserveIDListCreate tags: - ObserveIDList security: - bearerAuth: - observe:idLists:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeIDListCreateReq" responses: "200": description: Observe ID list created. content: application/json: schema: $ref: "#/components/schemas/observeIDListCreateRsp" default: $ref: "#/components/responses/error" /observe/flowSearch: post: x-mint: href: /api-reference/observe/search-flows summary: Search flows by filter criteria description: |- Finds Observe flows that match the provided filters. Provide at least one of the following filters: `userIDs`, `flowIDs`, `sessionIDs`, or a complete `fromDate` / `toDate` range. When provided, the date range may span at most 366 days. Results are ordered as a stable timeline, oldest first (by creation time), and capped at `limit`. Required API key permission: `observe:flow:read`. operationId: ObserveFlowSearch tags: - ObserveFlow security: - bearerAuth: - observe:flow:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeFlowSearchReq" responses: "200": description: Matching flows plus the total match count. content: application/json: schema: $ref: "#/components/schemas/observeFlowSearchRsp" default: $ref: "#/components/responses/error" /observe/subFlowSearch: post: x-mint: href: /api-reference/observe/search-subflows summary: Search subflows by filter criteria description: |- Finds subflows using exactly one selector: `userIDs`, `flowIDs`, `sessionIDs` or `filters`. The `filters` selector searches a time window with optional error, environment and subflow filters. ID-based results are ordered by start time, oldest first. Filter-based results are newest first and include `totalCount` (uncapped matches) and `flowIDs` (distinct parent flows). All results are capped at `limit`. Required API key permission: `observe:subFlows:read`. operationId: ObserveSubFlowSearch tags: - ObserveSubFlow security: - bearerAuth: - observe:subFlows:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeSubFlowSearchReq" responses: "200": description: Matching subflows. content: application/json: schema: $ref: "#/components/schemas/observeSubFlowSearchRsp" default: $ref: "#/components/responses/error" /observe/eventSearch: post: x-mint: href: /api-reference/observe/search-events summary: Search events by filter criteria description: |- Finds SDK tracking events for selected flows. Use the flow IDs returned by flow search to inspect the event timeline behind those flows. Results are ordered as a stable timeline, oldest first (by creation time), and capped at `limit`. Required API key permission: `observe:events:read`. operationId: ObserveEventSearch tags: - ObserveEvent security: - bearerAuth: - observe:events:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeEventSearchReq" responses: "200": description: Matching SDK tracking events in their original session order. content: application/json: schema: $ref: "#/components/schemas/observeEventSearchRsp" default: $ref: "#/components/responses/error" /observe/uiPatternSearch: post: x-excluded: true summary: Search UI patterns by filter criteria description: |- Finds low-level UI patterns detected from Observe tracking events. Results can be selected by sessions or subflows. Results are ordered as a stable timeline, oldest first (by start time), and capped at `limit`. Required API key permission: `observe:events:read`. operationId: ObserveUIPatternSearch tags: - ObserveEvent security: - bearerAuth: - observe:events:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeUIPatternSearchReq" responses: "200": description: Matching UI patterns. content: application/json: schema: $ref: "#/components/schemas/observeUIPatternSearchRsp" default: $ref: "#/components/responses/error" /observe/subFlowErrorSearch: post: x-excluded: true summary: Search subflow error occurrences by filter criteria description: |- Finds subflow error occurrences detected during classification. Results can be selected by sessions or subflows; an optional flavour filter narrows them further. Entries reference their raw-signature flavour (`erf-`) only — resolve signature details and the mapped error via the error flavour list. Results are ordered as a stable timeline, oldest first (by occurrence time), and capped at `limit`. Required API key permission: `observe:events:read`. operationId: ObserveSubFlowErrorSearch tags: - ObserveEvent security: - bearerAuth: - observe:events:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeSubFlowErrorSearchReq" responses: "200": description: Matching subflow error occurrences. content: application/json: schema: $ref: "#/components/schemas/observeSubFlowErrorSearchRsp" default: $ref: "#/components/responses/error" /observe/trackingEventBatchSearch: post: x-excluded: true summary: Search tracking event batches by filter criteria description: |- Finds tracking event ingestion batches. Provide at least one of `sessionIDs` or `batchIDs`; `createdAfterMs` / `createdBeforeMs` further narrow the results but cannot be used on their own. Results are ordered as a stable timeline, oldest first (by creation time), and capped at `limit`. Required API key permission: `observe:events:read`. operationId: ObserveTrackingEventBatchSearch tags: - ObserveEvent security: - bearerAuth: - observe:events:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeTrackingEventBatchSearchReq" responses: "200": description: Matching tracking event batches. content: application/json: schema: $ref: "#/components/schemas/observeTrackingEventBatchSearchRsp" default: $ref: "#/components/responses/error" /observe/trackingEventLowSearch: post: x-mint: href: /api-reference/observe/search-low-events summary: Search low-level tracking events by filter criteria description: |- Finds low-level tracking events (raw UI interaction signals) as they were ingested. Provide at least one of `sessionIDs` or `batchIDs`; `types`, `createdAfterMs` and `createdBeforeMs` further narrow the results but cannot be used on their own. Results are ordered as a stable timeline, oldest first (by client capture time), and capped at `limit`. Required API key permission: `observe:events:read`. operationId: ObserveTrackingEventLowSearch tags: - ObserveEvent security: - bearerAuth: - observe:events:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeTrackingEventLowSearchReq" responses: "200": description: Matching low-level tracking events. content: application/json: schema: $ref: "#/components/schemas/observeTrackingEventLowSearchRsp" default: $ref: "#/components/responses/error" /observe/trackingStats: get: x-excluded: true summary: Get tracking ingestion stats description: |- Returns raw ingestion stats for Observe tracking tables over the last 60 minutes. Required API key permission: `observe:trackingStats:read`. operationId: ObserveTrackingStatsGet tags: - ObserveTrackingStats security: - bearerAuth: - observe:trackingStats:read responses: "200": description: Tracking ingestion stats. content: application/json: schema: $ref: "#/components/schemas/trackingStats" default: $ref: "#/components/responses/error" /observe/flowTagSearch: post: x-mint: href: /api-reference/observe/search-flow-tags summary: Search flow tags description: |- Finds Observe flow tags for selected flows. Required API key permission: `observe:flow:read`. operationId: ObserveFlowTagSearch tags: - ObserveFlow security: - bearerAuth: - observe:flow:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeFlowTagSearchReq" responses: "200": description: Matching flow tags. content: application/json: schema: type: array items: $ref: "#/components/schemas/observeFlowTag" default: $ref: "#/components/responses/error" /observe/userSearch: post: x-mint: href: /api-reference/observe/search-users summary: Search users by filter criteria description: |- Finds Observe users by a single search criterion, such as user ID, external ID, a prefix match, or related flow IDs. Use this endpoint to locate users before opening their Observe context or investigating their flows. Required API key permission: `observe:user:read`. operationId: ObserveUserSearch tags: - ObserveUser security: - bearerAuth: - observe:user:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeUserSearchReq" responses: "200": description: Users matching the search criterion, ordered by creation time (newest first). content: application/json: schema: type: array items: $ref: "#/components/schemas/observeUser" default: $ref: "#/components/responses/error" /observe/passkeyCohort: post: x-mint: href: /api-reference/observe/passkey-cohort summary: List passkey behaviour for a user cohort description: >- Returns a raw (non-aggregated) per-user list of passkey behaviour for a cohort of confirmed users defined by creation time window (fromMs/toMs) and capped at maxGroupSize. Each entry carries the user's passkeys plus compact passkey login/enrollment outcome summaries, so the caller can categorise passkey enablement client-side. Scoped to the project of the bearer token. Required API key permission: `observe:passkeys:read`. operationId: ObservePasskeyCohortList tags: - ObservePasskey security: - bearerAuth: - observe:passkeys:read requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observePasskeyCohortReq' responses: '200': description: Per-user passkey behaviour list for the cohort content: application/json: schema: type: array items: $ref: '#/components/schemas/observePasskeyCohortUser' default: $ref: "#/components/responses/error" /observe/passkeySearch: post: x-mint: href: /api-reference/observe/search-passkeys summary: Search passkeys description: |- Finds observed passkeys for selected Observe users. Required API key permission: `observe:passkeys:read`. operationId: ObservePasskeySearch tags: - ObservePasskey security: - bearerAuth: - observe:passkeys:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observePasskeySearchReq" responses: "200": description: Matching passkeys. content: application/json: schema: type: array items: $ref: "#/components/schemas/observePasskey" default: $ref: "#/components/responses/error" /observe/clientEnvSearch: post: x-mint: href: /api-reference/observe/search-client-environments summary: Search client environments description: |- Finds observed client environments for selected Observe users. Required API key permission: `observe:clientEnvs:read`. operationId: ObserveClientEnvSearch tags: - ObserveClientEnv security: - bearerAuth: - observe:clientEnvs:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeClientEnvSearchReq" responses: "200": description: Matching client environments. content: application/json: schema: type: array items: $ref: "#/components/schemas/observeClientEnv" default: $ref: "#/components/responses/error" /observe/applications: get: x-mint: href: /api-reference/observe/applications summary: List applications description: |- Lists Observe applications. Required API key permission: `observe:catalog:read`. operationId: ObserveApplicationList tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:read responses: "200": description: Applications. content: application/json: schema: type: array maxItems: 10000 items: $ref: "#/components/schemas/application" default: $ref: "#/components/responses/error" /observe/emailDomains: get: x-mint: href: /api-reference/observe/email-domains summary: List email domains description: |- Lists all normalized email domains observed in this project. Required API key permission: `observe:catalog:read`. operationId: ObserveEmailDomainList tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:read responses: "200": description: Email domains. content: application/json: schema: type: array items: $ref: "#/components/schemas/observeEmailDomain" default: $ref: "#/components/responses/error" /observe/labels: get: x-mint: href: /api-reference/observe/labels summary: List labels description: |- Lists Observe labels by entity type. Required API key permission: `observe:catalog:read`. operationId: ObserveLabelList tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:read parameters: - name: entityType in: query required: true description: The entity type to filter labels by. schema: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=50 responses: "200": description: Labels. content: application/json: schema: type: array maxItems: 10000 items: $ref: "#/components/schemas/observeLabel" default: $ref: "#/components/responses/error" post: x-mint: href: /api-reference/observe/create-label summary: Create label description: |- Creates an Observe label. Required API key permission: `observe:catalog:write`. operationId: ObserveLabelCreate tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeLabelCreateReq" responses: "200": description: Label created. content: application/json: schema: $ref: "#/components/schemas/observeLabel" default: $ref: "#/components/responses/error" /observe/labels/{labelID}: put: x-mint: href: /api-reference/observe/update-label summary: Update label description: |- Updates an Observe label. Required API key permission: `observe:catalog:write`. operationId: ObserveLabelUpdate tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:write parameters: - name: labelID in: path required: true description: |- Label ID (format `lbl-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=lbl requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeLabelUpdateReq" responses: "200": description: Label updated. content: application/json: schema: $ref: "#/components/schemas/observeLabel" default: $ref: "#/components/responses/error" delete: x-mint: href: /api-reference/observe/delete-label summary: Delete label description: |- Deletes an Observe label. Required API key permission: `observe:catalog:delete`. operationId: ObserveLabelDelete tags: - ObserveCatalog security: - bearerAuth: - observe:catalog:delete parameters: - name: labelID in: path required: true description: |- Label ID (format `lbl-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=lbl responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/annotations: get: x-mint: href: /api-reference/observe/annotations summary: List annotations description: |- Lists Observe annotations, optionally filtered to a time window by dateMs. Paginated; sorted by createdMs (default descending). Required API key permission: `observe:annotations:read`. operationId: ObserveAnnotationList tags: - ObserveAnnotation security: - bearerAuth: - observe:annotations:read parameters: - name: fromMs in: query required: false description: Only return annotations with dateMs greater than or equal to this value (epoch ms). schema: type: integer format: int64 x-oapi-codegen-extra-tags: validate: omitempty,min=0 - name: toMs in: query required: false description: Only return annotations with dateMs less than or equal to this value (epoch ms). schema: type: integer format: int64 x-oapi-codegen-extra-tags: validate: omitempty,min=0 - name: orderBy in: query required: false description: Field to order by schema: type: string default: created enum: - created - date x-oapi-codegen-extra-tags: validate: omitempty,oneof=created date - name: orderDirection in: query required: false description: Order direction schema: type: string default: desc enum: - asc - desc x-oapi-codegen-extra-tags: validate: omitempty,oneof=asc desc - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 responses: "200": description: Paginated list of annotations. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers. content: application/json: schema: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeAnnotation" default: $ref: "#/components/responses/error" post: x-mint: href: /api-reference/observe/create-annotation summary: Create annotation description: |- Creates an Observe annotation. Required API key permission: `observe:annotations:write`. operationId: ObserveAnnotationCreate tags: - ObserveAnnotation security: - bearerAuth: - observe:annotations:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeAnnotationCreateReq" responses: "200": description: Annotation created. content: application/json: schema: $ref: "#/components/schemas/observeAnnotation" default: $ref: "#/components/responses/error" /observe/annotations/{annotationID}: put: x-mint: href: /api-reference/observe/update-annotation summary: Update annotation description: |- Updates an Observe annotation. Required API key permission: `observe:annotations:write`. operationId: ObserveAnnotationUpdate tags: - ObserveAnnotation security: - bearerAuth: - observe:annotations:write parameters: - name: annotationID in: path required: true description: |- Annotation ID (format `ann-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ann requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeAnnotationUpdateReq" responses: "200": description: Annotation updated. content: application/json: schema: $ref: "#/components/schemas/observeAnnotation" default: $ref: "#/components/responses/error" delete: x-mint: href: /api-reference/observe/delete-annotation summary: Delete annotation description: |- Deletes an Observe annotation. Required API key permission: `observe:annotations:delete`. operationId: ObserveAnnotationDelete tags: - ObserveAnnotation security: - bearerAuth: - observe:annotations:delete parameters: - name: annotationID in: path required: true description: |- Annotation ID (format `ann-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ann responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/errorFlavours: get: x-mint: href: /api-reference/observe/error-flavours summary: List error flavours description: |- Lists all error flavours of the project (content-addressed raw error signatures; capped per project, so the full list is returned unpaged). Occurrence statistics are NOT included — counts and recency come from the `subflow-error-flavour-v1` time series, keyed by the raw flavour id in t1. Required API key permission: `observe:errorFlavours:read`. operationId: ObserveErrorFlavourList tags: - ObserveErrorFlavour security: - bearerAuth: - observe:errorFlavours:read responses: "200": description: All error flavours of the project, sorted by first-seen (descending). content: application/json: schema: type: array maxItems: 100000 items: $ref: "#/components/schemas/observeErrorFlavour" default: $ref: "#/components/responses/error" patch: x-mint: href: /api-reference/observe/assign-error-flavours summary: Assign error flavours description: |- Bulk-assigns the given error flavours to an error (or unassigns them when errorID is omitted). Flavours not belonging to the project are ignored. An error never mixes subflow types: the assigned flavours must share one subflow type, which must match the error's stamped scope (stamped on first assignment, cleared when the last member is unassigned or moved away). Violations return a validation error. Required API key permission: `observe:errorFlavours:write`. operationId: ObserveErrorFlavourAssign tags: - ObserveErrorFlavour security: - bearerAuth: - observe:errorFlavours:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeErrorFlavourAssignReq" responses: "200": description: Assignment applied. content: application/json: schema: $ref: "#/components/schemas/observeErrorFlavourAssignRsp" default: $ref: "#/components/responses/error" /observe/errorFlavours/impact: post: x-mint: href: /api-reference/observe/error-impact summary: Analyze the flow impact of error flavours description: |- Compares completion for engaged real-user flows affected by the selected error flavours with all engaged real-user flows of the same types and date range. The baseline includes affected flows. Engagement requires a subflow, nested flow or resolved decision, matching the time-series `engagement=engaged` filter. Results show correlation, not causation; flows may carry other errors. Each group includes up to `flowLimit` flows, newest first (default 5,000; maximum 50,000). When capped, `sampled: true` means all reported metrics use that sample. `analyzedFlowLimit` reports the applied cap; `flowListID` identifies the exact analyzed flows. The baseline `completionRate` weights rates by the affected group's `osName`/`browserName` mix. `rawCompletionRate` reports the unweighted baseline rate. Outcomes `skipped`, `invisible` and `visible-auto-skip` count as `other` and are excluded from completion rates. Occurrences without flows are reported as orphans and excluded from rates. `baseline` is absent when no comparable engaged flows exist. Use naive UTC datetimes (`YYYY-MM-DDTHH:mm:ss`) for the half-open interval [fromDate, toDate), with a maximum range of 30 days. Required API key permission: `observe:errorFlavours:read`. operationId: ObserveErrorFlavourImpact tags: - ObserveErrorFlavour security: - bearerAuth: - observe:errorFlavours:read requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeErrorFlavourImpactReq" responses: "200": description: Impact analysis for the given flavours and range. content: application/json: schema: $ref: "#/components/schemas/observeErrorFlavourImpactRsp" default: $ref: "#/components/responses/error" /observe/errors: get: x-mint: href: /api-reference/observe/errors-list summary: List errors description: |- Lists the project's curated errors (the labels flavours are mapped to). Occurrence rollups are computed client-side from the flavour list. Required API key permission: `observe:errors:read`. operationId: ObserveErrorList tags: - ObserveError security: - bearerAuth: - observe:errors:read responses: "200": description: All errors of the project, sorted by creation time (descending). content: application/json: schema: type: array maxItems: 10000 items: $ref: "#/components/schemas/observeError" default: $ref: "#/components/responses/error" post: x-mint: href: /api-reference/observe/create-error summary: Create error description: |- Creates a curated error, optionally assigning an initial set of flavours to it in the same request. Required API key permission: `observe:errors:write`. operationId: ObserveErrorCreate tags: - ObserveError security: - bearerAuth: - observe:errors:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeErrorCreateReq" responses: "200": description: Error created. content: application/json: schema: $ref: "#/components/schemas/observeError" default: $ref: "#/components/responses/error" /observe/errors/{errorID}: put: x-mint: href: /api-reference/observe/update-error summary: Update error description: |- Updates a curated error's name, description, type, and severity. The subflow scope is auto-managed via flavour assignment and cannot be set here. Required API key permission: `observe:errors:write`. operationId: ObserveErrorUpdate tags: - ObserveError security: - bearerAuth: - observe:errors:write parameters: - name: errorID in: path required: true description: |- Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeErrorUpdateReq" responses: "200": description: Error updated. content: application/json: schema: $ref: "#/components/schemas/observeError" default: $ref: "#/components/responses/error" delete: x-mint: href: /api-reference/observe/delete-error summary: Delete error description: |- Deletes a curated error. Its member flavours are unassigned (they return to the unmapped inbox); occurrence data is untouched. Required API key permission: `observe:errors:delete`. operationId: ObserveErrorDelete tags: - ObserveError security: - bearerAuth: - observe:errors:delete parameters: - name: errorID in: path required: true description: |- Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/errors/{errorID}/recommendation: put: x-mint: href: /api-reference/observe/upsert-error-recommendation summary: Upsert error recommendation description: >- Creates or fully replaces the error's recommendation (an error has at most one). Full-replace semantics like the error update: every field is taken from this request, so omitting annotationID reopens a resolved recommendation (the linked annotation IS the resolution). Required API key permission: `observe:errors:write`. operationId: ObserveErrorRecommendationUpsert tags: - ObserveError security: - bearerAuth: - observe:errors:write parameters: - name: errorID in: path required: true description: |- Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeErrorRecommendationUpsertReq" responses: "200": description: The stored recommendation. content: application/json: schema: $ref: "#/components/schemas/observeErrorRecommendation" default: $ref: "#/components/responses/error" delete: x-mint: href: /api-reference/observe/delete-error-recommendation summary: Delete error recommendation description: |- Removes the error's recommendation. The error itself is untouched. Required API key permission: `observe:errors:write`. operationId: ObserveErrorRecommendationDelete tags: - ObserveError security: - bearerAuth: - observe:errors:write parameters: - name: errorID in: path required: true description: |- Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/errors/{errorID}/recommendation/assets: post: x-mint: href: /api-reference/observe/create-recommendation-asset-upload summary: Create recommendation asset upload description: >- Registers a media asset (screenshot or video) on the error's recommendation and returns a short-lived presigned URL the browser PUTs the file to directly — the API never proxies the bytes. The upload must send exactly the declared content type. After uploading, call the confirm endpoint to verify the object and make the asset servable. Fails when no assets store is configured in this environment. Required API key permission: `observe:errors:write`. operationId: ObserveErrorRecommendationAssetCreate tags: - ObserveError security: - bearerAuth: - observe:errors:write parameters: - name: errorID in: path required: true description: |- Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeAssetCreateReq" responses: "200": description: The pending asset plus the presigned upload URL. content: application/json: schema: $ref: "#/components/schemas/observeAssetCreateRsp" default: $ref: "#/components/responses/error" /observe/errors/{errorID}/recommendation/assets/{assetID}: delete: x-mint: href: /api-reference/observe/delete-recommendation-asset summary: Delete recommendation asset description: |- Removes the asset (metadata and stored object). Required API key permission: `observe:errors:write`. operationId: ObserveErrorRecommendationAssetDelete tags: - ObserveError security: - bearerAuth: - observe:errors:write parameters: - name: errorID in: path required: true description: |- Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err - name: assetID in: path required: true description: |- Asset ID (format `ast-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ast responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/errors/{errorID}/recommendation/assets/{assetID}/confirm: post: x-mint: href: /api-reference/observe/confirm-recommendation-asset-upload summary: Confirm recommendation asset upload description: >- Verifies the uploaded object against the declared upload (size, content type) and makes the asset servable. Idempotent — confirming an already-ready asset returns it unchanged. Fails with a validation error when no object arrived yet or it does not match the declaration. Required API key permission: `observe:errors:write`. operationId: ObserveErrorRecommendationAssetConfirm tags: - ObserveError security: - bearerAuth: - observe:errors:write parameters: - name: errorID in: path required: true description: |- Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err - name: assetID in: path required: true description: |- Asset ID (format `ast-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ast responses: "200": description: The confirmed (ready) asset. content: application/json: schema: $ref: "#/components/schemas/observeAsset" default: $ref: "#/components/responses/error" /observe/errors/{errorID}/recommendation/assets/{assetID}/downloadUrl: get: x-mint: href: /api-reference/observe/recommendation-asset-download summary: Get recommendation asset download URL description: >- Mints a short-lived presigned URL for viewing a ready asset. URLs are meant to be requested per view, not stored. Required API key permission: `observe:errors:read`. operationId: ObserveErrorRecommendationAssetDownloadURL tags: - ObserveError security: - bearerAuth: - observe:errors:read parameters: - name: errorID in: path required: true description: |- Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err - name: assetID in: path required: true description: |- Asset ID (format `ast-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ast responses: "200": description: The presigned view URL. content: application/json: schema: $ref: "#/components/schemas/observeAssetDownloadUrlRsp" default: $ref: "#/components/responses/error" /observe/alertSummary: get: x-mint: href: /api-reference/observe/alert-summary summary: Get alerting summary description: |- Returns project-wide counts and status summaries for alert rules and instances, plus the latest scheduled evaluation activity. Takes no filters. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertSummaryGet tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read responses: "200": description: Alerting summary for the project. content: application/json: schema: $ref: "#/components/schemas/observeAlertSummary" default: $ref: "#/components/responses/error" /observe/alertRules: get: x-mint: href: /api-reference/observe/alert-rules summary: List alert rules description: |- Lists Observe alert rules for the project. Paginated; sorted by createdMs (default descending). Required API key permission: `observe:alerts:read`. operationId: ObserveAlertRuleList tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: status in: query required: false description: Filter by rule status. schema: type: string enum: - active - paused x-oapi-codegen-extra-tags: validate: omitempty,oneof=active paused - name: ruleType in: query required: false description: Filter by rule type. schema: type: string enum: - login_success_rate x-oapi-codegen-extra-tags: validate: omitempty,oneof=login_success_rate - name: name in: query required: false description: > Filter to rules whose name contains this text, case-insensitively. A substring match rather than a prefix one, because someone searching for "checkout" means the rule with checkout anywhere in its name. Wildcards in the term are matched literally. schema: type: string maxLength: 255 x-oapi-codegen-extra-tags: validate: omitempty,max=255 - name: instanceStatus in: query required: false description: > Filter to rules that have at least one alert in any of these statuses - comma-separated, and read as "or". This is what selecting a status card above the rules list asks for, and it is a different question from `status`, which is whether the rule itself is running. Omitting it is not the same as listing every status: a rule that has never been evaluated has no alerts at all, and belongs in the unfiltered list. style: form explode: false schema: type: array maxItems: 5 items: type: string enum: - normal - pending - firing - no_data - error x-oapi-codegen-extra-tags: validate: omitempty,max=5,unique,dive,oneof=normal pending firing no_data error - name: orderDirection in: query required: false description: Order direction by creation time. schema: type: string default: desc enum: - asc - desc x-oapi-codegen-extra-tags: validate: omitempty,oneof=asc desc - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 responses: "200": description: Paginated list of alert rules. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers. content: application/json: schema: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeAlertRule" default: $ref: "#/components/responses/error" post: x-mint: href: /api-reference/observe/create-alert-rule summary: Create alert rule description: |- Creates an Observe alert rule and stores its configuration. Does not evaluate the rule. Required API key permission: `observe:alerts:write`. operationId: ObserveAlertRuleCreate tags: - ObserveAlert security: - bearerAuth: - observe:alerts:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeAlertRuleCreateReq" responses: "200": description: Alert rule created. content: application/json: schema: $ref: "#/components/schemas/observeAlertRule" default: $ref: "#/components/responses/error" /observe/alertRules/{alertRuleID}: get: x-mint: href: /api-reference/observe/alert-rule summary: Get alert rule description: |- Returns a single Observe alert rule. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertRuleGet tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: alertRuleID in: path required: true description: |- Alert rule ID (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=aru responses: "200": description: Alert rule. content: application/json: schema: $ref: "#/components/schemas/observeAlertRule" default: $ref: "#/components/responses/error" put: x-mint: href: /api-reference/observe/update-alert-rule summary: Update alert rule description: |- Updates an Observe alert rule. Required API key permission: `observe:alerts:write`. operationId: ObserveAlertRuleUpdate tags: - ObserveAlert security: - bearerAuth: - observe:alerts:write parameters: - name: alertRuleID in: path required: true description: |- Alert rule ID (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=aru requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeAlertRuleUpdateReq" responses: "200": description: Alert rule updated. content: application/json: schema: $ref: "#/components/schemas/observeAlertRule" default: $ref: "#/components/responses/error" delete: x-mint: href: /api-reference/observe/delete-alert-rule summary: Delete alert rule description: |- Permanently deletes an Observe alert rule and all of its child rows (instances, evaluations, transitions and notifications). Required API key permission: `observe:alerts:delete`. operationId: ObserveAlertRuleDelete tags: - ObserveAlert security: - bearerAuth: - observe:alerts:delete parameters: - name: alertRuleID in: path required: true description: |- Alert rule ID (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=aru responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/alerts/evaluate: post: x-mint: href: /api-reference/observe/evaluate-alert-rules summary: Evaluate alert rules description: |- Evaluates active alert rules immediately, using the current time. Writes alert instances, transitions and evaluation records, and sends any resulting notifications. Returns when evaluation completes. Omit the body or `alertRuleID` to evaluate all active rules; provide `alertRuleID` to evaluate one. Paused rules are skipped, including an explicitly selected rule (`evaluated: 0`). The evaluation time cannot be overridden. Required API key permission: `observe:alerts:write`. operationId: ObserveAlertEvaluate tags: - ObserveAlert security: - bearerAuth: - observe:alerts:write requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/observeAlertEvaluateReq" responses: "200": description: Alert evaluation completed. content: application/json: schema: $ref: "#/components/schemas/observeAlertEvaluate" default: $ref: "#/components/responses/error" /observe/alertContactPoints: get: x-mint: href: /api-reference/observe/alert-contact-points summary: List alert contact points description: |- Lists the project's alert contact points and their integrations. Each contact point is a named notification destination that can contain multiple integrations, each with its own type. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertContactPointList tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 responses: "200": description: Paginated list of contact points, by name. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers. content: application/json: schema: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeAlertContactPoint" default: $ref: "#/components/responses/error" post: x-mint: href: /api-reference/observe/create-alert-contact-point summary: Create alert contact point description: |- Creates a contact point and its integrations. Required API key permission: `observe:alerts:write`. operationId: ObserveAlertContactPointCreate tags: - ObserveAlert security: - bearerAuth: - observe:alerts:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeAlertContactPointCreateReq" responses: "200": description: Contact point created. content: application/json: schema: $ref: "#/components/schemas/observeAlertContactPoint" default: $ref: "#/components/responses/error" /observe/alertContactPoints/{alertContactPointID}: get: x-mint: href: /api-reference/observe/alert-contact-point summary: Get alert contact point description: |- Returns one contact point with its integrations. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertContactPointGet tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: alertContactPointID in: path required: true description: |- Alert contact point ID (format `acp-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=acp responses: "200": description: Alert contact point. content: application/json: schema: $ref: "#/components/schemas/observeAlertContactPoint" default: $ref: "#/components/responses/error" put: x-mint: href: /api-reference/observe/update-alert-contact-point summary: Update alert contact point description: >- Replaces the contact point and its integration set. An integration listed with an id keeps that id; one listed without an id is created; one that is no longer listed is retired, not erased, so the delivery history that references it still resolves. Required API key permission: `observe:alerts:write`. operationId: ObserveAlertContactPointUpdate tags: - ObserveAlert security: - bearerAuth: - observe:alerts:write parameters: - name: alertContactPointID in: path required: true description: |- Alert contact point ID (format `acp-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=acp requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeAlertContactPointUpdateReq" responses: "200": description: Contact point updated. content: application/json: schema: $ref: "#/components/schemas/observeAlertContactPoint" default: $ref: "#/components/responses/error" delete: x-mint: href: /api-reference/observe/delete-alert-contact-point summary: Delete alert contact point description: |- Permanently deletes a contact point and its integrations. Rejected while an alert rule still references it. Required API key permission: `observe:alerts:delete`. operationId: ObserveAlertContactPointDelete tags: - ObserveAlert security: - bearerAuth: - observe:alerts:delete parameters: - name: alertContactPointID in: path required: true description: |- Alert contact point ID (format `acp-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=acp responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/alertRuleTypes: get: x-mint: href: /api-reference/observe/alert-rule-types summary: List alert rule types description: >- Lists the alert rule types that can be created, described for the authenticated project. The rule builder renders itself from this: `available` says whether the project has the data the type reads, and `dimensions` are the keys a rule of that type can be grouped by here, including the project's own time-series tags. A type with `available` false, or a `groupBy` key not listed here, is rejected when the rule is saved. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertRuleTypeList tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read responses: "200": description: Alert rule types, ordered by ruleType. content: application/json: schema: type: array maxItems: 100 items: $ref: "#/components/schemas/observeAlertRuleType" default: $ref: "#/components/responses/error" /observe/alertInstances: get: x-mint: href: /api-reference/observe/alert-instances summary: List alert instances description: |- Lists Observe alert instances for the project. Paginated; newest-evaluated first unless orderBy says otherwise. Empty until the alerting evaluator runs. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertInstanceList tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: alertRuleID in: query required: false description: |- Filter to instances of a single alert rule (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=aru - name: alertInstanceID in: query required: false description: |- Filter to a single alert instance (format `ain-`), so an alert email can deep-link to exactly the alert it names. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=ain - name: status in: query required: false description: > Filter by instance status - comma-separated, and read as "or". A set rather than one value because the panel's status cards are a multi-select: asking for firing and pending separately would page the two answers independently and leave them impossible to merge into one ordered list. style: form explode: false schema: type: array maxItems: 5 items: type: string enum: - normal - pending - firing - no_data - error x-oapi-codegen-extra-tags: validate: omitempty,max=5,unique,dive,oneof=normal pending firing no_data error - name: ruleName in: query required: false description: > Filter to alerts whose rule's name contains this text, so one search box can serve both the rules list and the flat alert list. It filters and does not project: the alerts that come back carry their rule's id, as they always do, and not its name. schema: type: string maxLength: 255 x-oapi-codegen-extra-tags: validate: omitempty,max=255 - name: orderBy in: query required: false description: > Field to order by. lastEvaluated, the default, is the order the panel's lists open in; the others are the columns those lists can be sorted on. status orders by urgency (normal, no_data, error, pending, firing) and severity by level (info, warning, critical) rather than alphabetically, so descending puts the alert that needs attention first; ties within such a column resolve newest-evaluated first. An instance with no value for the field - never notified, no severity yet - sorts as the lowest. schema: type: string default: lastEvaluated enum: - lastEvaluated - status - severity - currentValue - lastStatusChange - lastNotification x-oapi-codegen-extra-tags: validate: omitempty,oneof=lastEvaluated status severity currentValue lastStatusChange lastNotification - name: orderDirection in: query required: false description: Order direction. schema: type: string default: desc enum: - asc - desc x-oapi-codegen-extra-tags: validate: omitempty,oneof=asc desc - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 responses: "200": description: Paginated list of alert instances. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers. content: application/json: schema: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeAlertInstance" default: $ref: "#/components/responses/error" /observe/alertInstanceStatistics: get: x-mint: href: /api-reference/observe/alert-instance-statistics summary: Get alert instance statistics description: |- Returns an alert instance's hourly evaluation aggregates and status timeline with per-status totals. Only evaluated hours have buckets. The timeline starts with the status held at `fromMs`, using the last preceding transition. Evaluations have shorter retention than transitions; expired history returns empty results rather than an error. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertInstanceStatisticsGet tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: alertInstanceID in: query required: true description: |- The alert instance to describe (format `ain-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ain - name: fromMs in: query required: true description: Window start (epoch ms, inclusive). schema: type: integer format: int64 x-oapi-codegen-extra-tags: validate: required - name: toMs in: query required: true description: Window end (epoch ms, exclusive). Must be after fromMs; the window may span at most 366 days. schema: type: integer format: int64 x-oapi-codegen-extra-tags: validate: required responses: "200": description: Statistics for the alert instance over the window. content: application/json: schema: $ref: "#/components/schemas/observeAlertInstanceStatistics" default: $ref: "#/components/responses/error" /observe/alertEvaluations: get: x-mint: href: /api-reference/observe/alert-evaluations summary: List alert evaluations description: >- Lists Observe alert evaluation records for the project - one row per alert per evaluation run, written by the evaluator. Paginated; newest-evaluated first. Empty until the alerting evaluator runs, and retained for a shorter period than transitions. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertEvaluationList tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: alertRuleID in: query required: false description: |- Filter to evaluations of a single alert rule (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=aru - name: alertInstanceID in: query required: false description: |- Filter to evaluations of a single alert instance (format `ain-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=ain - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 responses: "200": description: Paginated list of alert evaluations. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers. content: application/json: schema: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeAlertEvaluation" default: $ref: "#/components/responses/error" /observe/alertTransitions: get: x-mint: href: /api-reference/observe/alert-transitions summary: List alert transitions description: |- Lists the append-only status-change history of the project's alerts, including the silent transitions that never produced a notification. Paginated; newest first. One flat collection with filters rather than a nested route, so the same endpoint answers both "what happened to this alert" (alertInstanceID) and "what has this rule been doing" (alertRuleID). Required API key permission: `observe:alerts:read`. operationId: ObserveAlertTransitionList tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: alertRuleID in: query required: false description: |- Filter to transitions of a single alert rule (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=aru - name: alertInstanceID in: query required: false description: |- Filter to transitions of a single alert instance (format `ain-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=ain - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 responses: "200": description: Paginated list of alert transitions. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers. content: application/json: schema: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeAlertTransition" default: $ref: "#/components/responses/error" /observe/alertNotifications: get: x-mint: href: /api-reference/observe/alert-notifications summary: List alert notifications description: |- Lists Observe alert notification delivery attempts for the project. Paginated; newest first. Empty until the alerting evaluator delivers notifications. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertNotificationList tags: - ObserveAlert security: - bearerAuth: - observe:alerts:read parameters: - name: alertRuleID in: query required: false description: |- Filter to notifications of a single alert rule (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=aru - name: alertInstanceID in: query required: false description: |- Filter to notifications of a single alert instance (format `ain-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=ain - name: status in: query required: false description: Filter by delivery status. schema: type: string enum: - pending - sent - failed x-oapi-codegen-extra-tags: validate: omitempty,oneof=pending sent failed - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 responses: "200": description: Paginated list of alert notifications. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers. content: application/json: schema: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeAlertNotification" default: $ref: "#/components/responses/error" /observe/experiments: get: x-mint: href: /api-reference/observe/experiments summary: List experiments description: |- Lists Observe experiments and their variants. Required API key permission: `observe:experiments:read`. operationId: ObserveExperimentList tags: - ObserveExperiment security: - bearerAuth: - observe:experiments:read responses: "200": description: Experiments with their variants. content: application/json: schema: type: array maxItems: 10000 items: $ref: "#/components/schemas/observeExperiment" default: $ref: "#/components/responses/error" /observe/experimentRuns: get: x-mint: href: /api-reference/observe/experiment-runs summary: List experiment runs description: |- Lists configured Observe experiment runs. Required API key permission: `observe:experiments:read`. operationId: ObserveExperimentRunList tags: - ObserveExperiment security: - bearerAuth: - observe:experiments:read responses: "200": description: Experiment runs. content: application/json: schema: type: array maxItems: 10000 items: $ref: "#/components/schemas/observeExperimentRun" default: $ref: "#/components/responses/error" post: x-mint: href: /api-reference/observe/create-experiment-run summary: Create experiment run description: |- Creates an Observe experiment run. Required API key permission: `observe:experiments:write`. operationId: ObserveExperimentRunCreate tags: - ObserveExperiment security: - bearerAuth: - observe:experiments:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeExperimentRunCreateReq" responses: "200": description: Experiment run created. content: application/json: schema: $ref: "#/components/schemas/observeExperimentRun" default: $ref: "#/components/responses/error" /observe/experimentRuns/{experimentRunID}: put: x-mint: href: /api-reference/observe/update-experiment-run summary: Update experiment run description: |- Updates an Observe experiment run. Required API key permission: `observe:experiments:write`. operationId: ObserveExperimentRunUpdate tags: - ObserveExperiment security: - bearerAuth: - observe:experiments:write parameters: - name: experimentRunID in: path required: true description: |- Experiment run ID (format `exr-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=exr requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeExperimentRunUpdateReq" responses: "200": description: Experiment run updated. content: application/json: schema: $ref: "#/components/schemas/observeExperimentRun" default: $ref: "#/components/responses/error" delete: x-mint: href: /api-reference/observe/delete-experiment-run summary: Delete experiment run description: |- Deletes an Observe experiment run. Required API key permission: `observe:experiments:delete`. operationId: ObserveExperimentRunDelete tags: - ObserveExperiment security: - bearerAuth: - observe:experiments:delete parameters: - name: experimentRunID in: path required: true description: |- Experiment run ID (format `exr-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=exr responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/dataPolicies: get: x-excluded: true summary: List data policies description: |- Lists the project's data policies, ordered by code. A data policy is selected by the integer code the SDK reports in `meta.dataPolicy`; code 0 is the project's default policy and applies to every session that never reported a code. Required API key permission: `observe:dataPolicies:read`. operationId: ObserveDataPolicyList tags: - ObserveDataPolicy security: - bearerAuth: - observe:dataPolicies:read responses: "200": description: Data policies. content: application/json: schema: type: array maxItems: 256 items: $ref: "#/components/schemas/observeDataPolicy" default: $ref: "#/components/responses/error" post: x-excluded: true summary: Create data policy description: |- Creates a data policy. The code must be unused in the project and is immutable afterwards: stored sessions reference it, so it must keep its meaning for as long as data captured under it exists. Codes carry no ordering. Required API key permission: `observe:dataPolicies:write`. operationId: ObserveDataPolicyCreate tags: - ObserveDataPolicy security: - bearerAuth: - observe:dataPolicies:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeDataPolicyCreateReq" responses: "200": description: Data policy created. content: application/json: schema: $ref: "#/components/schemas/observeDataPolicy" default: $ref: "#/components/responses/error" /observe/dataPolicies/{dataPolicyID}: put: x-excluded: true summary: Update data policy description: |- Updates the name and retention days of a data policy. The code cannot be changed. Required API key permission: `observe:dataPolicies:write`. operationId: ObserveDataPolicyUpdate tags: - ObserveDataPolicy security: - bearerAuth: - observe:dataPolicies:write parameters: - name: dataPolicyID in: path required: true description: |- Data policy ID (format `dpo-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=dpo requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/observeDataPolicyUpdateReq" responses: "200": description: Data policy updated. content: application/json: schema: $ref: "#/components/schemas/observeDataPolicy" default: $ref: "#/components/responses/error" delete: x-excluded: true summary: Delete data policy description: |- Deletes a data policy. Sessions that reference the code keep their stored value; retention treats an unknown code as "no policy configured" for that session. Deleting code 0 removes the project's default policy. Required API key permission: `observe:dataPolicies:delete`. operationId: ObserveDataPolicyDelete tags: - ObserveDataPolicy security: - bearerAuth: - observe:dataPolicies:delete parameters: - name: dataPolicyID in: path required: true description: |- Data policy ID (format `dpo-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=dpo responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/data/reset: post: x-excluded: true summary: Reset Observe data description: |- Resets Observe tracking, flow, time-series, and related data for the authenticated project. Required API key permission: `observe:data:delete`. operationId: ObserveDataReset tags: - ObserveData security: - bearerAuth: - observe:data:delete responses: "204": $ref: "#/components/responses/204" default: $ref: "#/components/responses/error" /observe/dataContext/configuration: get: x-excluded: true summary: Get observe data context configuration snapshot description: |- Returns an allowlisted, project-scoped snapshot of Observe configuration tables (project metadata, time series catalog, applications, flow type definitions, decisions, decision variants, labels) together with relationship metadata. All rows are filtered server-side by the project ID resolved from the bearer API key. Endpoints under `/v1/observe/dataContext/*` are deliberately schema-loose and exist to provide rich, self-describing context for downstream tooling. There is no compatibility contract — fields may be added, renamed, or removed between releases. Required API key permission: `observe:dataContext:read`. operationId: ObserveDataContextConfigurationGet tags: - ObserveDataContext security: - bearerAuth: - observe:dataContext:read responses: "200": description: Project-scoped configuration snapshot. The exact shape may change between releases. content: application/json: schema: type: object additionalProperties: true default: $ref: "#/components/responses/error" /observe/dataContext/flows: get: x-excluded: true summary: Get observe flow rows description: |- Returns all flows for one session, one user, one flow ID — or a batch of up to 500 sessions/flows via the plural `sessionIDs`/`flowIDs` selectors. Batch selection replaces N serial single-ID calls with one; rows carry `session_public_id` and `flow_id_public` so the caller can group them. Endpoint is schema-loose and has no compatibility contract. Required API key permission: `observe:dataContext:read`. operationId: ObserveDataContextFlowsGet tags: - ObserveDataContext security: - bearerAuth: - observe:dataContext:read parameters: - name: sessionID in: query required: false description: Session ID (UUID format). Mutually exclusive with the other selectors. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,uuid - name: userID in: query required: false description: |- User ID (format `tus-`). Mutually exclusive with the other selectors. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=tus - name: flowID in: query required: false description: |- Flow ID (format `flw-`). Mutually exclusive with the other selectors. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=flw - name: sessionIDs in: query required: false description: Comma-separated session IDs (UUID format), max 500. Mutually exclusive with the other selectors. schema: type: string - name: flowIDs in: query required: false description: |- Comma-separated flow IDs (format `flw-`), max 500. Mutually exclusive with the other selectors. schema: type: string responses: "200": description: Flow rows for the selected session, user, or flow. The exact shape may change between releases. content: application/json: schema: type: object additionalProperties: true default: $ref: "#/components/responses/error" /observe/dataContext/subFlows: get: x-excluded: true summary: Get observe subflow rows description: |- Returns all subflows for one session, one user, one flow ID — or a batch of up to 500 sessions/flows via the plural `sessionIDs`/`flowIDs` selectors — grouped by subflow type. Rows carry `session_public_id` and `flow_id_public` so batched results can be grouped by the caller. Endpoint is schema-loose and has no compatibility contract. Required API key permission: `observe:dataContext:read`. operationId: ObserveDataContextSubFlowsGet tags: - ObserveDataContext security: - bearerAuth: - observe:dataContext:read parameters: - name: sessionID in: query required: false description: Session ID (UUID format). Mutually exclusive with the other selectors. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,uuid - name: userID in: query required: false description: |- User ID (format `tus-`). Mutually exclusive with the other selectors. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=tus - name: flowID in: query required: false description: |- Flow ID (format `flw-`). Mutually exclusive with the other selectors. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=flw - name: sessionIDs in: query required: false description: Comma-separated session IDs (UUID format), max 500. Mutually exclusive with the other selectors. schema: type: string - name: flowIDs in: query required: false description: |- Comma-separated flow IDs (format `flw-`), max 500. Mutually exclusive with the other selectors. schema: type: string responses: "200": description: Subflow rows for the selected session, user, or flow. The exact shape may change between releases. content: application/json: schema: type: object additionalProperties: true default: $ref: "#/components/responses/error" /observe/dataContext/window: get: x-excluded: true summary: Time-windowed flow listing for agent reconnaissance description: |- Lists `ob_flow` rows within a short time window. The reconnaissance call for an agent that will follow up with `/session` and `/events` based on what it finds. Rides `idx_project_created (project_id, created)`. Filters are residual within the window; everything else (error-count threshold, duration range, path patterns, subflow touched, OS/browser, country, ...) the agent does client-side on the returned payload. **Window cap (server-enforced):** with no narrowing filter set the window must be ≤ 30 seconds; with at least one of `flowType / outcome / touchpoint / applicationID` set the cap is ≤ 60 seconds. Beyond that the call returns HTTP 422. **Serial use only.** Do not parallelize calls to `/observe/dataContext/*` from a single token. The response carries `meta.usage` reiterating this. The expected agent loop is: window → pick session_ids or flow_ids → /session and/or /events. Schema-loose. No compatibility contract. Required API key permission: `observe:dataContext:read`. operationId: ObserveDataContextWindowGet tags: - ObserveDataContext security: - bearerAuth: - observe:dataContext:read parameters: - name: fromDate in: query required: true description: Window start (naive datetime, interpreted in `timezone`). Format YYYY-MM-DDTHH:MM:SS. schema: type: string x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 - name: toDate in: query required: true description: Window end (naive datetime, interpreted in `timezone`). schema: type: string x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 - name: timezone in: query required: false description: IANA timezone name. Defaults to the project's configured timezone (`pr_project.timezone`); pass an explicit value to override. schema: type: string - name: flowType in: query required: false description: Comma-separated list of flow types (login,enrollment,signup,recovery). schema: type: string - name: outcome in: query required: false description: Comma-separated list of outcomes (complete,incomplete,skipped,invisible,visible-auto-skip). schema: type: string - name: touchpoint in: query required: false description: Comma-separated list of touchpoint values to match against ob_flow.touchpoint. schema: type: string - name: applicationID in: query required: false description: Comma-separated list of application IDs. schema: type: string - name: resetCount in: query required: false description: Comma-separated list of reset counts. schema: type: string - name: limit in: query required: false description: Max rows to return. Server clamps to 2000. Default 1000. schema: type: integer default: 1000 responses: "200": description: Flow rows in the window, wrapped in a stacked-tables envelope with `meta`. content: application/json: schema: type: object additionalProperties: true default: $ref: "#/components/responses/error" /observe/dataContext/session: get: x-excluded: true summary: Full session package (flows, subflows, tags) for one session description: |- Returns everything about one session except tracking events. Bundles flows (`ob_flow.idx_project_session`), per-flow tags (`ob_tag_flow.idx_project_session`), and every subflow table (`ob_*_sub_flow.project_id+flow_id`) into one stacked-tables envelope. Use `/observe/dataContext/events?sessionID=...` to fetch the heavy tracking-event payload separately. **Serial use only.** Schema-loose. Required API key permission: `observe:dataContext:read`. operationId: ObserveDataContextSessionGet tags: - ObserveDataContext security: - bearerAuth: - observe:dataContext:read parameters: - name: sessionID in: query required: true description: Session ID (UUID format) schema: type: string x-oapi-codegen-extra-tags: validate: required,uuid responses: "200": description: Session package wrapped in a stacked-tables envelope with `meta`. content: application/json: schema: type: object additionalProperties: true default: $ref: "#/components/responses/error" /observe/dataContext/events: get: x-excluded: true summary: Raw tracking events for one session or flow description: |- Returns ob_tracking_event rows for one session or one flow, including raw `data` and `metadata` JSON columns. Session lookups ride `ob_tracking_event.session_id`; flow lookups ride `ob_event_flow.idx_project_flow`. The timeline also embeds detected UI patterns (input clicks, autofill, overlays) in their natural chronological position. These are not SDK events — they are derived server-side from monitored browser behaviour — and are marked with `event_class=browser-behaviour` (SDK rows carry `event_class=sdk`) plus a per-row `pattern_description`. This is the heaviest of the three drill-in endpoints (events carry WebAuthn payloads); pull only the sessions you're actually going to inspect. **Serial use only.** Schema-loose. Required API key permission: `observe:dataContext:read`. operationId: ObserveDataContextEventsGet tags: - ObserveDataContext security: - bearerAuth: - observe:dataContext:read parameters: - name: sessionID in: query required: false description: Session ID (UUID format). Mutually exclusive with `flowID`. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,uuid - name: flowID in: query required: false description: |- Flow ID (format `flw-`). Mutually exclusive with `sessionID`. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=flw responses: "200": description: Event rows for the selected session or flow wrapped in a stacked-tables envelope. content: application/json: schema: type: object additionalProperties: true default: $ref: "#/components/responses/error" components: securitySchemes: bearerAuth: type: http scheme: bearer description: |- Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server. schemas: errorRspV2: type: object required: - error properties: error: type: object required: - message properties: message: description: Error message type: string example: 'Validation failed' details: description: Validation error details per field type: array items: type: object required: - field - message properties: field: description: Field name that failed validation type: string example: 'projectID' message: description: Validation error message type: string example: 'required' operationExecutionSearchReq: type: object required: - fromMs - toMs properties: fromMs: type: integer format: int64 description: Inclusive execution start timestamp; maximum query window is 31 days. x-oapi-codegen-extra-tags: validate: gt=0 toMs: type: integer format: int64 description: Exclusive execution start timestamp. x-oapi-codegen-extra-tags: validate: gt=0 operationName: type: string maxLength: 100 x-oapi-codegen-extra-tags: validate: omitempty,max=100 trigger: type: string enum: - cron - api - interactive - manual x-oapi-codegen-extra-tags: validate: omitempty,oneof=cron api interactive manual status: type: string enum: - running - succeeded - partial - failed - skipped x-oapi-codegen-extra-tags: validate: omitempty,oneof=running succeeded partial failed skipped actorUserID: type: string maxLength: 100 x-oapi-codegen-extra-tags: validate: omitempty,max=100 correlationID: type: string maxLength: 100 x-oapi-codegen-extra-tags: validate: omitempty,max=100 beforeID: type: string description: Exclusive ID cursor from the previous page, ordered by descending execution ID. Not supported with collapse. x-oapi-codegen-extra-tags: validate: omitempty,id=ope definitionID: type: string description: Time-series definition (tsd-) recorded in details; for precalculation and read executions. x-oapi-codegen-extra-tags: validate: omitempty,id=tsd interval: type: string enum: - hourly - daily - monthly - 1m - 5m description: Time-series interval recorded in details (1m and 5m only occur on live reads). x-oapi-codegen-extra-tags: validate: omitempty,oneof=hourly daily monthly 1m 5m jobType: type: string enum: - live - consistency - manual - experiment description: Precalculation job type recorded in details. x-oapi-codegen-extra-tags: validate: omitempty,oneof=live consistency manual experiment collapse: type: string enum: - bucket description: | bucket returns one execution per precalculated bucket (definitionID, interval, details.fromMs): the most recently started one, plus bucket* aggregates over all runs of that bucket. Requires operationName observe.timeseries.precalculate. fromMs/toMs then select buckets by their start (details.fromMs); runs that started up to 4 days after toMs are included so late consistency runs count. Ordered by definition, interval and bucket start. The status, trigger, actor and correlation filters are not supported with collapse. x-oapi-codegen-extra-tags: validate: omitempty,oneof=bucket limit: type: integer default: 50 description: Page size; at most 200, or 5000 with collapse. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=5000 orderBy: type: string enum: - id - runtime x-enum-varnames: - OperationExecutionSearchReqOrderByID - OperationExecutionSearchReqOrderByRuntime x-oapi-codegen-extra-tags: validate: omitempty,oneof=id runtime default: id description: | id pages by descending execution ID (default). runtime returns the slowest finished executions first (unfinished ones are excluded); it has no cursor (no beforeID, no nextBeforeID) and is not combinable with collapse. operationExecutionStatsReq: type: object required: - fromMs - toMs properties: fromMs: type: integer format: int64 description: Inclusive execution start timestamp; maximum query window is 31 days. x-oapi-codegen-extra-tags: validate: gt=0 toMs: type: integer format: int64 description: Exclusive execution start timestamp. x-oapi-codegen-extra-tags: validate: gt=0 operationName: type: string maxLength: 100 x-oapi-codegen-extra-tags: validate: omitempty,max=100 trigger: type: string enum: - cron - api - interactive - manual x-oapi-codegen-extra-tags: validate: omitempty,oneof=cron api interactive manual status: type: string enum: - running - succeeded - partial - failed - skipped x-oapi-codegen-extra-tags: validate: omitempty,oneof=running succeeded partial failed skipped actorUserID: type: string maxLength: 100 x-oapi-codegen-extra-tags: validate: omitempty,max=100 correlationID: type: string maxLength: 100 x-oapi-codegen-extra-tags: validate: omitempty,max=100 groupByDefinition: type: boolean description: Additionally group by the time-series definition recorded in details (definitionName). timeBucket: type: string enum: - hour - day description: Additionally group by execution start, truncated to UTC hours or days. x-oapi-codegen-extra-tags: validate: omitempty,oneof=hour day groupByMode: type: boolean description: Additionally group by the mode recorded in details (e.g. the search selector, the classification mode or the error impact baseline mode). runtimeBandsMs: type: array description: | Ascending runtime band limits in milliseconds (1-10 values, each at most 86400000). The response then carries runtimeBands with one count per band: [0, limit1), [limit1, limit2), ..., [lastLimit, ∞). Unfinished executions are not counted. maxItems: 10 items: type: integer format: int64 x-oapi-codegen-extra-tags: validate: omitempty,max=10,dive,gt=0,lte=86400000 operationExecution: type: object required: - id - projectID - operationName - trigger - startedAtMs - status - details properties: id: type: string projectID: type: string operationName: type: string trigger: type: string actorUserID: type: string correlationID: type: string startedAtMs: type: integer format: int64 completedAtMs: type: integer format: int64 runtimeMs: type: integer format: int64 description: Derived from completion minus start; absent for unfinished records. status: type: string enum: - running - succeeded - partial - failed - skipped resultCount: type: integer format: int64 description: Classification successfully recalculated ready sessions; precalculation committed parent aggregate rows; panel reads final series prepared. Never sum across different operation names. errorMessage: type: string description: Safe operational explanation; internal errors remain in server logs. details: $ref: "#/components/schemas/operationExecutionDetails" bucketRuns: type: integer format: int64 description: Collapse only. Number of executions of this bucket in the searched range. bucketRowsWrittenTotal: type: integer format: int64 description: Collapse only. Sum of rowsWritten over all runs of this bucket; divide by rowsWritten for write amplification. bucketRuntimeTotalMs: type: integer format: int64 description: Collapse only. Sum of runtimes over all finished runs of this bucket. bucketFinal: type: boolean description: Collapse only. The returned run started after the bucket ended, so its rowsWritten is the settled cardinality. operationExecutionDetails: type: object description: Typed optional fields selected by operationName. Missing timings mean unavailable, not zero. Parallel read phase timings overlap and must not be summed. properties: mode: type: string definitionID: type: string definitionName: type: string interval: type: string jobID: type: string jobType: type: string readMode: type: string description: Reads. aggregate, experiment, flow_ids, live (dynamic interval, every bucket computed live) or live_latest (open bucket computed live). responseFormat: type: string fromMs: type: integer format: int64 toMs: type: integer format: int64 sessionsRequested: type: integer format: int64 sessionsRecalculated: type: integer format: int64 sessionsSucceeded: type: integer format: int64 sessionsFailed: type: integer format: int64 sessionsAlreadyReady: type: integer format: int64 sessionsDeferred: type: integer format: int64 sessionsUnavailable: type: integer format: int64 description: Sessions skipped because their transaction group cannot be classified (a member has flows but no events any more). jobsCompleted: type: integer format: int64 jobsClosedUnavailable: type: integer format: int64 description: Jobs of unavailable groups finished as failed without classification (queue drain only), so they are not selected again. rowsWritten: type: integer format: int64 experimentRowsWritten: type: integer format: int64 rowsRead: type: integer format: int64 series: type: integer format: int64 shards: type: integer format: int64 groupBy: type: array items: type: string engagement: type: string errorID: type: string baselineMode: type: string snapshotStored: type: boolean analyzedFlowLimit: type: integer format: int64 affectedFlows: type: integer format: int64 baselineFlows: type: integer format: int64 occurrences: type: integer format: int64 orphanOccurrences: type: integer format: int64 affectedUsers: type: integer format: int64 repeatUsers: type: integer format: int64 flavourCount: type: integer format: int64 valueTotal: type: integer format: int64 description: Precalculation. Sum of the stored row values of the bucket (flows or events for count definitions). singletonRows: type: integer format: int64 description: Precalculation. Stored rows of the bucket whose value is 1. source: type: string enum: - panel - api_key description: How an API-triggered execution was authenticated. Absent for scheduled and runner executions. errorKind: type: string enum: - validation - not_found - busy - canceled - timeout - internal description: Reads, searches and classification runs. Failure category when status is failed; busy means no live read slot was free (429). liveBuckets: type: integer format: int64 description: Live reads. Number of buckets computed live. liveStepSeconds: type: integer format: int64 description: Live reads. Bucket width of a dynamic interval; absent for a single live bucket. liveRows: type: integer format: int64 description: Live reads. Rows returned by the live query. httpStatus: type: integer format: int64 description: Reads. HTTP status the request was answered with, when it failed. requestedBaselineMode: type: string description: Error impact. Baseline mode the request asked for; mode and baselineMode carry the effective one (matched can fall back to env-only). filters: type: array description: Searches. Names of the filters the request set (never their values). items: type: string inputSizes: type: object description: Searches. Number of values per list input the request carried (e.g. flowIDs, path). additionalProperties: type: integer format: int64 limit: type: integer format: int64 description: Searches. Result cap applied (limit, or page size for user search). saturated: type: boolean description: Searches. The result reached the cap, so more matches may exist. output: type: string description: Subflow search. full, flowIDs or aggregate. total: type: integer format: int64 description: Subflow search (filters). Uncapped number of matches. typesRequested: type: integer format: int64 description: Subflow search. Subflow types the request asked for. typesQueried: type: integer format: int64 description: Subflow search. Subflow types actually queried (types the filters do not apply to are skipped). slowestType: type: string description: Subflow search. The subflow type whose query took longest. slowestTypeMs: type: integer format: int64 includeDetails: type: boolean description: Subflow search. Entries were enriched with errors, tags and client environments. cells: type: integer format: int64 description: Subflow search (aggregate). Cells returned. truncated: type: boolean description: Subflow search (aggregate). The cell list hit its cap. cohortFlows: type: integer format: int64 description: Flow search. Flows the requested ID lists resolved to. cohortEmpty: type: boolean description: Flow search. The ID lists and the explicit flow IDs had no flow in common, so no query ran. customTagFilters: type: integer format: int64 description: Flow search. Active custom-tag filters (each adds joins). experiment: type: boolean description: Flow search. Scoped to an experiment (adds the exposure join). page: type: integer format: int64 description: User search. Requested page. patternLength: type: integer format: int64 description: User search. Length of the ID pattern (pattern modes only; the pattern itself is not recorded). timingsMs: type: object additionalProperties: type: integer format: int64 operationExecutionSearchRsp: type: object required: - executions properties: executions: type: array items: $ref: "#/components/schemas/operationExecution" nextBeforeID: type: string truncated: type: boolean description: With collapse, more buckets matched than the limit returned. operationExecutionStatsRsp: type: object required: - groups properties: groups: type: array items: $ref: "#/components/schemas/operationExecutionStats" operationExecutionStats: type: object description: Aggregated over the requested start-time window, grouped by operation, trigger and status (optionally also definition and time bucket). Duration buckets are nonoverlapping and exclude unfinished records. required: - operationName - trigger - status - executions - completed - resultCount - runtimeTotalMs - runtimeMaxMs - runtimeUnder100Ms - runtime100To1000Ms - runtime1000To10000Ms - runtime10000To60000Ms - runtimeAtLeast60000Ms properties: operationName: type: string trigger: type: string status: type: string executions: type: integer format: int64 completed: type: integer format: int64 resultCount: type: integer format: int64 runtimeTotalMs: type: integer format: int64 runtimeMaxMs: type: integer format: int64 runtimeUnder100Ms: type: integer format: int64 runtime100To1000Ms: type: integer format: int64 runtime1000To10000Ms: type: integer format: int64 runtime10000To60000Ms: type: integer format: int64 runtimeAtLeast60000Ms: type: integer format: int64 lastCompletedAtMs: type: integer format: int64 definitionName: type: string description: Present with groupByDefinition; empty for executions without a definition. mode: type: string description: Present with groupByMode; empty for executions without a recorded mode. runtimeBands: type: array description: Present with runtimeBandsMs. Finished executions per requested runtime band (one more entry than limits). items: type: integer format: int64 bucketStartMs: type: integer format: int64 description: Present with timeBucket. UTC start of the hour or day. rowsReadTotal: type: integer format: int64 description: Sum of details.rowsRead (time-series reads). seriesTotal: type: integer format: int64 description: Sum of details.series (time-series reads). rowsWrittenTotal: type: integer format: int64 description: Sum of details.rowsWritten (precalculation). operationQueueState: type: object required: - observedAtMs - classification - precalculation properties: observedAtMs: type: integer format: int64 classification: $ref: "#/components/schemas/operationQueueCounts" precalculation: $ref: "#/components/schemas/operationQueueCounts" operationQueueCounts: type: object required: - due - deferred - running - failed properties: due: type: integer format: int64 deferred: type: integer format: int64 running: type: integer format: int64 failed: type: integer format: int64 oldestDueAtMs: type: integer format: int64 oldestRunningAtMs: type: integer format: int64 ObserveFunnelHistoryMetricSeriesRequest: type: object additionalProperties: false required: - schemaVersion - name - fromDate - toDate - interval - metrics properties: schemaVersion: type: string enum: - funnel-metric-v1 name: type: string enum: - login-flow-v1 - signup-flow-v1 - recovery-flow-v1 - security-enrollment-flow-v1 fromDate: type: string description: Inclusive UTC-naive datetime, YYYY-MM-DDTHH:mm:ss; aligned to project bucket boundaries toDate: type: string description: Exclusive UTC-naive datetime; later than fromDate; maximum 366 days interval: type: string enum: - daily - hourly selection: allOf: - {$ref: '#/components/schemas/ObserveFunnelHistorySelection'} description: Required for single-position bucket history. Mutually exclusive with selections. Omission requires selections with output totals; no position discovery is supported. output: type: string enum: - buckets - totals default: buckets description: Single selection supports buckets only (the default). Plural selections requires totals, returning no buckets and accepting no comparison or breakdowns. Interval still selects the existing daily/hourly source data. selections: type: array minItems: 1 maxItems: 1000 description: Explicit node/edge prefixes to calculate together with output totals. Mutually exclusive with selection. Non-root positions are returned in nodes, including zero-volume positions. Root remains the top-level result. items: {$ref: '#/components/schemas/ObserveFunnelHistorySelection'} comparison: {$ref: '#/components/schemas/ObserveFunnelHistoryComparison'} filters: {$ref: '#/components/schemas/ObserveFunnelHistoryFilters'} breakdowns: type: array minItems: 1 maxItems: 16 description: Independent first-order groupings calculated together in one pass over stored aggregates. Each dimension occurs once. Omit a dimension's values to discover its observed groups in that same pass. The sum of explicit and discovered values across all dimensions multiplied by the number of buckets must not exceed 100000. The baseline is returned once at the top level. items: {$ref: '#/components/schemas/ObserveFunnelHistoryBreakdown'} metrics: type: array minItems: 1 maxItems: 19 items: type: string enum: - flowsReached - attemptsReached - occurrences - eventualCompletionRate - attemptCompletionRate - flowErrorRate - retriedFlowRate - eventualCompletionTime - subflowCompletionRate - completedHereRate - dropoffRate - retryHereRate - continueRate - completedHereTime - stepErrorRate - edgeShare - eventualSkipRate - eventualDropoffRate - skippedHereRate ObserveFunnelHistoryPeriod: type: object additionalProperties: false required: - fromDate - toDate properties: fromDate: type: string description: Inclusive UTC-naive datetime aligned to a project calendar-day boundary toDate: type: string description: Exclusive UTC-naive datetime aligned to a project calendar-day boundary ObserveFunnelHistoryComparison: type: object additionalProperties: false required: - baseline - current description: Optional daily comparison. Both periods must be nonempty, contained within the request range, and baseline must end no later than current starts. Unequal lengths are supported. Periods do not change the daily chart or full-range totals. properties: baseline: {$ref: '#/components/schemas/ObserveFunnelHistoryPeriod'} current: {$ref: '#/components/schemas/ObserveFunnelHistoryPeriod'} ObserveFunnelHistoryPeriodResult: type: object required: - fromDate - toDate - totals - summary - unparsedRows properties: fromDate: type: string toDate: type: string totals: {$ref: '#/components/schemas/ObserveFunnelHistoryCounts'} summary: type: object description: Metrics from merged period counts and duration histograms, never averages of daily percentages or medians. Null when this period has unparsed candidates; counts then cover decoded rows only. additionalProperties: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'} unparsedRows: type: integer format: int64 ObserveFunnelHistoryComparisonResult: type: object required: - baseline - current - differences properties: baseline: {$ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'} current: {$ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'} differences: type: object description: Current minus baseline per metric. Rate differences are percentage points, duration differences are seconds, count differences are absolute. Null when either period metric is unavailable. additionalProperties: type: - number - "null" format: double ObserveFunnelHistoryBreakdown: type: object additionalProperties: false required: - dimension description: Subsets of the already filtered population. The top-level baseline retains other and missing values. One scan calculates all requested groups. Box dimensions require a subflow target and return occurrence-based boxShare values; flow membership may overlap across retries. boxLeaf accepts one JSON-encoded selector with group and optional secondary field/value or authenticator exclusions, and returns focused occurrence metrics. properties: dimension: type: string enum: - os - browser - os-browser - device-browser - customTag1 - customTag2 - customTag3 - customTag4 - customTag5 - customTag6 - boxOutcome - boxProvider - boxAutofillType - boxFieldName - boxLeaf omitEmpty: type: boolean default: false description: Omit groups with no target or source observations across the whole range. Does not remove low-volume groups. minWeeklyObservations: type: integer minimum: 0 description: Optional daily-only traffic screen after merging. With comparison, applies to its two periods, scaled by period days / 7. Without comparison, checks the first and last seven days. Zero disables it. values: description: In a breakdowns request, omit values to discover and return every observed nonempty value while calculating the selected population. Explicit lists restrict the returned groups. boxLeaf requires explicit values. All discovered groups share the 100000 group-bucket budget; exceeding it returns an error, never silent truncation. type: array minItems: 1 maxItems: 1000 uniqueItems: true items: type: string maxLength: 512 minLength: 1 ObserveFunnelHistoryBreakdownResult: type: object required: - dimension - groups description: One independent grouping of the top-level filtered population. Shares the top-level baseline, dates, coverage and unavailable-metric semantics; dimensions are not nested. properties: dimension: type: string groups: type: array items: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricGroup'} ObserveFunnelHistoryMetricGroup: type: object required: - value - buckets - totals - summary properties: comparison: {$ref: '#/components/schemas/ObserveFunnelHistoryComparisonResult'} value: type: string totals: {$ref: '#/components/schemas/ObserveFunnelHistoryCounts'} summary: type: object additionalProperties: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'} buckets: type: array items: type: object properties: time: type: string format: date-time counts: {$ref: '#/components/schemas/ObserveFunnelHistoryCounts'} unparsedRows: type: integer format: int64 description: Nonzero makes every metric in this bucket unavailable unparsedWeight: type: number format: double description: Candidate flow weight that could not be interpreted values: type: object additionalProperties: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'} ObserveFunnelHistoryStep: type: object additionalProperties: false required: - kind description: >- Exactly one discriminator-specific field: decisionID, subflowType, flowType or terminalType. specType is exact structural identity, not a wildcard, and is supported only on split subflow types. Decision input/output values do not split the structural node. Predicates on choices are future work. properties: kind: type: string enum: - decision - subflow - flow - terminal decisionID: type: string pattern: '^dec-[0-9]+$' subflowType: type: string enum: - provideIdentifier - passwordLogin - passkeyLogin - passkeyEnrollment - socialLogin - emailLink - emailOtp - smsOtp - totp - appConfirmation - provideData - setPassword - passkeyDeletion - reset - systemCredential - trustedDeviceCheck - trustedDeviceEnrollment - keySigning - keyRegistration flowType: type: string description: Built-in or project-defined flow type from the project catalog specType: type: string terminalType: type: string enum: - decision-unresolved - decision-resolved description: Synthetic ending after a final decision; must be last in an exact prefix. ObserveFunnelHistorySelection: type: object additionalProperties: false required: - kind - scope - prefix properties: kind: type: string enum: - node - edge scope: type: string enum: - prefix - anywhere prefix: type: array maxItems: 32 description: >- Exact normalized attempt prefix including the target node (or edge source). Empty prefix selects the flow root. Anywhere requires exactly one step and counts a flow/attempt once even if it matches multiple positions. items: {$ref: '#/components/schemas/ObserveFunnelHistoryStep'} destination: allOf: - {$ref: '#/components/schemas/ObserveFunnelHistoryStep'} description: Required only for edges; immediate next structural step, not an eventual-reach condition or visually folded edge ObserveFunnelHistoryBrowserHierarchyFilter: type: object additionalProperties: false required: - mode - section - browser properties: mode: type: string enum: - os - device section: type: string maxLength: 512 minLength: 1 browser: type: string maxLength: 512 minLength: 1 description: Exact existing OS/browser or derived-device/browser cohort. Unknown labels use (unknown); device sections are desktop, mobile or other. ObserveFunnelHistoryFilters: type: object additionalProperties: false description: Values within a dimension are ORed; dimensions are ANDed. Omitted filters mean all. Null includes rows where a supported dimension is absent or empty. properties: browserHierarchy: {$ref: '#/components/schemas/ObserveFunnelHistoryBrowserHierarchyFilter'} applicationIDs: type: array x-go-type: '[]*string' maxItems: 100 description: |- Application IDs in `app-` format, scoped to the authenticated project. Time-series panels expose the numeric portion as dimensions.applicationId; clients must prefix those string values with app- when building this filter. Values are ORed and applied before aggregation to buckets, totals, comparisons, breakdowns and batched selections. Omitted or empty means all applications; valid IDs without matching project data return zero counts. Null includes rows without an application ID. items: type: - string - "null" example: ['app-12345678910'] osNames: type: array items: type: - string - "null" x-go-type: '[]*string' browserNames: type: array items: type: - string - "null" x-go-type: '[]*string' osVersions: type: array items: type: string touchpoints: type: array items: type: - string - "null" x-go-type: '[]*string' customTags: type: object x-go-type: 'map[string][]*string' description: Physical slots customTag1..6; slot names resolved via project configuration. Null includes absent or empty values. additionalProperties: type: array items: type: - string - "null" outcomes: type: array items: type: string enum: - complete - incomplete - skipped - invisible - visible-auto-skip engagement: type: string enum: - all - engaged - non-engaged attemptNumbers: type: array items: type: string enum: - '1' - '2' - '3' - '4+' ObserveFunnelHistoryCounts: type: object required: - flowsReached - attemptsReached - completedFlows - flowsWithErrors - sourceAttempts properties: flowsReached: type: number format: double description: Distinct weighted flows matching the target across selected attempts attemptsReached: type: number format: double description: Weighted selected attempts reaching the node or traversing the edge completedFlows: type: number format: double description: Matching flows with eventual complete outcome skippedFlows: type: number format: double description: Matching flows eventually skipped or hidden or auto-skipped droppedFlows: type: number format: double description: Matching flows with eventual incomplete outcome flowsWithErrors: type: number format: double description: Matching flows with at least one error anywhere in the flow sourceAttempts: type: number format: double description: "All selected attempts reaching the source, including those not taking the edge" completedAttempts: type: number format: double occurrences: type: number format: double subflowOccurrences: type: number format: double completedSubflowOccurrences: type: number format: double completedHere: type: number format: double droppedHere: type: number format: double retriedHere: type: number format: double continued: type: number format: double otherEndings: type: number format: double description: Final attempts ending skipped or hidden or auto-skipped at this position flowsWithRetries: type: number format: double repeatedFlows: type: number format: double embeddedErrorOccurrences: type: number format: double description: Observed references only; not a historically complete error count completionDurationBuckets: type: array minItems: 6 maxItems: 1000 items: type: number format: double description: le3s, le10s, le30s, le1m, le5m, g5m for eventual completed flows completedHereDurationBuckets: type: array minItems: 6 maxItems: 1000 items: type: number format: double description: Same bands for flows completed at this target ObserveFunnelHistoryRate: type: object required: - numerator - denominator - percent properties: numerator: type: number format: double denominator: type: number format: double percent: type: - number - "null" format: double description: Null when denominator is zero ObserveFunnelHistoryDurationSummary: type: object properties: histogram: type: object additionalProperties: type: number format: double observations: type: number format: double estimatedP50Seconds: type: - number - "null" format: double x-omitempty: false method: type: string description: >- Same six flow-duration bands as the funnel. Linear interpolation; the >5m band assumes 300–600 seconds. This is an estimate of end-to-end completion time, not elapsed time within the node. ObserveFunnelHistoryMetricValue: x-go-type: any oneOf: - type: number format: double - {$ref: '#/components/schemas/ObserveFunnelHistoryRate'} - {$ref: '#/components/schemas/ObserveFunnelHistoryDurationSummary'} - type: "null" ObserveFunnelHistoryMetricSeriesResponse: type: object required: - schemaVersion - projectID - name - timeZone - timeBasis - selection - buckets - totals - summary - coverage properties: nodes: type: array description: Present only for batched totals. Explicitly requested non-root node/edge positions in deterministic semantic-prefix order, each with empty buckets and no nested nodes. The top-level result is the root. Unparseable source rows conservatively invalidate all position metrics. No silent truncation. items: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricSeriesResponse'} comparison: {$ref: '#/components/schemas/ObserveFunnelHistoryComparisonResult'} schemaVersion: type: string projectID: type: string name: type: string timeZone: type: string timeBasis: type: string enum: - flow-start selection: {$ref: '#/components/schemas/ObserveFunnelHistorySelection'} totals: {$ref: '#/components/schemas/ObserveFunnelHistoryCounts'} summary: type: object description: Full-period metrics calculated from merged counts/histograms. All values are null when candidate paths could not be interpreted. Counts and totals then cover decoded records only. additionalProperties: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'} breakdowns: type: array maxItems: 16 description: Independent results for a breakdowns request, in request order. An empty groups array means no values passed the requested support screen. Omit breakdowns for baseline metrics only. items: {$ref: '#/components/schemas/ObserveFunnelHistoryBreakdownResult'} unavailableMetrics: type: object description: Reasons for unavailable or inapplicable metrics; corresponding values are null additionalProperties: type: string buckets: type: array items: type: object properties: time: type: string format: date-time counts: {$ref: '#/components/schemas/ObserveFunnelHistoryCounts'} unparsedRows: type: integer format: int64 description: Nonzero makes every metric in this bucket unavailable unparsedWeight: type: number format: double description: Candidate flow weight that could not be interpreted values: type: object additionalProperties: {$ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'} coverage: type: object properties: firstBucket: type: string format: date-time endExclusive: type: string format: date-time snapshotDate: type: string format: date completeWindow: type: boolean description: Bounds lie within recorded coverage; not a completeness guarantee for every interior bucket notes: type: array items: type: string diagnostics: type: object description: Calculation timings and processed-cell counts. Shard timings overlap and must not be added as end-to-end latency. required: - rowsScanned - rowsMatched - rowsUnparsed properties: rowsScanned: type: integer format: int64 description: Aggregated cells delivered by SQL after all WHERE predicates rowsMatched: type: integer format: int64 description: Cells whose decoded path contributed to the selection rowsUnparsed: type: integer format: int64 description: Aggregated cells that could not be decoded after a bounded dictionary refresh. Affected bucket metrics and whole-period summaries are unavailable; counts and totals describe decoded records only. weightUnparsed: type: number format: double description: Sum of undecodable candidate row weights, not a count of confirmed matches at this position. additionalProperties: true observeExperimentRunGroup: type: object required: - label - role - variantIDs properties: label: type: string description: Display name of the arm (e.g. "Control", "New colors") x-oapi-codegen-extra-tags: validate: required,min=1,max=100 role: type: string description: Role of the arm in the A/B evaluation enum: - control - treatment x-oapi-codegen-extra-tags: validate: required,oneof=control treatment variantIDs: type: array description: |- Variant IDs assigned to this arm (format `exv-`) items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,dive,id=exv expectedSharePct: description: Optional intended exposure share for this arm in percent (0..100); enables the sample-ratio-mismatch check type: number format: double observeDataPolicy: type: object required: - id - code - name - trackingRetentionDays - flowUserLinkRetentionDays - flowRetentionDays - createdMs - updatedMs properties: id: type: string description: |- ID of the data policy (format `dpo-`). code: type: integer format: int32 description: Project-scoped selector (0..255) the SDK reports in `meta.dataPolicy`. 0 is the default policy. Immutable. name: type: string description: Human-readable label (panel only, never transmitted by the SDK). trackingRetentionDays: type: integer format: int32 description: Delete a session's raw tracking data (events, batches, tags, user references, device info, lows, telemetry) this many days after capture. 0 = no expiry. flowUserLinkRetentionDays: type: integer format: int32 description: Remove person-identifying links from flows/subflows this many days after capture, keeping the flows. 0 = no expiry. flowRetentionDays: type: integer format: int32 description: Delete flows and dependent derived records this many days after capture. 0 = no expiry. createdMs: type: integer format: int64 updatedMs: type: integer format: int64 observeDataPolicyCreateReq: type: object required: - code - name - trackingRetentionDays - flowUserLinkRetentionDays - flowRetentionDays properties: code: type: integer format: int32 description: Project-scoped selector (0..255), unique per project and immutable once created. 0 is the default policy. x-oapi-codegen-extra-tags: validate: min=0,max=255 name: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=255 trackingRetentionDays: type: integer format: int32 description: Days after capture; 0 = no expiry. x-oapi-codegen-extra-tags: validate: min=0,max=36500 flowUserLinkRetentionDays: type: integer format: int32 description: Days after capture; 0 = no expiry. x-oapi-codegen-extra-tags: validate: min=0,max=36500 flowRetentionDays: type: integer format: int32 description: Days after capture; 0 = no expiry. x-oapi-codegen-extra-tags: validate: min=0,max=36500 observeDataPolicyUpdateReq: type: object required: - name - trackingRetentionDays - flowUserLinkRetentionDays - flowRetentionDays properties: name: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=255 trackingRetentionDays: type: integer format: int32 description: Days after capture; 0 = no expiry. x-oapi-codegen-extra-tags: validate: min=0,max=36500 flowUserLinkRetentionDays: type: integer format: int32 description: Days after capture; 0 = no expiry. x-oapi-codegen-extra-tags: validate: min=0,max=36500 flowRetentionDays: type: integer format: int32 description: Days after capture; 0 = no expiry. x-oapi-codegen-extra-tags: validate: min=0,max=36500 observeExperimentRunCreateReq: type: object required: - experimentID - name - startMs - variantIDs - timeSeriesDefinitionIDs properties: experimentID: type: string description: |- ID of the experiment (format `exp-`) x-oapi-codegen-extra-tags: validate: required,id=exp name: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string startMs: description: Start of the run in milliseconds since epoch type: integer format: int64 endMs: description: Optional end of the run in milliseconds since epoch (open-ended if omitted) type: integer format: int64 variantIDs: type: array description: |- Selected variant IDs (format `exv-`) items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,dive,id=exv timeSeriesDefinitionIDs: type: array description: |- Time-series definition IDs to break down for this run (format `tsd-`) items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,dive,id=tsd groups: type: array description: Optional A/B evaluation arms (control vs treatment) over the selected variants. Omit for a breakdown-only run. items: $ref: "#/components/schemas/observeExperimentRunGroup" observeExperimentRunUpdateReq: type: object required: - name - startMs - variantIDs - timeSeriesDefinitionIDs properties: name: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string startMs: type: integer format: int64 endMs: type: integer format: int64 variantIDs: type: array items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,dive,id=exv timeSeriesDefinitionIDs: type: array items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,dive,id=tsd groups: type: array description: Optional A/B evaluation arms (control vs treatment) over the selected variants. Omit for a breakdown-only run. items: $ref: "#/components/schemas/observeExperimentRunGroup" observeLabelCreateReq: type: object required: - entityType - entityID properties: entityType: type: string description: Type of the entity to label x-oapi-codegen-extra-tags: validate: required,min=1,max=50 entityID: type: string description: |- ID of the entity to label. Use `app-` for applications, `dec-` for decisions and decision options, and `dva-` for decision variants. x-oapi-codegen-extra-tags: validate: required,min=5,max=50 option: type: string description: | Sub-key within the labeled entity. Required for entityType='decisionOption', must be empty (or omitted) for all other entity types. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=100 displayName: type: string description: Human-readable display name x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 description: type: string description: Description of the entity x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=5000 observeLabelUpdateReq: type: object properties: displayName: type: string description: Human-readable display name x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 description: type: string description: Description of the entity x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=5000 observeErrorFlavour: type: object required: - id - subFlowType - stepName - name - message - code - uiPatterns - specType - trigger - durationBucket - firstSeenMs properties: id: type: string description: |- Error flavour ID (format `erf-`). subFlowType: type: string description: Subflow type the flavour belongs to (e.g. passkey-login). stepName: type: string description: Step the error occurred on ("" for subflow-level errors). name: type: string description: Raw error name from the tracking event (e.g. NotAllowedError; "" for code-only and step-incomplete flavours). message: type: string description: Raw error message from the tracking event ("" for code-only and step-incomplete flavours). code: type: string description: Raw error code from the tracking event ("" when the error carried name/message instead). uiPatterns: type: string description: Canonical comma-joined set of UI patterns observed during the error ("" for none). specType: type: string description: Resolved subflow spec type the error occurred under ("" when the subflow has none). trigger: type: string enum: - step-error - step-incomplete - step-missing - no-followup description: What produced the flavour - an explicit error event, a must-complete step that ended neither finished nor errored, a step the subflow had to reach that never appeared at all, or a subflow with interaction evidence but no step or error event at all. durationBucket: type: string enum: - "0" - le100 - le2000 - le30000 - gt30000 - na description: Bucketed step-start to error latency (na when not measurable). errorID: type: string description: |- ID of the error this flavour is mapped to (format `err-`); absent while unmapped. assignSource: type: string enum: - manual - kb - agent description: Who made the current error assignment - a human in the Management Console (manual), a deterministic knowledge-base rule (kb), or AI/agent judgment (agent). Absent while unmapped and on assignments made before provenance existed. assignReason: type: string description: Human-readable explanation of why this flavour belongs to its error. Absent under the same conditions as assignSource. firstSeenMs: type: integer format: int64 description: Timestamp of the occurrence that minted this flavour, in milliseconds since epoch. observeErrorFlavourAssignReq: type: object required: - flavourIDs properties: flavourIDs: type: array minItems: 1 maxItems: 1000 items: type: string x-oapi-codegen-extra-tags: validate: required,id=erf description: |- Flavour IDs to (un)assign (format `erf-`). x-oapi-codegen-extra-tags: validate: required,min=1,max=1000,dive errorID: type: string description: |- Error to assign the flavours to (format `err-`). Omit to unassign the flavours. x-oapi-codegen-extra-tags: validate: omitempty,id=err assignSource: type: string enum: - manual - kb - agent description: Provenance of this assignment (defaults to manual). Only allowed together with errorID; unassigning always clears the stored provenance. x-oapi-codegen-extra-tags: validate: excluded_without=ErrorID,omitempty,oneof=manual kb agent assignReason: type: string description: Human-readable explanation of why these flavours belong to the error; stored per flavour and overwritten on remap. Only allowed together with errorID. x-oapi-codegen-extra-tags: validate: excluded_without=ErrorID,omitempty,min=1,max=500 observeErrorFlavourAssignRsp: type: object required: - assignedCount properties: assignedCount: type: integer format: int64 description: Number of flavours whose assignment was changed. observeErrorFlavourImpactReq: type: object required: - flavourIDs - fromDate - toDate properties: flavourIDs: type: array minItems: 1 maxItems: 1000 items: type: string x-oapi-codegen-extra-tags: validate: required,id=erf description: |- Flavour IDs to analyze together (format `erf-`), e.g. an error's member flavours. x-oapi-codegen-extra-tags: validate: required,min=1,max=1000,dive fromDate: type: string description: Range start, naive UTC datetime (inclusive). example: "2026-08-01T00:00:00" x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 toDate: type: string description: Range end, naive UTC datetime (exclusive). example: "2026-08-08T00:00:00" x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 flowLimit: type: integer minimum: 1 maximum: 50000 description: >- Maximum number of flows to analyze PER GROUP (affected and baseline). Both groups are read as raw flow rows, so this is what bounds the analysis; a group that hits the limit is marked `sampled` and describes the most recent `flowLimit` flows of that group. Defaults to 5000. High values buy completeness (fewer sampled groups, so per-user tallies see a user's whole history in range) at the cost of a slower analysis. example: 5000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=50000 baselineFlowListID: type: string description: |- Optional stored ID list (format `idl-`, from POST /observe/idLists or a previous analysis) to use verbatim as the baseline group instead of building one. The listed flows are read as raw rows (capped at `flowLimit`, most recent first) and compared against the affected group with the usual device-mix standardization; `matching` is ignored when this is set. x-oapi-codegen-extra-tags: validate: omitempty,id=idl matching: $ref: "#/components/schemas/observeErrorImpactMatching" errorID: type: string description: |- The curated error whose impact is being analyzed (format `err-`). When set, the flavourIDs must be exactly the error's current member flavours, and the analysis result is stored on the error as its last-known impact (served as `lastImpact` in the errors list). Omit for ad-hoc flavour analyses, which are never stored. x-oapi-codegen-extra-tags: validate: omitempty,id=err observeErrorImpactMatching: type: object description: >- Baseline modeling configuration. When present, the baseline is not "all engaged flows of the affected flow types" but a stratified sample matched to the affected group on the requested dimensions — controlling for WHERE in the flow the error happened (pathPrefix) and for the population mix, so the completion comparison isolates the error instead of the route that leads to it. The response's `matchingReport` describes the strata, the achieved balance, and every fallback taken. properties: dimensions: type: array description: >- Dimensions to match the baseline on. `pathPrefix` is the flow's coarse route up to (and including the code of) the erroring subflow, derived from long_path — it requires the project to have error-flavour embedding enabled (observeClassificationConfig); without embedded data the analysis degrades to the remaining dimensions and reports `prefixesUnavailable`. Defaults to [pathPrefix, osName, browserName]. items: type: string enum: - pathPrefix - osName - browserName - touchpoint - applicationID x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=5,dive,oneof=pathPrefix osName browserName touchpoint applicationID prefixMode: type: string enum: - code - raw description: >- Prefix coarsening. `code` (default) reduces every segment to its kind and code (s_pr-id|d_1|s_pk-lo), so routes match regardless of variant detail; `raw` matches the exact long_path prefix including variant aliases — far more strata, only useful on very high-volume flows. x-oapi-codegen-extra-tags: validate: omitempty,oneof=code raw ratio: type: integer minimum: 1 maximum: 10 description: Baseline sample size per stratum as a multiple of the stratum's affected flows. Defaults to 3. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10 coverage: type: number minimum: 0.5 maximum: 1 description: >- Share of affected flows the kept top prefixes must cover; the long tail of rarer prefixes is matched without the prefix dimension and reported as `uncoveredPrefixShare`. Defaults to 0.9. x-oapi-codegen-extra-tags: validate: omitempty,min=0.5,max=1 minCellSize: type: integer minimum: 1 maximum: 1000 description: >- Minimum baseline candidates a stratum needs before it falls back to a coarser match (prefix dropped first, then the extra dimensions, down to env-only). Defaults to 20. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=1000 observeErrorFlavourImpactRsp: type: object required: - affected - occurrenceCount - orphanOccurrenceCount properties: affected: $ref: "#/components/schemas/observeErrorImpactFlowGroup" baseline: $ref: "#/components/schemas/observeErrorImpactFlowGroup" completionLift: type: number format: double description: affected.completionRate minus baseline.completionRate (percentage points as a fraction, negative = affected flows complete less). Absent when either side has no completion rate. occurrenceCount: type: integer format: int64 description: Occurrences of the given flavours on real-user flows in range. orphanOccurrenceCount: type: integer format: int64 description: Occurrences in range without an attached flow (inferred / never attached); excluded from all rates. occurrencesPerFlowAvg: type: number format: double description: Average occurrences per affected flow (occurrenceCount / affected.flowCount). Absent when no flows are affected. affectedUserCount: type: integer format: int64 description: Distinct users among affected flows (flows without a user reference contribute none). Absent when no flows are affected. repeatUserCount: type: integer format: int64 description: >- Distinct users who hit the analyzed flavours MORE THAN ONCE in range, i.e. at least two occurrences — whether spread over several flows or fired twice within one flow. Subset of `affectedUserCount`; flows without a user reference contribute none. Absent when no flows are affected. Computed over the analyzed flows, so on a `sampled` affected group it is a lower bound (a user's earlier flows may fall outside the sample). repeatUserOccurrenceCount: type: integer format: int64 description: Occurrences on the repeat users' flows — how much of `occurrenceCount` is concentrated on users who keep hitting this. repeatUserFlowCount: type: integer format: int64 description: Affected flows belonging to the repeat users, i.e. the size of the cohort behind `repeatUserFlowListID`. repeatUserFlowListID: type: string description: |- Handle of a stored ID list (format `idl-`) holding the affected flows of the repeat users, for opening exactly those high-impact users in user search. Empty when no user hit the flavours more than once. userExposure: type: array items: $ref: "#/components/schemas/observeErrorImpactUserBucket" description: >- The distribution behind `repeatUserCount`: the affected users grouped into occurrence bands (1, 2, 3-4, 5-9, 10+), ascending, empty bands omitted. Every band above the first is made of repeat users, so their user counts sum to `repeatUserCount` and all bands together to `affectedUserCount`. Same sampling caveat as `repeatUserCount` — on a `sampled` affected group users shift toward the lower bands. unattributedFlows: $ref: "#/components/schemas/observeErrorImpactUnattributedFlows" terminalIncompleteFlowCount: type: integer format: int64 description: Incomplete affected flows whose last occurrence of the analyzed flavours fell within 10 seconds of the flow's end - the error was (close to) the last thing that happened. Absent when no flows are affected. analyzedFlowLimit: type: integer format: int64 description: The per-group flow cap the analysis ran with (the request's `flowLimit`, or the default). Together with each group's `sampled` flag it tells a caller whether raising the limit would change the numbers. matchingReport: $ref: "#/components/schemas/observeErrorImpactMatchingReport" perFlowType: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeErrorImpactFlowTypeImpact" description: >- The completion comparison split per flow type of the affected group, biggest affected slice first. The group-level `completionLift` is a weighted mean over these; when the per-type lifts diverge (different sign, or a large spread), the blended number hides differently-hurt flow types and a caller should present this cut instead. Empty when no flows are affected. subflowCompletion: $ref: "#/components/schemas/observeErrorImpactSubflowCompletion" observeErrorImpactFlowTypeImpact: type: object description: >- One flow type's slice of the impact comparison: the affected flows of this type against the baseline flows of the SAME type (flow type is a hard block variable of the baseline — see `matchingReport.strata[].flowType`), with the baseline rate standardized to this type's own affected OS/browser mix. required: - flowType - affectedFlowCount - affectedAttemptCount - baselineFlowCount - baselineAttemptCount properties: flowType: type: string description: Flow type name (`login`, `signup`, ...); empty for flows that carry no type. affectedFlowCount: type: integer format: int64 description: Affected flows of this type. affectedAttemptCount: type: integer format: int64 description: Affected flows of this type that completed or were abandoned — the denominator of `affectedCompletionRate`, and what says whether the row rests on anything. affectedCompletionRate: type: number format: double description: Completion rate of the affected flows of this type. Absent when none has an attempts outcome. affectedCompletedDurationP50Ms: type: integer format: int64 description: Median duration of COMPLETED affected flows of this type, in milliseconds. Absent when none completed. affectedCompletedFlowsMeasured: type: integer format: int64 description: How many completed affected flows that median rests on. baselineFlowCount: type: integer format: int64 description: Baseline flows of this type. baselineAttemptCount: type: integer format: int64 description: Baseline flows of this type with an attempts outcome. baselineCompletionRate: type: number format: double description: Baseline completion rate within this type, standardized to the type's affected OS/browser mix. Absent when no env cell is comparable. baselineCompletedDurationP50Ms: type: integer format: int64 description: Median duration of completed baseline flows of this type, in milliseconds. baselineCompletedFlowsMeasured: type: integer format: int64 description: How many completed baseline flows that median rests on. completionLift: type: number format: double description: affectedCompletionRate minus baselineCompletionRate within this type. Absent when either side has no rate. observeErrorImpactSubflowCompletion: type: object description: >- How the ERRORING SUBFLOW itself ended on both sides — did this step succeed, as opposed to `completionLift`'s did the whole flow succeed (possibly via a fallback). The affected side measures the segment the analyzed flavours fired on (falling back to the flow's first segment of the subflow's code when embedding does not locate it); the baseline side the first segment of the same code, so flows that never attempted the subflow are excluded. Flow-type-agnostic by construction: a passkey-login attempt is the same unit in a login and in a signup flow, so this comparison stays clean when the affected group mixes flow types. Absent when the analyzed flavours span several subflow types or none resolves to a known code. required: - subflowCode - definitional - affectedMeasuredCount - affectedCompleteCount - baselineMeasuredCount - baselineCompleteCount properties: subflowCode: type: string description: Long-path code of the subflow the analyzed flavours belong to (e.g. `pk-lo`). definitional: type: boolean description: >- True when the analyzed flavours are embedded ONLY in non-completing outcome variants — the comparison is then circular (the error's presence defines the segment as failed) and must not be presented as a measured impact. affectedMeasuredCount: type: integer format: int64 description: Affected flows with a classifiable segment of the subflow; the denominator of `affectedCompletionRate`. affectedCompleteCount: type: integer format: int64 affectedCompletionRate: type: number format: double description: Share of the affected side's measured subflow attempts that completed. Absent when nothing was measured. baselineMeasuredCount: type: integer format: int64 description: Baseline flows with a classifiable segment of the subflow. baselineCompleteCount: type: integer format: int64 baselineCompletionRate: type: number format: double description: Share of the baseline side's measured subflow attempts that completed. completionLift: type: number format: double description: affectedCompletionRate minus baselineCompletionRate. Absent when either side measured nothing. observeErrorImpactMatchingReport: type: object description: >- How the baseline group was modeled and how well it mirrors the affected group. Present when the request asked for `matching` or supplied `baselineFlowListID`; absent on a plain (unmatched) analysis. required: - mode - dimensions - prefixesUnavailable - matchRate - uncoveredPrefixShare - collapsedStrataCount properties: mode: type: string enum: - matched - env-only - provided-list description: >- `matched` = stratified matching ran as requested; `env-only` = the pathPrefix dimension was requested but no affected flow carried embedded error flavours in its long_path, so matching fell back to the remaining dimensions; `provided-list` = the caller supplied `baselineFlowListID` and no modeling ran. dimensions: type: array items: type: string description: The dimensions matching actually ran on (after any degradation). prefixesUnavailable: type: boolean description: >- True when pathPrefix was requested but could not be derived for any affected flow (the project has no embedded error flavours in long_path for the analyzed range). matchRate: type: number format: double description: Share of affected flows whose stratum found at least one baseline candidate (at any collapse level). uncoveredPrefixShare: type: number format: double description: Share of affected flows whose prefix fell outside the kept top prefixes (see the request's `coverage`); they are matched without the prefix dimension. collapsedStrataCount: type: integer description: Number of strata that fell back to a coarser match because they had fewer than `minCellSize` baseline candidates. strata: type: array items: $ref: "#/components/schemas/observeErrorImpactMatchingStratum" description: The largest strata by affected flows (capped at 50), for inspecting what the baseline was matched on. balance: type: array items: $ref: "#/components/schemas/observeErrorImpactBalanceCell" description: >- Per-dimension balance between the affected group and the baseline: total-variation distance (0 = identical distributions, 1 = disjoint) before matching (against all candidates) and after (against the sampled baseline). After-values near 0 mean the baseline mirrors the affected group on that dimension. observeErrorImpactMatchingStratum: type: object required: - affectedFlowCount - baselineFlowCount - collapseLevel properties: flowType: type: string description: >- The stratum's flow type. Flow type is a hard block variable — part of every stratum key at every collapse level, never dropped — so baseline flows of one flow type never serve affected flows of another. Empty for flows carrying no type. pathPrefix: type: string description: Coarse route before the erroring subflow (segment codes joined by |). Empty = the error sat on the first segment, or the prefix dimension was not part of this stratum. errorSubflow: type: string description: Subflow code the error sits on (e.g. pk-lo). Empty when the position could not be derived. osName: type: string browserName: type: string touchpoint: type: string applicationID: type: string affectedFlowCount: type: integer format: int64 baselineFlowCount: type: integer format: int64 description: Baseline flows sampled for this stratum (target is `ratio` x affectedFlowCount; less when candidates ran out). collapseLevel: type: integer description: 0 = matched on the full requested key; 1 = prefix dropped; 2 = extra dimensions dropped (env + position only); 3 = position only. observeErrorImpactBalanceCell: type: object required: - dimension - imbalanceBefore - imbalanceAfter properties: dimension: type: string imbalanceBefore: type: number format: double imbalanceAfter: type: number format: double observeErrorImpactFlowGroup: type: object required: - flowCount - completeCount - incompleteCount - otherCount properties: flowCount: type: integer format: int64 description: Distinct flows in the group. completeCount: type: integer format: int64 description: Flows with outcome `complete`. incompleteCount: type: integer format: int64 description: Flows with outcome `incomplete`. otherCount: type: integer format: int64 description: Flows with any other outcome (`skipped`, `invisible`, `visible-auto-skip`); excluded from completion rates. completionRate: type: number format: double description: completeCount / (completeCount + incompleteCount). For the baseline group this is standardized to the affected group's (osName, browserName) mix. Absent when no attempts-outcome flows exist. rawCompletionRate: type: number format: double description: Baseline only — unweighted completion rate of the whole population, for transparency next to the mix-weighted completionRate. envMix: type: array maxItems: 1000 description: Per-(osName, browserName) cells of the group. Empty dimension values mean unknown. items: $ref: "#/components/schemas/observeErrorImpactEnvCell" flowTypes: type: array maxItems: 1000 description: >- Which flow types the group's analyzed flows belong to, biggest first. On the affected group this is also what the baseline was drawn from. A funnel diagram renders exactly one flow type, so a caller offering to open these flows in the funnel needs this list to know which funnel(s) apply. items: $ref: "#/components/schemas/observeErrorImpactFlowTypeCell" sampled: type: boolean description: >- True when the group hit `flowLimit`, i.e. every number describing it was computed over the most recent `flowLimit` flows of the group rather than its whole population. completedDurationP25Ms: type: integer format: int64 description: 25th percentile flow duration in milliseconds, over COMPLETED flows only (an incomplete flow's duration is time-until-abandonment, a different quantity). Absent when the group has no completed flows. completedDurationP50Ms: type: integer format: int64 description: Median flow duration in milliseconds, over completed flows only. completedDurationP90Ms: type: integer format: int64 description: 90th percentile flow duration in milliseconds, over completed flows only. completedFlowsMeasured: type: integer format: int64 description: How many completed flows the duration percentiles rest on. flowListID: type: string description: |- Handle of a stored ID list (format `idl-`) holding exactly the analyzed flows of this group, for opening them in user search. Empty when the group is empty. observeErrorImpactUserBucket: type: object required: - minOccurrences - userCount - flowCount - occurrenceCount properties: minOccurrences: type: integer format: int64 description: Lowest occurrence count in this band (inclusive). maxOccurrences: type: integer format: int64 description: Highest occurrence count in this band (inclusive). Absent on the open-ended top band. userCount: type: integer format: int64 description: Distinct users whose occurrence count falls into this band. flowCount: type: integer format: int64 description: Affected flows belonging to those users - the size of the cohort behind `flowListID`. occurrenceCount: type: integer format: int64 description: Occurrences on this band's flows, i.e. how much of `occurrenceCount` sits on these users. attemptCount: type: integer format: int64 description: This band's flows that completed or were abandoned - the denominator of `completionRate`. completionRate: type: number format: double description: >- Share of this band's attempts that completed. Read against the affected group's own rate it says whether being hit repeatedly goes with giving up. Absent when the band has no attempts-outcome flows. flowListID: type: string description: |- Handle of a stored ID list (format `idl-`) holding this band's flows, for opening exactly these users in user search. Empty when the list could not be stored. observeErrorImpactUnattributedFlows: type: object required: - flowCount - occurrenceCount properties: flowCount: type: integer format: int64 description: Affected flows without a user reference. occurrenceCount: type: integer format: int64 description: Occurrences on those flows. attemptCount: type: integer format: int64 description: Those flows that completed or were abandoned - the denominator of `completionRate`. completionRate: type: number format: double description: Share of those attempts that completed. Absent when none has an attempts outcome. flowListID: type: string description: |- Handle of a stored ID list (format `idl-`) holding these flows, for opening them in user search. Empty when the list could not be stored. observeErrorImpactFlowTypeCell: type: object required: - flowType - flowCount properties: flowType: type: string description: Flow type name (`login`, `enrollment`, `recovery`, `signup` or a project's custom type); empty when the flow carries none. flowCount: type: integer format: int64 description: Analyzed flows of this type in the group. observeErrorImpactEnvCell: type: object required: - osName - browserName - flowCount properties: completedDurationP50Ms: type: integer format: int64 description: Median flow duration in milliseconds within this environment, over completed flows only. Absent when the cell has no completed flows. completedFlowsMeasured: type: integer format: int64 description: How many completed flows this cell's median rests on. osName: type: string description: OS name; empty when unknown. browserName: type: string description: Browser (web) or app name (app); empty when unknown. flowCount: type: integer format: int64 description: Distinct flows in this cell. completionRate: type: number format: double description: Completion rate within this cell. Absent when the cell has no attempts-outcome flows. observeError: type: object required: - id - name - type - severity - createdMs - updatedMs properties: id: type: string description: |- Error ID (format `err-`). name: type: string description: Human-readable error name. description: type: string description: Optional longer description of the error. subFlowType: type: string description: Auto-managed subflow scope — stamped from the first assigned flavours, enforced on every later assignment (an error never mixes subflow types), cleared when the last member is unassigned. Never user input. Absent while the error has no members. type: type: string enum: - general - project-specific description: Whether the error is a general (cross-deployment) or project-specific one. severity: type: string enum: - error - warn - info description: User-declared triage severity of an occurrence of this error. createdMs: type: integer format: int64 description: Creation time in milliseconds since epoch. updatedMs: type: integer format: int64 description: Last update time in milliseconds since epoch. recommendation: $ref: "#/components/schemas/observeErrorRecommendation" lastImpact: $ref: "#/components/schemas/observeErrorImpactSnapshot" observeErrorImpactSnapshot: type: object description: > Result of the most recent impact analysis run for this error: the completion-rate and completed-duration comparison against the baseline, plus when it ran and over which range. Stored when the impact endpoint is called with the error's ID; absent while no analysis ran (or the error lost its last member flavour since). Numbers describe the member set at analysis time — `analyzedAtMs` says how current they are. required: - analyzedAtMs - fromDate - toDate - baselineMode - affectedFlowCount properties: analyzedAtMs: type: integer format: int64 description: When the analysis ran, in milliseconds since epoch. fromDate: type: string description: Analyzed range start, naive UTC datetime (inclusive) — as the analysis request carried it. toDate: type: string description: Analyzed range end, naive UTC datetime (exclusive). baselineMode: type: string description: How the baseline was built — `population` (plain comparable-engaged population) or a matching-report mode (`matched`, `env-only`, `provided-list`). affectedFlowCount: type: integer format: int64 description: Distinct affected flows the analysis rested on. baselineFlowCount: type: integer format: int64 description: Distinct baseline flows; absent when no comparable flows existed. affectedCompletionRate: type: number format: double description: Completion rate of the affected flows. Absent when none had an attempts outcome. baselineCompletionRate: type: number format: double description: Completion rate of the baseline, standardized to the affected group's device mix. Absent when the baseline had no attempts-outcome flows. completionLift: type: number format: double description: affectedCompletionRate minus baselineCompletionRate — the completion-rate impact (negative means flows hit by this error complete less). Absent when either side has no rate. affectedCompletedDurationP50Ms: type: integer format: int64 description: Median duration of COMPLETED affected flows in milliseconds. Absent when none completed. baselineCompletedDurationP50Ms: type: integer format: int64 description: Median duration of completed baseline flows in milliseconds. Absent when none completed. perFlowType: type: array maxItems: 1000 items: $ref: "#/components/schemas/observeErrorImpactSnapshotFlowType" description: >- Per-flow-type completion comparison of that analysis, biggest affected slice first — enough to mark a blended lift that hides differently-hurt flow types. Absent on snapshots stored before the breakdown existed. subflowCode: type: string description: Long-path code of the erroring subflow the subflow-completion fields below describe. Absent when the analysis produced no subflow comparison. subflowCompletionDefinitional: type: boolean description: True when the subflow comparison was definitional (the flavours only occur on failed attempts) — render no subflow impact from this snapshot. affectedSubflowCompletionRate: type: number format: double description: Share of the affected side's measured attempts at the erroring subflow that completed. baselineSubflowCompletionRate: type: number format: double description: Share of the baseline side's measured attempts at the erroring subflow that completed. subflowCompletionLift: type: number format: double description: affectedSubflowCompletionRate minus baselineSubflowCompletionRate — the subflow-completion impact. Absent when either side measured nothing. observeErrorImpactSnapshotFlowType: type: object description: One flow type's slice of a stored impact snapshot. required: - flowType - affectedFlowCount - attemptCount properties: flowType: type: string description: Flow type name; empty for flows carrying no type. affectedFlowCount: type: integer format: int64 description: Affected flows of this type in that analysis. attemptCount: type: integer format: int64 description: Affected flows of this type with an attempts outcome — what the type's lift rests on. completionLift: type: number format: double description: The type's completion lift (affected minus type-standardized baseline). Absent when either side had no rate. observeErrorRecommendation: type: object description: > Curated guidance attached to an error (at most one per error): what the error is and how to reproduce it, the recommended handling (ignore / observe / fix), and — for fix — the fix in detail. Human-created like the error itself; classification never writes it. Free-text fields are markdown. required: - id - action - summary - source - createdMs - updatedMs properties: id: type: string description: |- Recommendation ID (format `erc-`). action: type: string enum: - ignore - observe - fix description: Recommended handling of the error. summary: type: string description: One-line summary of the recommendation. explanation: type: string description: What happens and why (root cause), as markdown. reproduction: type: string description: Preconditions and steps to reproduce, as markdown. fixDetails: type: string description: The recommended fix in detail, as markdown. Present when action is fix. source: type: string enum: - manual - ai-draft description: Provenance of the recommendation content. annotationID: type: string description: |- ID of the annotation marking that the recommended action was carried out (format `ann-`). Its presence IS the resolved state: the annotation's date is when, its description what was done. Absent while still open. The link survives the annotation's deletion; `annotation` is then absent. annotation: $ref: "#/components/schemas/observeAnnotation" assets: type: array maxItems: 100 description: > Media assets (screenshots, videos) attached to this recommendation, oldest first. Only confirmed (ready) uploads appear. View URLs are minted per asset via the downloadUrl endpoint. items: $ref: "#/components/schemas/observeAsset" createdMs: type: integer format: int64 description: Creation time in milliseconds since epoch. updatedMs: type: integer format: int64 description: Last update time in milliseconds since epoch. observeAsset: type: object description: > One user-uploaded media file (screenshot or video). The bytes live in a private object store; viewing goes through short-lived presigned URLs (see the downloadUrl endpoint), so this object carries metadata only. required: - id - fileName - contentType - sizeBytes - status - createdMs properties: id: type: string description: |- Asset ID (format `ast-`). fileName: type: string description: Original file name, for display. contentType: type: string description: MIME type (image/png, image/jpeg, image/webp, image/gif, video/mp4, video/webm, video/quicktime). sizeBytes: type: integer format: int64 description: Declared (and, once ready, verified) file size in bytes. status: type: string enum: - pending - ready description: Upload lifecycle — pending until the uploaded object was confirmed. createdMs: type: integer format: int64 description: Creation time in milliseconds since epoch. observeAssetCreateReq: type: object required: - fileName - contentType - sizeBytes properties: fileName: type: string description: Original file name, for display. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 contentType: type: string description: > MIME type of the upload. Allowed: image/png, image/jpeg, image/webp, image/gif (up to 20 MB) and video/mp4, video/webm, video/quicktime (up to 500 MB). The presigned URL is bound to it — the browser's PUT must send exactly this content type. x-oapi-codegen-extra-tags: validate: required,oneof=image/png image/jpeg image/webp image/gif video/mp4 video/webm video/quicktime sizeBytes: type: integer format: int64 minimum: 1 description: Exact file size in bytes; verified against the uploaded object on confirm. x-oapi-codegen-extra-tags: validate: required,min=1 observeAssetCreateRsp: type: object required: - asset - uploadUrl - uploadExpiresAtMs properties: asset: $ref: "#/components/schemas/observeAsset" uploadUrl: type: string description: Presigned URL to PUT the file to, with the declared content type as the Content-Type header. uploadExpiresAtMs: type: integer format: int64 description: When the upload URL stops working, in milliseconds since epoch. observeAssetDownloadUrlRsp: type: object required: - url - expiresAtMs properties: url: type: string description: Presigned view URL for the asset. expiresAtMs: type: integer format: int64 description: When the URL stops working, in milliseconds since epoch. Request a fresh one per view. observeErrorRecommendationUpsertReq: type: object required: - action - summary properties: action: type: string enum: - ignore - observe - fix description: Recommended handling of the error. x-oapi-codegen-extra-tags: validate: required,oneof=ignore observe fix summary: type: string description: One-line summary of the recommendation. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 explanation: type: string description: What happens and why (root cause), as markdown. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=16384 reproduction: type: string description: Preconditions and steps to reproduce, as markdown. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=16384 fixDetails: type: string description: The recommended fix in detail, as markdown. Required when action is fix. x-oapi-codegen-extra-tags: validate: required_if=Action fix,omitempty,min=1,max=16384 source: type: string enum: - manual - ai-draft description: Provenance of the recommendation content; defaults to manual. x-oapi-codegen-extra-tags: validate: omitempty,oneof=manual ai-draft annotationID: type: string description: |- Annotation marking that the recommended action was carried out (format `ann-`) — linking it IS resolving the recommendation. Must exist in the project. Omitting it on a later upsert reopens (the annotation itself is untouched). x-oapi-codegen-extra-tags: validate: omitempty,id=ann observeErrorCreateReq: type: object required: - name properties: name: type: string description: Human-readable error name. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string description: Optional longer description of the error. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=1024 type: type: string enum: - general - project-specific description: Error type; defaults to project-specific. x-oapi-codegen-extra-tags: validate: omitempty,oneof=general project-specific severity: type: string enum: - error - warn - info description: Triage severity; defaults to error. x-oapi-codegen-extra-tags: validate: omitempty,oneof=error warn info flavourIDs: type: array maxItems: 1000 items: type: string x-oapi-codegen-extra-tags: validate: required,id=erf description: |- Optional initial set of flavours to assign to the new error (format `erf-`). Must all share one subflow type, which becomes the error's auto-stamped scope. x-oapi-codegen-extra-tags: validate: omitempty,max=1000,dive assignSource: type: string enum: - manual - kb - agent description: Provenance of the initial flavour assignment (defaults to manual). Only allowed together with flavourIDs. x-oapi-codegen-extra-tags: validate: excluded_without=FlavourIDs,omitempty,oneof=manual kb agent assignReason: type: string description: Human-readable explanation of why the initial flavours belong to this error; stored per flavour. Only allowed together with flavourIDs. x-oapi-codegen-extra-tags: validate: excluded_without=FlavourIDs,omitempty,min=1,max=500 observeErrorUpdateReq: type: object required: - name properties: name: type: string description: Human-readable error name. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string description: Optional longer description of the error. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=1024 type: type: string enum: - general - project-specific description: Error type; defaults to project-specific. x-oapi-codegen-extra-tags: validate: omitempty,oneof=general project-specific severity: type: string enum: - error - warn - info description: Triage severity; defaults to error. x-oapi-codegen-extra-tags: validate: omitempty,oneof=error warn info observeAnnotationCreateReq: type: object required: - headline - dateMs properties: headline: type: string description: Short headline describing the annotation. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string description: Optional longer description of the annotation. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 dateMs: description: The annotated point in time in milliseconds since epoch. type: integer format: int64 x-oapi-codegen-extra-tags: validate: required,min=0 observeAnnotationUpdateReq: type: object required: - headline - dateMs properties: headline: type: string description: Short headline describing the annotation. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string description: Optional longer description of the annotation. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 dateMs: description: The annotated point in time in milliseconds since epoch. type: integer format: int64 x-oapi-codegen-extra-tags: validate: required,min=0 observeEventCreateReq: type: object required: - sessionID - events properties: deliveryAck: type: boolean description: Request synchronous durable ingestion. Only a committed request returns X-Corbado-Observe-Accepted=1; temporary persistence failures return 503. Legacy delivery is unchanged. sessionID: type: string description: Session ID for the events (UUID format) example: "550e8400-e29b-41d4-a716-446655440000" x-oapi-codegen-extra-tags: validate: required,uuid events: type: array description: Array of events to create. The combined number of events and lows must be at least 1 and at most 2000. items: $ref: "#/components/schemas/observeEvent" x-oapi-codegen-extra-tags: validate: max=2000,dive lows: type: array description: Array of low-level events to create. The combined number of events and lows must be at least 1 and at most 2000. items: $ref: "#/components/schemas/observeLow" x-oapi-codegen-extra-tags: validate: omitempty,max=2000,dive telemetry: type: array description: | Diagnostic telemetry entries (SDK/integration-side messages, not auth-flow events). They ride along with the normal event batch, are tied to the same session, and never participate in flow classification. A batch may carry telemetry only (no events/lows). Capped at 2000 per batch. items: $ref: "#/components/schemas/observeTelemetry" x-oapi-codegen-extra-tags: validate: omitempty,max=2000,dive meta: $ref: "#/components/schemas/observeEventMetaSession" sdk: $ref: "#/components/schemas/observeSdkInfo" observeSdkInfo: type: object description: >- Identity of the SDK that produced the batch. Clients have always sent this; it is declared here so the backend can branch on it (e.g. serve the app-specific reliability config to native SDKs). Optional for backwards compatibility. required: - name - version properties: name: type: string description: SDK wire name, e.g. "@corbado/observe" (web) or "observe-android". x-oapi-codegen-extra-tags: validate: max=64 version: type: string description: SDK version, e.g. "0.2.0". x-oapi-codegen-extra-tags: validate: max=32 observeEventCreateRes: type: object description: | SDK reliability configuration. Returned from the event ingestion endpoints only when the client opts in by sending the `X-Corbado-Observe-Config` request header carrying the config version the client is currently running (or `1` when it has none cached). When the sent version matches the current one the endpoints return `204 No Content` (nothing new); without the header they always return `204`, so this is a fully backwards-compatible addition. The SDK applies a received config on its next page load (boot-snapshot model) and stamps the version it ran under into each batch's `meta.configVersion`. required: - version - flushIntervalMs - durableOutbox - durableLowOutbox - beaconKeepalive - sessionContinuity - sessionInactivityMs - seqLockTimeoutMs - tvc - tph - td - telemetry - rawErrors - flushOnTelemetry - flushOnEventNames - flushOnFlowTypeFinished - deviceInfoCollectorTimeoutMs - deviceInfoTiming - aap - sourcePathQuery - sourcePathQueryAllow - retry properties: version: type: string description: | Content-derived version (hash) of this configuration. Changes whenever any value changes. The SDK caches it, echoes it in the `X-Corbado-Observe-Config` request header, and stamps it into `meta.configVersion` of every event batch so analyses can segment by the config actually in effect. example: "3f2a1b9c0d4e" flushIntervalMs: type: integer format: int32 description: How often the SDK should flush its event queue, in milliseconds. example: 500 durableLowOutbox: type: boolean description: Persist lows in a separate bounded outbox and require durable server acknowledgement. Default false. durableOutbox: type: boolean description: Whether the SDK should persist queued events to a durable outbox so they survive reloads, redirects and browser-context switches. beaconKeepalive: type: boolean description: Whether the SDK should use keepalive/sendBeacon transport for flushes triggered during page unload. sessionContinuity: type: boolean description: Whether the SDK should maintain session continuity across browser-context switches (e.g. in-app browser to system browser). sessionInactivityMs: type: integer format: int32 description: | Inactivity threshold for continuity sessions, in milliseconds. When more time than this has passed since the last tracked activity, the SDK rotates to a new session id on the next load. Only relevant when `sessionContinuity` is enabled. example: 1800000 seqLockTimeoutMs: type: integer format: int32 description: | Maximum time to wait for the cross-tab sequence Web Lock before allocating without it, in milliseconds. Clamped to 0–100ms. 0 is a sentinel that disables the lock: the SDK then allocates the sequence counter without requesting a lock at all, giving up cross-tab atomicity (two tabs can allocate the same seq) to save a lock round-trip per event. example: 5 tvc: type: boolean description: | Flush-trigger switch: flush pending events when the document becomes hidden (`visibilitychange`). Default true; the SDK treats a missing value as true, so delivery can never be disabled by accident. tph: type: boolean description: "Flush-trigger switch: flush pending events on `pagehide` (navigation/close). Default true." td: type: boolean description: "Flush-trigger switch: flush pending events when the integrator calls `destroy()`. Default true." rawErrors: type: boolean default: true description: | Enables serialization of explicitly supplied raw error diagnostics into stepData.rawError. Server default is true; an explicit false disables diagnostics. Normalized errors are always reported independently. SDK built-in defaults may differ (Android defaults off). SDKs apply this using their normal config lifecycle; disabling affects newly captured diagnostics, not events already queued. telemetry: type: boolean description: | Master switch for the diagnostic telemetry stream. When true the SDK sends buffered telemetry entries (`observeTelemetry`) piggybacked on normal event requests; when false it collects nothing and sends nothing. Lets telemetry be turned off server-side without a customer redeploy. flushOnTelemetry: type: boolean description: | When true (and `telemetry` is enabled), enqueuing a telemetry entry triggers an immediate client flush so diagnostics go out promptly (e.g. before a crash/navigation). Default false: a telemetry entry alone never triggers a flush, it only rides the next flush caused by anything else. flushOnEventNames: type: array description: | Superseded by `flushOnFlowTypeFinished`; served only for SDK versions that predate it (they ignore the new field, newer SDKs ignore this one). Event names that trigger an immediate client-side flush when enqueued (e.g. `flow_finished`, `conversion`), so high-value events go out while the page is still alive instead of relying on unload delivery. Empty = no priority events. Capped at 20 names (both sides). items: type: string example: ["flow_finished", "conversion"] flushOnFlowTypeFinished: type: array description: | Flow types whose completion triggers an immediate client-side flush when enqueued, so the highest-value events go out while the page is still alive instead of relying on unload delivery. Both completion events count — `flow_finished` and `flow_auto_finished` — matched on their `flowName`; no other event name ever flushes early. Empty = no priority flows. Capped at 20 entries (both sides). Replaces `flushOnEventNames`, which SDKs from the version that introduced this field on no longer read. items: type: string example: ["login", "enrollment"] deviceInfoCollectorTimeoutMs: type: integer format: int32 description: | Per-field timeout for the SDK's device info collection, in milliseconds. A browser API that does not answer within this budget is recorded as a timeout in the event's device info collection errors and the field stays empty; the other fields are unaffected. Clamped to 10–10000ms. The SDK reads it per collection run, so a new value takes effect from the next device info refresh; the first collection of a load without a cached config runs on the built-in default. example: 1000 deviceInfoTiming: type: boolean description: | When true (and `telemetry` is enabled), every device info collection emits an `info` telemetry entry carrying the total duration and each field's duration in milliseconds. Default false — a diagnostic stream to switch on while investigating slow collection, not for permanent use. Durations of fields that hit `deviceInfoCollectorTimeoutMs` are censored at that value. aap: type: string description: | Capability policy token for Corbado frontend SDKs and adapters. Values are assigned by Corbado per project and select how a capability behaves for that project; an SDK that does not implement the token it receives ignores it and keeps its standard behavior. Empty (the default) always means standard behavior. Capped at 16 characters — a longer value is served as empty. example: "c1" sourcePathQuery: type: string description: | Which query values the SDK includes in the page URL it reports as `meta.trackingSourcePath`: `allowlist` (the default) or `all`. `allowlist` keeps every query key and its position but replaces each value with `*` unless its key is listed in `sourcePathQueryAllow` (empty by default, so every value is masked); empty values and keys without a value stay as they are. `all` sends the query unchanged. The path itself is never changed. Any value other than `all` (including unset or empty) is served as `allowlist`. Server-side email/phone redaction still applies to whatever is sent. example: allowlist sourcePathQueryAllow: type: array description: | Query keys whose values are kept when `sourcePathQuery` is `allowlist`. Matched case-insensitively and exactly; a trailing `*` matches a key prefix (`utm_*`). Empty or oversized entries (more than 64 characters) are dropped and the list is capped at 50 entries (both sides). Empty by default. Ignored in `all` mode. items: type: string example: ["utm_*", "section"] retry: $ref: "#/components/schemas/observeEventCreateResRetry" observeEventCreateResRetry: type: object description: Client-side retry configuration (exponential backoff) for failed event flushes. required: - maxAttempts - baseDelayMs - maxDelayMs properties: maxAttempts: type: integer format: int32 description: Maximum number of send attempts, including the first one. example: 5 baseDelayMs: type: integer format: int32 description: Base delay for exponential backoff, in milliseconds. example: 500 maxDelayMs: type: integer format: int32 description: Maximum backoff delay between attempts, in milliseconds. example: 15000 observeSdkConfigApp: type: object description: | SDK reliability configuration for native app SDKs (observe-android/observe-ios). Served from the config GET endpoint when `sdkName` names a native SDK, or from event ingestion instead of observeEventCreateRes when the request's `sdk.name` names a native SDK. Contains only native fields — web-only flags (beaconKeepalive, seqLockTimeoutMs, tvc/tph/tlf, durableOutbox, sessionContinuity) never appear. Config GET always returns the current policy and content-hash version. Legacy ingestion uses the `X-Corbado-Observe-Config` request header and returns 204 when the version is current. required: - version - flushIntervalMs - sessionInactivityMs - telemetry - rawErrors - flushOnTelemetry - flushOnFlowTypeFinished - deviceInfoCollectorTimeoutMs - flushOnBackground - retry properties: version: type: string description: Content-derived version (hash); echoed by the SDK in the request header. flushIntervalMs: type: integer format: int32 description: How often the SDK flushes its event queue, in milliseconds. Native default is 2000 (battery/radio frugality). sessionInactivityMs: type: integer format: int32 description: Inactivity threshold after which the session id rotates, in milliseconds. rawErrors: type: boolean default: true description: | Enables serialization of explicitly supplied raw error diagnostics into stepData.rawError. Server default is true; an explicit false disables diagnostics. Normalized errors are always reported independently. SDK built-in defaults may differ (Android defaults off). SDKs apply this using their normal config lifecycle; disabling affects newly captured diagnostics, not events already queued. telemetry: type: boolean description: Master switch for the diagnostic telemetry stream. flushOnTelemetry: type: boolean description: When true (and telemetry is enabled), enqueuing a telemetry entry triggers an immediate flush. flushOnFlowTypeFinished: type: array items: type: string description: Flow types whose completion (flow_finished/flow_auto_finished) triggers an immediate flush. deviceInfoCollectorTimeoutMs: type: integer format: int32 description: Per-field timeout for device info collection, in milliseconds. flushOnBackground: type: boolean description: >- Native flush-trigger switch: flush pending events when the app leaves the foreground (the last reliable delivery moment before a potential process kill). Defaults to true; a missing value can never disable delivery. retry: $ref: "#/components/schemas/observeEventCreateResRetry" observeDataDeletionJobCreateReq: type: object required: - externalIDs properties: externalIDs: type: array description: Array of external user IDs to create deletion jobs for items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=1000,dive,required,min=1,max=255 observeClassificationEnsureReq: type: object properties: userID: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=tus externalID: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 observeClassificationScheduleReq: type: object required: - sessionIDs properties: sessionIDs: type: array description: Internal numeric session IDs (decimal strings, uint64 range). Larger uploads are sent in several calls. items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=50000,dive,required,number,max=20 observeClassificationScheduleRsp: type: object required: - scheduled - skippedPending - skippedUnknown properties: scheduled: type: integer format: int64 description: Jobs created. skippedPending: type: integer format: int64 description: Sessions skipped because they already have a pending classification job. skippedUnknown: type: integer format: int64 description: Session IDs skipped because they do not exist in the project. firstStartAtMs: type: integer format: int64 description: Start time of the first created job; absent when nothing was scheduled. lastStartAtMs: type: integer format: int64 description: Start time of the last created job; absent when nothing was scheduled. observeClassificationScheduleBacklog: type: object required: - jobs properties: jobs: type: integer format: int64 description: Pending jobs that start after the ingest job delay. lastStartAtMs: type: integer format: int64 description: Start time of the last backlog job; absent when the backlog is empty. observeClassificationConfig: type: object required: - manualJobsPerMinute - ingestJobDelaySeconds properties: manualJobsPerMinute: type: integer description: Maximum number of scheduled (manual) classification jobs that start per minute. Default 2000. ingestJobDelaySeconds: type: integer description: Delay between ingesting a batch and classifying its session. Default 120. observeClassificationSessionResult: type: object required: - sessionID - status - recalculated properties: sessionID: type: string description: Public session UUID. status: type: string enum: - ready - failed - unavailable recalculated: type: boolean observeClassificationEnsure: type: object required: - sessions properties: sessions: type: array items: $ref: "#/components/schemas/observeClassificationSessionResult" observeClassificationRunReq: type: object required: - sessionIDs properties: sessionIDs: type: array items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,dive,required,uuid observeFlowSearchReq: type: object properties: userIDs: type: array description: |- User IDs to filter flows by (format `tus-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=tus flowIDs: type: array description: |- Flow IDs to filter by (format `flw-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=flw flowListIDs: type: array description: |- Restrict the search to the flows held by these stored ID lists (format `idl-`, from POST /observe/idLists) — the same cohort handles `GET /observe/timeSeries?flowListID=` renders a funnel over. Several lists are unioned, and the result is intersected with `flowIDs` when both are given. Counts as a selector, so a cohort-scoped search needs no date range; all other filters (path, tags, outcome, …) still narrow within the cohort. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=4,dive,id=idl sessionIDs: type: array description: Public session UUIDs to filter flows by. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,uuid fromDate: type: string description: Optional start of date range (yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss), interpreted in UTC. Requires `toDate`. x-oapi-codegen-extra-tags: validate: omitempty,min=10,max=19 toDate: type: string description: Optional exclusive end of date range (yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss), interpreted in UTC. Requires `fromDate` and must be at most 366 days after it. x-oapi-codegen-extra-tags: validate: omitempty,min=10,max=19 flowType: type: array description: Filter by built-in or project-specific custom flow type names. items: type: string minLength: 1 maxLength: 50 x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=50 touchpoint: type: array x-go-type: '[]*string' description: Filter by touchpoint values; null includes flows with an absent or empty touchpoint. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - "null" outcome: type: array description: Filter by outcome values items: type: string enum: - complete - incomplete - skipped - invisible - visible-auto-skip x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,oneof=complete incomplete skipped invisible visible-auto-skip path: type: array description: Filter by long_path values (the t2 dimension of *-flow-v1) items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=3000 osName: type: array x-go-type: '[]*string' description: Filter by OS name; null includes flows with an absent or empty OS name. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=100 items: type: - string - "null" browserName: type: array x-go-type: '[]*string' description: Filter by browser name; null includes flows with an absent or empty browser name. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=100 items: type: - string - "null" osVersion: type: array description: Filter by OS version (the maj.min.pat string, matching the error-flavour timeseries tag) items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=100 flavourIDs: type: array description: |- Restrict to flows that carry an error occurrence of one of these error flavours (format `erf-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=erf applicationID: type: array x-go-type: '[]*string' description: Filter by application ID; null includes flows with no application ID. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=25 items: type: - string - "null" customTag1: type: array x-go-type: '[]*string' description: Filter by first configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - "null" customTag2: type: array x-go-type: '[]*string' description: Filter by second configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - "null" customTag3: type: array x-go-type: '[]*string' description: Filter by third configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - "null" customTag4: type: array x-go-type: '[]*string' description: Filter by fourth configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - "null" customTag5: type: array x-go-type: '[]*string' description: Filter by fifth configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - "null" customTag6: type: array x-go-type: '[]*string' description: Filter by sixth configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - "null" resetCount: type: array description: Filter by reset count items: type: integer x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=0,max=255 errorCount: type: array description: Filter by exact error count items: type: integer x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=0,max=255 durationBand: type: array description: >- Filter by flow-duration band. Each token maps to a range on ob_flow.duration; multiple tokens are OR-combined. le3s=<=3s, le10s=<=10s, le30s=<=30s, le1m=<=60s, le5m=<=300s, g5m=>300s. items: type: string enum: - le3s - le10s - le30s - le1m - le5m - g5m x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,oneof=le3s le10s le30s le1m le5m g5m minErrorCount: type: integer description: >- Filter to flows whose error count is at least this value. Independent from `errorCount` (exact-value set); when both are supplied they are AND-combined. Pass 1 to match errored flows. minimum: 0 maximum: 255 x-oapi-codegen-extra-tags: validate: omitempty,min=0,max=255 experimentID: type: string description: |- Restrict flows to those exposed to this experiment run (format `exp-`). Enables joining variant attribution; each returned flow includes its `variantID`. x-oapi-codegen-extra-tags: validate: omitempty,id=exp variantIDs: type: array description: |- Restrict flows to these experiment variants (format `exv-`). Requires `experimentID`. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=exv limit: type: integer description: Maximum number of flows to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeFlowSearchRsp: type: object required: - flows - totalCount properties: flows: type: array description: Matching flows in stable timeline order, oldest first, capped at `limit`. items: $ref: "#/components/schemas/observeFlowSearchEntry" totalCount: type: integer description: >- Number of matching flows returned (equal to len(flows), capped at `limit`). This is the exact total when it is below `limit`; when it equals `limit` there may be more matches that were not counted (the endpoint runs no separate COUNT query, for efficiency). observeFlowSearchEntry: type: object required: - flowID - sessionID - flowType - outcome - visitorType - errorCount - resetCount - durationMs - previousTotalCount - previousSameTouchpointCount - createdMs properties: parentFlowID: type: string description: Enclosing flow (flw-...), when nested. Older unrefreshed rows may not have this relationship. clientEnvDataID: type: string description: Exact environment snapshot row ID, encoded as a decimal string. longPath: type: string description: Full classified path, preserving technical outcome codes. flowID: type: string description: |- Flow ID (format `flw-`). sessionID: type: string description: Session ID (UUID format). userID: type: string description: |- User ID (format `tus-`). Absent for anonymous flows. externalID: type: string description: Customer-provided external user ID. Absent for anonymous flows. clientEnvID: type: string description: |- Client environment ID (format `tce-`). Absent when no client environment was resolved. flowType: type: string description: Flow type (login, enrollment, signup, recovery) outcome: type: string enum: - complete - incomplete - skipped - invisible - visible-auto-skip description: Flow outcome visitorType: type: string enum: - user - auto-test x-enum-varnames: - ObserveFlowSearchEntryVisitorTypeUser - ObserveFlowSearchEntryVisitorTypeAutoTest description: Visitor type classified for the flow. errorCount: type: integer description: Number of errors during the flow. resetCount: type: integer description: Number of resets during the flow. durationMs: type: integer format: int64 description: Duration of the flow in milliseconds. previousFlowDiffMs: type: integer format: int64 description: Time since the previous flow for the same user in milliseconds, when available. previousTotalCount: type: integer description: Number of previous flows for the same user. previousSameTouchpointCount: type: integer description: Number of previous flows for the same user and touchpoint. createdMs: description: Flow creation time in milliseconds since epoch type: integer format: int64 osName: type: string description: OS name browserName: type: string description: Browser name osVersion: type: string description: OS major version browserVersion: type: string description: Browser major version model: type: string description: Device model from Sec-CH-UA-Model (when the client opted in). Absent on older data and when the header was not sent. uvpaa: type: boolean description: >- Whether a user-verifying platform authenticator was available on the client (isUVPAA). Null on app-only flows and rare web flows missing a capability snapshot. applicationID: type: string description: Application ID touchpoint: type: string description: Flow touchpoint customTag1: type: string description: Value of the first configured custom tag for this flow customTag2: type: string description: Value of the second configured custom tag for this flow customTag3: type: string description: Value of the third configured custom tag for this flow customTag4: type: string description: Value of the fourth configured custom tag for this flow customTag5: type: string description: Value of the fifth configured custom tag for this flow customTag6: type: string description: Value of the sixth configured custom tag for this flow variantID: type: string description: |- Experiment variant the flow was exposed to (format `exv-`). Present only when `experimentID` was supplied in the request. observeSubFlowSearchReq: type: object properties: includeDetails: type: boolean description: Include batched environment, error and tag details for userIDs, flowIDs or sessionIDs selectors. Filters retain their output setting. userIDs: type: array description: |- User IDs to fetch subflows for (format `tus-`). Mutually exclusive with other selectors. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=tus flowIDs: type: array description: |- Flow IDs to fetch subflows for (format `flw-`). Mutually exclusive with other selectors. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=flw sessionIDs: type: array description: Public session UUIDs to fetch subflows for. Mutually exclusive with other selectors. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,uuid filters: $ref: "#/components/schemas/observeSubFlowSearchFilters" subFlowTypes: type: array description: Optional subflow types to include. items: $ref: "#/components/schemas/observeSubFlowType" x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,oneof=passkeyLogin passwordLogin socialLogin provideIdentifier decision passkeyEnrollment emailOTP emailLink setPassword provideData reset passkeyDeletion smsOTP totp appConfirmation systemCredential trustedDeviceCheck trustedDeviceEnrollment keySigning keyRegistration limit: type: integer description: Maximum number of subflows to return in total across all subflow types. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeSubFlowSearchRsp: type: object required: - subFlows properties: subFlows: type: array description: >- Matching subflows, capped at `limit`. ID-based selectors order oldest first; the `filters` selector orders newest first. items: $ref: "#/components/schemas/observeSubFlowSearchEntry" totalCount: type: integer format: int64 description: >- Total number of matching subflows before the `limit` cap. Only set for the `filters` selector — compare against the returned count to detect truncation (analytics over a truncated result cover the most recent totalCount-of-limit slice, not the whole window). flowIDs: type: array description: |- Deduplicated parent flow IDs (format `flw-`) of the returned subflows, in result order. Only set for the `filters` selector. Store via POST /observe/idLists to hand the cohort to user-search or a funnel. items: type: string aggregates: type: array description: >- Per-group counts of the matching subflows — only set for `output=aggregate`. Ordered by count descending and capped at 5000 cells (`aggregateTruncated` reports the cap firing; `totalCount` stays exact regardless). A value of "" means the dimension is not set on the subflow. items: $ref: "#/components/schemas/observeSubFlowSearchAggregateCell" aggregateTruncated: type: boolean description: True when the aggregate cell cap dropped long-tail groups. observeSubFlowSearchAggregateCell: type: object required: - values - count properties: values: type: object description: The group's dimension values, keyed by the requested groupBy tokens. additionalProperties: type: string count: type: integer format: int64 description: Number of matching subflows in this group. observeSubFlowSearchFilters: type: object description: >- Time-window selector with optional narrowing filters. All narrowing filters are AND-combined; values within one filter are OR-combined. Filters targeting a column a subflow type does not have (e.g. cdaLikelihoods on anything but passkey-login) simply exclude that type from the result. required: - fromDate - toDate properties: fromDate: type: string description: Start of the subflow-start window (yyyy-MM-dd), interpreted in UTC. x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02 toDate: type: string description: End of the subflow-start window (yyyy-MM-dd, exclusive), interpreted in UTC. At most 366 days after `fromDate`. x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02 flavourIDs: type: array description: |- Restrict to subflows that carry an error occurrence of one of these error flavours (format `erf-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=erf osName: type: array description: Filter by OS name. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=100 browserName: type: array description: Filter by browser name (web) / app name (native). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=100 applicationID: type: array description: Filter by application ID. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=25 specTypes: type: array description: Filter by subflow spec type. Excludes subflow types without a spec type. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=255 configVariantIDs: type: array description: |- Filter by challenge/config variant (format `chv-`). Only passkey-login, passkey-enrollment and provide-identifier subflows carry one. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=chv cdaLikelihoods: type: array description: Filter by CDA-likelihood bucket. Only passkey-login subflows carry one. items: type: string enum: - no - 25-50 - 50-75 - 75-95 - 95-plus x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,oneof=no 25-50 50-75 75-95 95-plus completed: type: boolean description: Filter by completion. Omit to match both completed and non-completed subflows. output: type: string enum: - full - flowIDs - aggregate description: >- Response shape. `full` (default) returns hydrated subflow entries enriched with environment values, error occurrences and the parent flow's custom tags. `flowIDs` returns an empty `subFlows` array and only `totalCount` plus the deduplicated parent `flowIDs` — the cheap shape for user-search / funnel handoffs. `aggregate` returns per-group counts of the matching subflows along the `groupBy` dimensions instead of rows — the exact-denominator shape for correlation analysis (no row cap bias). x-oapi-codegen-extra-tags: validate: "omitempty,oneof=full flowIDs aggregate" groupBy: type: array description: >- Dimensions to aggregate over — required with (and only valid with) `output=aggregate`. Static tokens: clientEnvType (web/app), osName, browserName (browser / app name), osVersion, browserVersion (browser version maj.min.pat / app version), deviceModel, deviceBrand, deviceOwnerAuth, playServicesVersion (the last three native-app only — web subflows fold into the "" group), specType, detailedOutcome, completed, configVariantID, cdaLikelihood. Custom tags of the parent flow via `customTag:`. A dimension a subflow type has no column for excludes that type from the aggregation. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=8,dive,min=1,max=270 detailedOutcomes: type: array description: Filter by detailed outcome values. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=255 observeSubFlowSearchEntry: type: object required: - id - flowID - sessionID - applicationID - errorCount - completed - durationMs - startMs - data properties: passkeyID: type: string description: Associated passkey (tpk-...). Interpret creation/use using method and outcome; association alone does not prove successful authentication. clientEnvDataID: type: string description: Exact environment snapshot ID as a decimal string. additionalClientEnvDataID: type: string description: Exact additional environment snapshot ID as a decimal string, when applicable. touchpoint: type: string description: Stored method touchpoint, when available. bindingID: type: string description: Trusted-device binding ID as a decimal string, when available. previouslySeenBucket: type: string description: Stored trusted-device history bucket. id: type: string description: |- Subflow ID (format `sfl-`). flowID: type: - string - "null" description: |- Parent flow ID (format `flw-`). Null when the subflow has no parent flow. sessionID: type: - string - "null" description: Public session UUID. Null when the subflow has no parent flow/session. applicationID: type: string description: Application ID. userID: type: string description: |- User ID (format `tus-`). Absent for anonymous subflows. clientEnvID: type: string description: |- Client environment ID (format `tce-`). Absent when no client environment was resolved. errorCount: type: integer description: Number of errors during the subflow. completed: type: boolean description: Whether the subflow completed successfully. durationMs: type: integer format: int64 description: Duration of the subflow in milliseconds. startMs: type: integer format: int64 description: Start time in milliseconds since epoch. firstInteractionDurationMs: type: integer format: int64 description: Duration from implicit decision start to first user interaction in milliseconds. detailedOutcome: type: string description: Detailed subflow outcome when available. connectedDecisionID: type: string description: |- Decision subflow ID that triggered this subflow (format `sfl-`), when available. environment: $ref: "#/components/schemas/observeSubFlowSearchEnvironment" errors: type: array description: >- Error occurrences detected on this subflow during classification, oldest first. Only set for `filters` with `output=full` or ID selectors with `includeDetails=true`. Resolve signature details and the mapped error via the error flavour list. items: $ref: "#/components/schemas/observeSubFlowSearchErrorOccurrence" customTags: type: array description: >- Custom tags of the parent flow, name-sorted. Only set for the `filters` selector with `output=full`. items: $ref: "#/components/schemas/observeSubFlowSearchCustomTag" data: $ref: "#/components/schemas/observeSubFlowData" observeSubFlowSearchEnvironment: type: object description: >- Resolved client-environment values of a subflow. Only set for the `filters` selector with `output=full`; ID-based selectors keep returning the clientEnvID reference only. properties: osName: type: string description: OS name, when recorded. browserName: type: string description: Browser name (web) / app name (native), when recorded. osVersion: type: string description: OS version as maj.min.pat; absent when unrecorded. clientEnvType: $ref: "#/components/schemas/observeClientEnvType" browserVersion: type: string description: Browser version as maj.min.pat (web) / app version (native), when recorded. deviceModel: type: string description: Device model (web via Sec-CH-UA-Model, native from the app), when recorded. deviceBrand: type: string description: Device brand (native only), when recorded. deviceOwnerAuth: type: string description: Screen-lock / device-owner authentication class (native only), when recorded. playServicesVersion: type: string description: Google Play Services version (Android only), when recorded. observeSubFlowSearchErrorOccurrence: type: object required: - flavourID - createdMs properties: flavourID: type: string description: |- Raw-signature flavour of the occurrence (format `erf-`). durationMs: type: integer format: int64 description: Subflow-start-to-error latency in milliseconds, when recorded. createdMs: type: integer format: int64 description: Occurrence time in milliseconds since epoch. observeSubFlowSearchCustomTag: type: object required: - name - value properties: name: type: string value: type: string observeSubFlowData: oneOf: - $ref: "#/components/schemas/observeSubFlowPasskeyLoginData" - $ref: "#/components/schemas/observeSubFlowPasswordLoginData" - $ref: "#/components/schemas/observeSubFlowSocialLoginData" - $ref: "#/components/schemas/observeSubFlowProvideIdentifierData" - $ref: "#/components/schemas/observeSubFlowDecisionData" - $ref: "#/components/schemas/observeSubFlowPasskeyEnrollmentData" - $ref: "#/components/schemas/observeSubFlowEmailOTPData" - $ref: "#/components/schemas/observeSubFlowEmailLinkData" - $ref: "#/components/schemas/observeSubFlowSetPasswordData" - $ref: "#/components/schemas/observeSubFlowProvideDataData" - $ref: "#/components/schemas/observeSubFlowResetData" - $ref: "#/components/schemas/observeSubFlowPasskeyDeletionData" - $ref: "#/components/schemas/observeSubFlowSmsOTPData" - $ref: "#/components/schemas/observeSubFlowTotpData" - $ref: "#/components/schemas/observeSubFlowAppConfirmationData" - $ref: "#/components/schemas/observeSubFlowSystemCredentialData" - $ref: "#/components/schemas/observeSubFlowKeySigningData" - $ref: "#/components/schemas/observeSubFlowKeyRegistrationData" - $ref: "#/components/schemas/observeSubFlowTrustedDeviceCheckData" - $ref: "#/components/schemas/observeSubFlowTrustedDeviceEnrollmentData" discriminator: propertyName: type mapping: passkeyLogin: "#/components/schemas/observeSubFlowPasskeyLoginData" passwordLogin: "#/components/schemas/observeSubFlowPasswordLoginData" socialLogin: "#/components/schemas/observeSubFlowSocialLoginData" provideIdentifier: "#/components/schemas/observeSubFlowProvideIdentifierData" decision: "#/components/schemas/observeSubFlowDecisionData" passkeyEnrollment: "#/components/schemas/observeSubFlowPasskeyEnrollmentData" emailOTP: "#/components/schemas/observeSubFlowEmailOTPData" emailLink: "#/components/schemas/observeSubFlowEmailLinkData" setPassword: "#/components/schemas/observeSubFlowSetPasswordData" provideData: "#/components/schemas/observeSubFlowProvideDataData" reset: "#/components/schemas/observeSubFlowResetData" passkeyDeletion: "#/components/schemas/observeSubFlowPasskeyDeletionData" smsOTP: "#/components/schemas/observeSubFlowSmsOTPData" totp: "#/components/schemas/observeSubFlowTotpData" appConfirmation: "#/components/schemas/observeSubFlowAppConfirmationData" systemCredential: "#/components/schemas/observeSubFlowSystemCredentialData" keySigning: "#/components/schemas/observeSubFlowKeySigningData" keyRegistration: "#/components/schemas/observeSubFlowKeyRegistrationData" trustedDeviceCheck: "#/components/schemas/observeSubFlowTrustedDeviceCheckData" trustedDeviceEnrollment: "#/components/schemas/observeSubFlowTrustedDeviceEnrollmentData" observeSubFlowPasskeyLoginData: type: object required: - type properties: type: type: string enum: - passkeyLogin description: Subflow detail type discriminator. specType: type: string description: Passkey login spec type, when available. configVariantID: type: string description: |- Challenge/config variant ID (format `chv-`), when available. cdaLikelihood: type: string enum: - no - 25-50 - 50-75 - 75-95 - 95-plus description: >- Bucketed likelihood that this login could only proceed via cross-device authentication, when a statement could be made (see the CDA-likelihood classification). Absent for discoverable/CUI logins and unknown environments. observeSubFlowPasswordLoginData: type: object required: - type properties: type: type: string enum: - passwordLogin description: Subflow detail type discriminator. specType: type: string description: Password login spec type, when available. overlayAutofillCount: type: integer description: Number of autofill patterns interpreted for the subflow. overlayUnclearCount: type: integer description: Number of unclear overlay patterns interpreted for the subflow. autofillType: type: string description: Derived autofill type, when available. observeSubFlowSocialLoginData: type: object required: - type properties: type: type: string enum: - socialLogin description: Subflow detail type discriminator. specType: type: string description: Social login spec type, when available. providerName: type: string description: Social provider name, when available. observeSubFlowProvideIdentifierData: type: object required: - type properties: type: type: string enum: - provideIdentifier description: Subflow detail type discriminator. specType: type: string description: Provide-identifier spec type, when available. configVariantID: type: string description: |- Challenge/config variant ID (format `chv-`), when available. overlayCUICount: type: integer description: Number of CUI overlay patterns interpreted for the subflow. overlayAutofillCount: type: integer description: Number of autofill patterns interpreted for the subflow. overlayUnclearCount: type: integer description: Number of unclear overlay patterns interpreted for the subflow. cuiType: type: string description: Derived CUI type, when available. autofillType: type: string description: Derived autofill type, when available. observeSubFlowDecisionData: type: object required: - type properties: type: type: string enum: - decision description: Subflow detail type discriminator. decisionID: type: string description: |- Decision ID for decision subflows (format `dec-`). inputVariantID: type: string description: |- Decision input variant ID for decision subflows (format `dva-`). outcomeVariantID: type: string description: |- Decision outcome variant ID for decision subflows (format `dva-`), when available. occurrence: type: integer description: 0-based occurrence of this decision within the flow, when available. firstStartMs: type: integer format: int64 description: Original first start time of the decision in milliseconds since epoch. observeSubFlowPasskeyEnrollmentData: type: object required: - type properties: type: type: string enum: - passkeyEnrollment description: Subflow detail type discriminator. specType: type: string description: Passkey enrollment spec type, when available. configVariantID: type: string description: |- Challenge/config variant ID (format `chv-`), when available. observeEmailDomain: type: object required: - id - domain - createdMs properties: id: type: string description: |- Email domain ID (`emd-`). domain: type: string maxLength: 253 createdMs: type: integer format: int64 observeSubFlowEmailOTPData: type: object required: - type properties: type: type: string enum: - emailOTP description: Subflow detail type discriminator. specType: type: string description: Email OTP spec type, when available. emailDomainID: type: string description: |- Project-scoped email domain reference (`emd-`), omitted when not reported. resentCount: type: integer description: Number of OTP resends, when available. observeSubFlowEmailLinkData: type: object required: - type properties: type: type: string enum: - emailLink description: Subflow detail type discriminator. specType: type: string description: Email link spec type, when available. additionalClientEnvID: type: string description: |- Additional completion-side client environment ID (format `tce-`), when available. observeSubFlowSetPasswordData: type: object required: - type properties: type: type: string enum: - setPassword description: Subflow detail type discriminator. specType: type: string description: Set-password spec type, when available. overlayAutofillCount: type: integer description: Number of autofill patterns interpreted for the subflow. overlayUnclearCount: type: integer description: Number of unclear overlay patterns interpreted for the subflow. autofillType: type: string description: Derived autofill type, when available. observeSubFlowProvideDataData: type: object required: - type properties: type: type: string enum: - provideData description: Subflow detail type discriminator. specType: type: string description: Provide-data spec type, when available. fieldName: type: string description: Name of the collected data field as reported by the SDK (sanitized), when available. observeSubFlowResetData: type: object required: - type properties: type: type: string enum: - reset description: Subflow detail type discriminator. observeSubFlowPasskeyDeletionData: type: object required: - type properties: type: type: string enum: - passkeyDeletion description: Subflow detail type discriminator. observeSubFlowSmsOTPData: type: object required: - type properties: type: type: string enum: - smsOTP description: Subflow detail type discriminator. specType: type: string description: SMS OTP spec type, when available. resentCount: type: integer description: Number of OTP resends, when available. observeSubFlowTotpData: type: object required: - type properties: type: type: string enum: - totp description: Subflow detail type discriminator. specType: type: string description: TOTP spec type, when available. observeSubFlowAppConfirmationData: type: object required: - type properties: type: type: string enum: - appConfirmation description: Subflow detail type discriminator. specType: type: string description: App confirmation spec type (e.g. qr-code), when available. retryCount: type: integer description: Number of retry steps within the confirmation, when available. ceremonyErrorCode: type: string description: Terminal ceremony error code (declined/expired) when the confirmation failed; empty otherwise. observeSubFlowSystemCredentialData: type: object required: - type properties: type: type: string enum: - systemCredential description: Subflow detail type discriminator. specType: type: string description: >- Requested credential option set (e.g. passkey-password, with the -auto suffix for sheets fired without a user gesture), when available. outcome: type: string description: >- System-credential outcome (complete-passkey / complete-password / complete-federated / fill-password / incomplete), when available. observeSubFlowKeySigningData: type: object required: - type properties: type: type: string enum: - keySigning description: Direct key signing. Completion includes preparing a usable signed artifact. observeSubFlowKeyRegistrationData: type: object required: - type properties: type: type: string enum: - keyRegistration description: Key registration. Completion means the authority is accepted and usable. observeSubFlowTrustedDeviceCheckData: type: object required: - type properties: type: type: string enum: - trustedDeviceCheck specType: type: string description: Reported mechanism (key or token). outcome: type: string description: Classified trust check or enrollment result. purpose: type: string description: Reported check purpose (additional-verification or mfa-exemption). storage: type: string trustName: type: string bindingReference: type: string description: Optional pseudonymous reference to an identified binding. observeSubFlowTrustedDeviceEnrollmentData: type: object required: - type properties: type: type: string enum: - trustedDeviceEnrollment specType: type: string description: Reported mechanism (key or token). outcome: type: string description: Classified trust check or enrollment result. purpose: type: string description: Reported check purpose (additional-verification or mfa-exemption). storage: type: string trustName: type: string bindingReference: type: string description: Optional pseudonymous reference to an identified binding. observeSubFlowType: type: string description: Observe subflow type. enum: - passkeyLogin - passwordLogin - socialLogin - provideIdentifier - decision - passkeyEnrollment - emailOTP - emailLink - setPassword - provideData - reset - passkeyDeletion - smsOTP - totp - appConfirmation - systemCredential - trustedDeviceCheck - trustedDeviceEnrollment - keySigning - keyRegistration observeDecision: type: object required: - id - name - longPathAlias properties: id: type: string description: |- Decision ID (format `dec-`). name: type: string description: Name of the decision. longPathAlias: type: string description: >- Short per-project token used for this decision in ob_flow long_paths (the `d_` value). Defaults to `id`, so old long_paths (which use the raw id) and new ones (which use the alias) are both resolvable: index decisions by BOTH `id` and `longPathAlias`. observeDecisionVariant: type: object required: - id - decisionID - type - data - longPathAlias properties: id: type: string description: |- Decision variant ID (format `dva-`). decisionID: type: string description: |- Parent decision ID (format `dec-`). type: type: string description: Type of decision variant. enum: - input - outcome data: type: string description: JSON-encoded variant data. longPathAlias: type: string description: >- Short per-project token used for this variant in ob_flow long_paths (the `i` / `o` value). Defaults to `id`; index variants by BOTH `id` and `longPathAlias`. observeChallengeVariant: type: object required: - id - subFlowType - type - data properties: id: type: string description: |- Challenge variant ID (format `chv-`). The numeric part equals the raw config_variant_id surfaced as the t8 dimension of the login-subflow-passkey-v1 time series. subFlowType: type: string description: Subflow type the variant belongs to. enum: - passkey-login - passkey-enrollment type: type: string description: Type of challenge variant (request options or response data). enum: - request - response data: type: string description: >- JSON-encoded variant data. For passkey-login request variants: allowCredentialCount, timeout, userVerification, hints, authenticatorEstimates (estimated provider names behind the allowlist, e.g. icloud-keychain; absent when the login ran without an allowlist). application: type: object required: - id - createdMs properties: id: type: string description: |- Application ID (format `app-`). externalID: type: string description: User-provided application external identifier. Absent for the default application. createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 observeLabel: type: object required: - id - entityType - entityID - option - createdMs - updatedMs properties: id: type: string description: |- Label ID (format `lbl-`). entityType: type: string description: Type of the labeled entity. entityID: type: string description: |- ID of the labeled entity. Applications use `app-`, decisions use `dec-`, decision variants use `dva-`, and decision options use the parent decision ID `dec-`. option: type: string description: | Sub-key within the labeled entity. Only used for entityType='decisionOption' where entityID references the decision and option holds the option name (e.g. "social-google"). Empty string for all other entity types. displayName: type: string description: Human-readable display name. description: type: string description: Description of the entity. createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 updatedMs: description: Last update time in milliseconds since epoch. type: integer format: int64 observeAnnotation: type: object required: - id - headline - dateMs - createdMs - updatedMs properties: id: type: string description: |- Annotation ID (format `ann-`). headline: type: string description: Short headline describing the annotation. description: type: string description: Optional longer description of the annotation. dateMs: description: The annotated point in time in milliseconds since epoch. type: integer format: int64 createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 updatedMs: description: Last update time in milliseconds since epoch. type: integer format: int64 observeAlertRuleConfig: type: object description: > The configuration of an alert rule: the generic envelope every rule type shares, plus one settings object belonging to the rule type named by type. Everything outside settings is implemented once, generically - the window is resolved and handed to the rule type as two absolute timestamps, and the conditions are applied to whatever number the rule type returned, so a rule type never sees the thresholds. Shape and vocabulary are validated here. The semantics that span fields - that the bands get stricter as the level does, that recovery sits on the lenient side of them, that the window is a whole number of days, and that groupBy names dimensions this project actually has - are validated when the rule is saved and again when it is evaluated, because only the second catches a project that changed after the rule was written. required: - version - type - window - conditions properties: version: type: integer minimum: 1 maximum: 1 description: Config schema version. Only 1 exists; a stored rule carries it so a later shape change can be migrated rather than guessed at. x-oapi-codegen-extra-tags: validate: required,oneof=1 type: type: string enum: - login_success_rate description: > The rule type this config belongs to. Must equal the rule's ruleType - the two are stored separately and the evaluator reads the column to pick the implementation, so letting them disagree would store a rule whose settings belong to one type and whose evaluation belongs to another. x-oapi-codegen-extra-tags: validate: required,oneof=login_success_rate window: type: string description: > How much history the value covers, as a duration that is a whole number of hours - "1h", "24h", "3d". Go duration syntax extended with "d" and "w". The alerting series is pre-aggregated hourly, so a window that is not a whole number of hours would resolve onto part of a bucket and answer a different question than the one configured; it is rejected when the rule is saved. x-oapi-codegen-extra-tags: validate: required evaluationDelay: type: string description: How far behind the evaluation instant the window ends, so pre-calculation has settled - e.g. "1h". Omit for none. groupBy: type: array maxItems: 10 description: > Dimension keys to alert separately by: one alert instance per combination of values, each with its own state and its own for clock. Keys are dimension names as reported by the rule type for this project, never columns or tag slots - a project that reorders its tags must not silently regroup a rule onto whatever now sits in that position. Empty means one ungrouped instance. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,unique,dive,required maxInstances: type: integer minimum: 1 maximum: 500 description: Cardinality cap for a grouped rule. Exceeding it is an error rather than a truncation, so a rule cannot quietly stop covering part of its groups. Defaults to 50. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500 settings: type: object additionalProperties: true description: > Settings belonging to type, opaque to the envelope. For login_success_rate this is observeAlertRuleSettingsLoginSuccessRate. This field stays open rather than a union, so a rule type can be added without a breaking change to this schema. conditions: type: array minItems: 1 maxItems: 3 description: > The severity bands, most severe matching band wins. All conditions must compare in the same direction, each level may appear at most once, and a more severe band must breach later than a less severe one. An equality band stands alone. There is no rule-level severity; each condition carries its own level. items: $ref: "#/components/schemas/observeAlertRuleCondition" x-oapi-codegen-extra-tags: validate: required,min=1,max=3,dive recovery: $ref: "#/components/schemas/observeAlertRuleRecovery" for: type: string description: > How long a group must stay breached before it fires, measured per instance from its own first breach - e.g. "1d". Omit to fire on the first breaching evaluation. noData: type: string enum: - ok - no_data - alerting - keep_last description: > What an instance does when its group produces no value. Defaults to no_data, which is visible in the panel and sends nothing - where keep_last would hold a firing alert firing forever and ok would quietly resolve one. x-oapi-codegen-extra-tags: validate: omitempty,oneof=ok no_data alerting keep_last overrides: type: array description: > Exceptions to the rule for particular alerts. An override's match is a complete label set - one value for every groupBy key - and it applies to exactly the alert with that label set. The alert is judged by the override's values instead of the rule's, field by field: a field the override sets replaces the rule's wholesale, a field it leaves out is inherited. Editing overrides never touches an alert's identity or history - the new values simply apply at the next evaluation. Requires groupBy; no cap on the count. items: $ref: "#/components/schemas/observeAlertRuleOverride" x-oapi-codegen-extra-tags: validate: omitempty,dive observeAlertRuleOverride: type: object description: > One exception to a rule: an alert's label set and a sparse patch of the per-alert fields. Only fields the evaluator and the rule type apply per alert can be set here - what shapes the read (window, evaluationDelay, groupBy, maxInstances) is one value per rule. required: - match properties: match: type: object additionalProperties: type: string description: > The alert's label set: one exact value for every one of the rule's groupBy keys, no more and no fewer. An override applies to exactly the alert carrying this label set. Two overrides with the same match are rejected. conditions: type: array minItems: 1 maxItems: 3 description: > The complete band set for matching alerts, validated by the same rules as the rule's own conditions and against the recovery threshold that applies (this override's, or the rule's when inherited). Omit to inherit the rule's bands. items: $ref: "#/components/schemas/observeAlertRuleCondition" x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=3,dive recovery: $ref: "#/components/schemas/observeAlertRuleRecovery" for: type: string description: Pending period for matching alerts, e.g. "3h". "0s" is a value - fire on the first breaching evaluation - and omitting it inherits the rule's. noData: type: string enum: - ok - no_data - alerting - keep_last description: No-data policy for matching alerts. Omit to inherit the rule's. x-oapi-codegen-extra-tags: validate: omitempty,oneof=ok no_data alerting keep_last settings: type: object additionalProperties: true description: > The complete settings object of the rule type for matching alerts - for login_success_rate, observeAlertRuleSettingsLoginSuccessRate. Replaces the rule's settings wholesale rather than merging into them. Omit to inherit the rule's. observeAlertRuleCondition: type: object description: One severity band - a comparison against a threshold that yields a level. required: - severity - operator - threshold properties: severity: type: string enum: - info - warning - critical description: The severity this band produces. It belongs to the condition rather than to the rule, so an alert may fire at warning and escalate to critical without changing identity. x-oapi-codegen-extra-tags: validate: required,oneof=info warning critical operator: type: string enum: - above - above_or_equal - below - below_or_equal - equal - not_equal description: How the rule's value is compared against threshold. x-oapi-codegen-extra-tags: validate: required,oneof=above above_or_equal below below_or_equal equal not_equal threshold: type: number format: double description: The value the band compares against. Zero is a meaningful threshold, so this field carries no required-value validation of its own. observeAlertRuleRecovery: type: object description: > An optional separate threshold a firing instance must clear before it resolves. Without one a rule can fire and resolve at the same value, which is the flapping this exists to prevent, so it must compare in the opposite direction to the conditions and sit on the lenient side of the least severe band. required: - operator - threshold properties: operator: type: string enum: - above - above_or_equal - below - below_or_equal - equal - not_equal x-oapi-codegen-extra-tags: validate: required,oneof=above above_or_equal below below_or_equal equal not_equal threshold: type: number format: double observeAlertRuleSettingsLoginSuccessRate: type: object description: > The settings shape for ruleType login_success_rate, carried in observeAlertRuleConfig settings: of the login flows a user actually engaged with, what share completed. This schema documents and generates that shape; the settings field itself stays an open object so that adding a rule type is not a breaking change. properties: minSample: type: integer minimum: 0 description: > The sample gate on the denominator - the engaged login flows in the window. A group below it produces no value and therefore neither fires nor resolves, which is what keeps a quiet night from reading as a collapse. Omit or 0 for no gate. observeAlertRuleCreateReq: type: object required: - name - ruleType - rule - contactPointID properties: name: type: string description: Human-readable rule name. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string description: Optional longer description of the rule. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 ruleType: type: string enum: - login_success_rate description: Type of rule; names what the rule measures and selects the rule implementation and its settings shape. x-oapi-codegen-extra-tags: validate: required,oneof=login_success_rate rule: $ref: "#/components/schemas/observeAlertRuleConfig" contactPointID: type: string description: |- Alert contact point ID (format `acp-`) this rule notifies. x-oapi-codegen-extra-tags: validate: required,id=acp labels: type: object additionalProperties: type: string description: Optional static labels attached to alerts produced by this rule. observeAlertRuleUpdateReq: type: object required: - name - ruleType - rule - contactPointID properties: name: type: string description: Human-readable rule name. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string description: Optional longer description of the rule. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 ruleType: type: string enum: - login_success_rate description: Type of rule; names what the rule measures and selects the rule implementation and its settings shape. x-oapi-codegen-extra-tags: validate: required,oneof=login_success_rate rule: $ref: "#/components/schemas/observeAlertRuleConfig" contactPointID: type: string description: |- Alert contact point ID (format `acp-`) this rule notifies. x-oapi-codegen-extra-tags: validate: required,id=acp labels: type: object additionalProperties: type: string description: Optional static labels attached to alerts produced by this rule. status: type: string enum: - active - paused description: Rule status. Use to pause/resume a rule. Cannot be set to deleted here. x-oapi-codegen-extra-tags: validate: omitempty,oneof=active paused observeAlertRule: type: object required: - id - name - ruleType - rule - contactPointID - contactPointName - status - instanceTotals - createdMs - updatedMs properties: id: type: string description: |- Alert rule ID (format `aru-`). name: type: string description: type: string ruleType: type: string enum: - login_success_rate rule: $ref: "#/components/schemas/observeAlertRuleConfig" contactPointID: type: string description: |- Alert contact point ID (format `acp-`) this rule notifies. contactPointName: type: string description: > Name of the contact point this rule notifies, resolved from contactPointID so a rule can be displayed without a second request. Display-only - requests still reference the contact point by contactPointID. labels: type: object additionalProperties: type: string status: type: string enum: - active - paused lastEvaluatedMs: type: integer format: int64 description: > When the evaluation runner last attempted this rule, successfully or not. Absent means it has never been attempted, which every rule is for up to one evaluation interval after it is created or edited - a state worth showing rather than rendering as healthy. lastErrorReason: type: string enum: - rule_type_not_implemented - config_invalid - series_not_available - dimension_not_available - too_many_instances - evaluation_failed description: > Why the last evaluation attempt failed, absent when it succeeded. This is rule health, which is a different question from whether anything the rule watches is breaching: a rule here is not evaluating at all, so it is neither firing nor all-clear. An unclassified failure reports evaluation_failed rather than a value outside this list. lastErrorMessage: type: string description: The detail behind lastErrorReason, truncated for display. Absent when the last attempt succeeded. instanceTotals: $ref: "#/components/schemas/observeAlertInstanceTotals" createdMs: type: integer format: int64 updatedMs: type: integer format: int64 observeAlertEvaluateReq: type: object properties: alertRuleID: type: string description: |- Evaluate only this rule (format `aru-`). Omit it, or omit the body entirely, to evaluate every active rule of the project. x-oapi-codegen-extra-tags: validate: omitempty,id=aru observeAlertEvaluate: type: object required: - evaluated properties: evaluated: type: integer description: > How many rules were evaluated successfully. Rules that were skipped because they are paused are not counted, and neither are rules whose evaluation failed - a failure is recorded as that rule's health and is readable on the rule itself, because one broken rule must not fail a run the rest of which worked. observeAlertInstanceTotals: type: object description: > How many of a rule's alert instances sit in each status, counted over all of them rather than over a page of them. This is what lets a rule row say "2 of 12 firing" without the client reading a single instance - and what keeps that number from quietly becoming "2 of however many were fetched" once a rule groups into more instances than one page holds. Every field is present, zero included, so a client can render the set without checking which keys exist. Counts include every instance the rule currently has. required: - normal - pending - firing - noData - error - total properties: normal: type: integer description: Instances whose value is within the thresholds. pending: type: integer description: Instances that are breaching but have not yet satisfied the rule's `for` duration. firing: type: integer description: Instances that are breaching and have fired. noData: type: integer description: Instances with no value this evaluation - no rows, an empty denominator, or a group under the sample gate. Not the same as zero. error: type: integer description: > Instances in an error state. Currently always 0: a failure that stops a rule evaluating is recorded on the rule as lastErrorReason rather than against its instances, because no instance was reached. The field exists so this set matches the alert instance status vocabulary one-to-one. total: type: integer description: Every instance of the rule, whatever its status. Provided so the common "N instances" label needs no addition client-side. observeAlertSummary: type: object description: > Project-wide alerting totals, unaffected by any filter the caller has applied elsewhere. required: - ruleTotals - instanceTotals properties: ruleTotals: $ref: "#/components/schemas/observeAlertRuleTotals" instanceTotals: $ref: "#/components/schemas/observeAlertInstanceTotals" lastEvaluatedMs: type: integer format: int64 description: > The most recent evaluation attempt across the project's rules. Absent when no rule has ever been attempted - which is the one thing the counts alone cannot say, because zero alerts because nothing is wrong looks exactly like zero alerts because nothing is running. observeAlertRuleTotals: type: object description: > How many of the project's alert rules sit in each status. Every field is present, zero included, so a client can render the set without checking which keys exist. required: - active - paused - unhealthy - total properties: active: type: integer description: Rules the evaluation runner picks up. paused: type: integer description: Rules that exist but are not evaluated. unhealthy: type: integer description: > Rules whose last evaluation attempt failed. Counted separately from active and paused rather than alongside them, because health is a second axis and not a third status: an unhealthy rule is also an active one, and adding the three together would double-count it. total: type: integer description: Every rule in the project, whatever its status. observeAlertContactPoint: type: object required: - id - name - integrations - createdMs - updatedMs properties: id: type: string description: |- Alert contact point ID (format `acp-`). name: type: string description: type: string integrations: type: array maxItems: 100 items: $ref: "#/components/schemas/observeAlertContactPointIntegration" createdMs: type: integer format: int64 updatedMs: type: integer format: int64 observeAlertContactPointIntegration: type: object required: - id - type - settings - status properties: id: type: string description: |- Integration ID (format `aci-`). type: type: string enum: - email description: The delivery mechanism. Same vocabulary as an alert notification's channel. settings: type: object additionalProperties: true description: > Settings belonging to type. For email this is observeAlertContactPointIntegrationSettingsEmail and nothing else - the mail server, its credentials and the sender address belong to the deployment, not to the project. minSeverity: type: string enum: - info - warning - critical description: > Suppresses anything less severe than this level. Omit for no floor. Resolved notifications are always delivered regardless, so an integration that heard about a problem also hears that it is over. status: type: string enum: - active - paused observeAlertContactPointIntegrationReq: type: object required: - type - settings properties: id: type: string description: |- Integration ID (format `aci-`). Omit to create a new integration; supply it to keep an existing one. x-oapi-codegen-extra-tags: validate: omitempty,id=aci type: type: string enum: - email x-oapi-codegen-extra-tags: validate: required,oneof=email settings: type: object additionalProperties: true description: Settings belonging to type. For email this is observeAlertContactPointIntegrationSettingsEmail. x-oapi-codegen-extra-tags: validate: required minSeverity: type: string enum: - info - warning - critical x-oapi-codegen-extra-tags: validate: omitempty,oneof=info warning critical status: type: string enum: - active - paused x-oapi-codegen-extra-tags: validate: omitempty,oneof=active paused observeAlertContactPointIntegrationSettingsEmail: type: object description: > The settings shape for an integration of type email, carried in observeAlertContactPointIntegration settings. This schema documents and generates that shape; the settings field itself stays an open object so that adding an integration type is not a breaking change. required: - addresses properties: addresses: type: array minItems: 1 maxItems: 10 description: Where this integration delivers. The mail server, its credentials and the sender address belong to the deployment, not to the project. items: type: string format: email observeAlertContactPointCreateReq: type: object required: - name - integrations properties: name: type: string description: Name of the contact point, unique within the project. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 integrations: type: array minItems: 1 maxItems: 100 items: $ref: "#/components/schemas/observeAlertContactPointIntegrationReq" x-oapi-codegen-extra-tags: validate: required,min=1,dive observeAlertContactPointUpdateReq: type: object required: - name - integrations properties: name: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 integrations: type: array minItems: 1 maxItems: 100 items: $ref: "#/components/schemas/observeAlertContactPointIntegrationReq" x-oapi-codegen-extra-tags: validate: required,min=1,dive observeAlertRuleType: type: object required: - ruleType - label - measures - available - dimensions properties: ruleType: type: string enum: - login_success_rate description: Identifies the type; this is what a rule of this type stores in ruleType. label: type: string description: Human-readable name of the type, for the type picker. measures: type: string description: What the type measures, as a short phrase (e.g. "completed logins / engaged logins"). available: type: boolean description: Whether this project has the data this type reads. Rules of an unavailable type cannot be saved. dimensions: type: array maxItems: 100 description: Keys a rule of this type can be grouped by for this project. Empty when available is false. items: $ref: "#/components/schemas/observeAlertRuleTypeDimension" observeAlertRuleTypeDimension: type: object required: - key - name properties: key: type: string description: What a rule stores in groupBy, and what comes back as a label key on its instances. name: type: string description: Display name for the grouping picker. observeAlertInstance: type: object required: - id - alertRuleID - alertRuleName - labelSetHash - hasOverride - status - createdMs - updatedMs properties: id: type: string description: |- Alert instance ID (format `ain-`). alertRuleID: type: string description: |- Alert rule ID (format `aru-`). alertRuleName: type: string description: > Name of the rule this alert belongs to, resolved from alertRuleID so an alert can be displayed without a second request. Display-only - requests still reference the rule by alertRuleID. labelSetHash: type: string labels: type: object additionalProperties: type: string currentValue: type: number format: double thresholdValue: type: number format: double hasOverride: type: boolean description: > Whether this alert is judged by one of its rule's overrides rather than by the rule's own values, as of the rule's current configuration. firstBreachedMs: type: integer format: int64 lastEvaluatedMs: type: integer format: int64 lastStatusChangeMs: type: integer format: int64 lastNotificationMs: type: integer format: int64 errorMessage: type: string severity: type: string enum: - info - warning - critical description: > The severity band matched at the last evaluation, absent when none matched. Status says whether the instance is firing, level says how badly, and the two move independently. The level is deliberately not part of labelSetHash - an identity that moved with the level would fork one incident into two. highWaterSeverity: type: string enum: - info - warning - critical description: > The most severe level this firing episode has already notified at, reset when the instance returns to normal. It is why a de-escalation is silent and why a re-escalation below this mark does not mail again: an instance notifies once per level per episode, and only ever as things get worse. noDataReason: type: string enum: - no_data - division_by_zero - guard_not_met - too_many_instances - rule_changed - dimension_not_available - series_not_available description: > Why this instance has no value, absent when it has one. The first three come from the rule type - no rows at all, an empty denominator, or a group under the sample gate - and the rest from the framework: the rule produced more groups than maxInstances, its grouping was edited, a dimension it groups by is gone from the project, or the series it reads is no longer available for the project. Missing, zero and errored stay three distinct things, so a group with no logins never reads as a 0% success rate. createdMs: type: integer format: int64 updatedMs: type: integer format: int64 previousStatus: type: string enum: - normal - pending - firing - no_data - error status: type: string enum: - normal - pending - firing - no_data - error observeAlertEvaluation: type: object required: - id - alertRuleID - alertInstanceID - status - windowFromMs - windowToMs - evaluatedMs - createdMs properties: id: type: string description: |- Alert evaluation ID (format `aev-`). alertRuleID: type: string description: |- Alert rule ID (format `aru-`). alertInstanceID: type: string description: |- Alert instance ID (format `ain-`). labels: type: object additionalProperties: type: string description: > The label set of the alert instance this row is about, resolved from alertInstanceID so the history can name the alert the way the alert list does. Absent for the ungrouped alert of a rule with no groupBy, which has no labels. status: type: string enum: - normal - pending - firing - no_data - error description: The instance's status as of this evaluation. value: type: number format: double description: The computed value this evaluation produced, absent when there was none - no_data is not zero. thresholdValue: type: number format: double description: The threshold the value was compared against, absent when no band applied. message: type: string windowFromMs: type: integer format: int64 description: Start of the data window this evaluation read, in milliseconds since epoch. windowToMs: type: integer format: int64 description: End of the data window this evaluation read, in milliseconds since epoch. evaluatedMs: type: integer format: int64 createdMs: type: integer format: int64 observeAlertTransition: type: object required: - id - alertRuleID - alertInstanceID - toStatus - reason - notified - evaluatedMs - createdMs properties: id: type: string description: |- Alert transition ID (format `atr-`). alertRuleID: type: string description: |- Alert rule ID (format `aru-`). alertInstanceID: type: string description: |- Alert instance ID (format `ain-`). labels: type: object additionalProperties: type: string description: > The label set of the alert instance this row is about, resolved from alertInstanceID so the history can name the alert the way the alert list does. Absent for the ungrouped alert of a rule with no groupBy, which has no labels. fromStatus: type: string enum: - normal - pending - firing - no_data - error toStatus: type: string enum: - normal - pending - firing - no_data - error fromSeverity: type: string enum: - info - warning - critical description: The severity band before this transition, absent when none matched. toSeverity: type: string enum: - info - warning - critical description: > The severity band after this transition, absent when none matched. A transition that changes only the level and not the status is still recorded, which is what lets the history show band flapping the inbox never saw. value: type: number format: double thresholdValue: type: number format: double sampleSize: type: integer format: int64 reason: type: string enum: - breach - breach_cleared - for_satisfied - escalation - de_escalation - recovery - no_data - data_returned - error - too_many_instances - rule_changed - division_by_zero - guard_not_met - dimension_not_available - series_not_available description: > The machine code for why this transition happened. recovery marks a firing instance going quiet and only that, so a pending instance that stops breaching is breach_cleared rather than a recovery that never fired. A transition into no_data carries the instance's noDataReason here instead, so why there was no value survives from the computation into the history - which is why the last four values below overlap that vocabulary. message: type: string notified: type: boolean evaluatedMs: type: integer format: int64 createdMs: type: integer format: int64 observeAlertInstanceStatistics: type: object description: > One alert instance's history over a requested window, in the two shapes the statistics panel draws: an hourly-bucketed evaluation series for the value chart, and the status timeline as merged phases plus per-status totals. The series carries only the hours that have evaluations; the phases jointly cover the window from the first known status to the earlier of the window's end and now. required: - series - phases - totals properties: series: type: array maxItems: 2500 items: $ref: "#/components/schemas/observeAlertEvaluationBucket" phases: type: array maxItems: 10000 items: $ref: "#/components/schemas/observeAlertStatusPhase" totals: $ref: "#/components/schemas/observeAlertStatusTotals" thresholdValue: type: number format: double description: The instance's current threshold, for the chart's reference line. Absent when no band applies. observeAlertEvaluationBucket: type: object description: > One hour of an instance's evaluations, aggregated. min/avg/max are computed over the evaluations that produced a value; an hour whose evaluations were all no_data carries counts but no values, which is a different statement from zero and the true one. required: - bucketStartMs - evaluationCount - normalCount - pendingCount - firingCount - noDataCount - errorCount properties: bucketStartMs: type: integer format: int64 description: Start of the hour bucket, in milliseconds since epoch (UTC hour boundaries). minValue: type: number format: double avgValue: type: number format: double maxValue: type: number format: double thresholdValue: type: number format: double description: The threshold in effect during this hour - the largest one, if it changed mid-hour. evaluationCount: type: integer description: Every evaluation in this hour, whatever its status. normalCount: type: integer pendingCount: type: integer firingCount: type: integer noDataCount: type: integer errorCount: type: integer observeAlertStatusPhase: type: object description: > One contiguous stretch of the timeline in a single status. Phases are merged - a severity-only transition does not split one - and clamped to the requested window, so they abut without gaps from the first known status to the earlier of the window's end and now. required: - fromMs - toMs - status properties: fromMs: type: integer format: int64 toMs: type: integer format: int64 status: type: string enum: - normal - pending - firing - no_data - error severity: type: string enum: - info - warning - critical description: The severity band when the phase began, absent when none matched. observeAlertStatusTotals: type: object description: > How long the instance spent in each status within the window, and how often it fired. Every field is present, zero included, and the durations add up to the covered part of the window - the stretch before the instance existed, or after now, is in none of them. required: - normalMs - pendingMs - firingMs - noDataMs - errorMs - firingCount properties: normalMs: type: integer format: int64 pendingMs: type: integer format: int64 firingMs: type: integer format: int64 noDataMs: type: integer format: int64 errorMs: type: integer format: int64 firingCount: type: integer description: How many separate firing phases the window contains. observeAlertNotification: type: object required: - id - alertRuleID - alertInstanceID - transition - channel - target - status - createdMs - updatedMs properties: id: type: string description: |- Alert notification ID (format `ano-`). alertRuleID: type: string description: |- Alert rule ID (format `aru-`). alertInstanceID: type: string description: |- Alert instance ID (format `ain-`). labels: type: object additionalProperties: type: string description: > The label set of the alert instance this row is about, resolved from alertInstanceID so the history can name the alert the way the alert list does. Absent for the ungrouped alert of a rule with no groupBy, which has no labels. transition: type: string enum: - firing - resolved - no_data - error channel: type: string enum: - email target: type: string description: Where this delivery went - an address, a URL or a routing key, depending on the integration. dedupeKey: type: string errorMessage: type: string sentMs: type: integer format: int64 status: type: string enum: - pending - sent - failed createdMs: type: integer format: int64 updatedMs: type: integer format: int64 observeExperimentVariant: type: object required: - id - value properties: id: type: string description: |- ID of the variant (format `exv-`). value: type: string description: Variant value (the tracked tag value, e.g. "blue"). observeExperiment: type: object required: - id - key - variants - createdMs properties: id: type: string description: |- ID of the experiment (format `exp-`). key: type: string description: Experiment key (the tracking tag key, e.g. "experiment_button_color"). variants: type: array items: $ref: "#/components/schemas/observeExperimentVariant" createdMs: type: integer format: int64 description: Creation time in milliseconds since epoch. observeExperimentRun: type: object required: - id - experimentID - name - startMs - variantIDs - timeSeriesDefinitionIDs - createdMs - updatedMs properties: id: type: string description: |- ID of the experiment run (format `exr-`). experimentID: type: string description: |- ID of the experiment (format `exp-`). name: type: string description: type: string startMs: type: integer format: int64 endMs: type: integer format: int64 variantIDs: type: array items: type: string timeSeriesDefinitionIDs: type: array items: type: string description: |- Time-series definition IDs (format `tsd-`). groups: type: array description: A/B evaluation arms (control vs treatment). Absent for breakdown-only runs. items: $ref: "#/components/schemas/observeExperimentRunGroup" createdMs: type: integer format: int64 updatedMs: type: integer format: int64 observeTimeSeriesDefinition: type: object description: A time-series definition available to the project. required: - definitionID - name - customTagsSupport properties: definitionID: type: string description: |- Time-series definition ID (format `tsd-`). name: type: string description: Human-readable definition name. customTagsSupport: type: boolean description: > Whether this series supports per-series custom tags. observeTimeSeriesPrecalculationConfig: type: object required: - mode - definitions properties: mode: type: string enum: - auto-stats-based - auto-config-based - manual definitions: type: array items: $ref: "#/components/schemas/observeTimeSeriesPrecalculationDefinition" observeTimeSeriesPrecalculationDefinition: type: object required: - definitionID - name - hourlyMaxLagMinutes - dailyMaxLagMinutes - monthlyMaxLagMinutes - customTags properties: definitionID: type: string description: |- Time-series definition ID (format `tsd-`). name: type: string hourlyMaxLagMinutes: type: integer minimum: 0 dailyMaxLagMinutes: type: integer minimum: 0 monthlyMaxLagMinutes: type: integer minimum: 0 customTags: type: array maxItems: 6 description: Per-series custom tag keys (map to the customTag1..6 dimensions). Ordered, at most 6. items: type: string columnGuide: description: Current column catalog used by the export picker. allOf: - $ref: "#/components/schemas/observeTimeSeriesColumnGuide" observeTimeSeriesPrecalculationConfigUpdateReq: type: object required: - mode properties: mode: type: string enum: - auto-stats-based - auto-config-based - manual x-oapi-codegen-extra-tags: validate: required,oneof=auto-stats-based auto-config-based manual definitions: type: array description: > Per-definition maxLag and custom-tag settings to upsert. Definitions not listed keep their current settings; omit the field to update only the mode. items: $ref: "#/components/schemas/observeTimeSeriesPrecalculationDefinitionUpdate" x-oapi-codegen-extra-tags: validate: omitempty,dive observeTimeSeriesPrecalculationDefinitionUpdate: type: object required: - definitionID - hourlyMaxLagMinutes - dailyMaxLagMinutes - monthlyMaxLagMinutes properties: definitionID: type: string description: |- Time-series definition ID (format `tsd-`). x-oapi-codegen-extra-tags: validate: required,id=tsd hourlyMaxLagMinutes: type: integer minimum: 0 x-oapi-codegen-extra-tags: validate: min=0 dailyMaxLagMinutes: type: integer minimum: 0 x-oapi-codegen-extra-tags: validate: min=0 monthlyMaxLagMinutes: type: integer minimum: 0 x-oapi-codegen-extra-tags: validate: min=0 customTags: type: array maxItems: 6 description: > Per-series custom tag keys (map to the customTag1..6 dimensions). Ordered; at most 6, unique, names limited to letters/digits/'_'/'-'. Only allowed for series whose definition has customTagsSupport=true. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=6,unique,dive,customTagName observeTimeSeriesPrecalculationScheduleRsp: type: object required: - jobsScheduled properties: jobsScheduled: type: integer minimum: 0 observeTimeSeriesPrecalculationManualScheduleReq: type: object required: - definitionIDs - timeInterval - fromMs - toMs properties: definitionIDs: type: array description: |- Time-series definition IDs to recompute (format `tsd-`). items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,dive,id=tsd timeInterval: type: string enum: - hourly - daily - monthly - total x-oapi-codegen-extra-tags: validate: required,oneof=hourly daily monthly total fromMs: type: integer format: int64 minimum: 0 x-oapi-codegen-extra-tags: validate: required,min=0 toMs: type: integer format: int64 minimum: 0 x-oapi-codegen-extra-tags: validate: required,min=0 observeTimeSeriesPrecalculationJobSearchReq: type: object properties: jobIDs: type: array description: |- Precalculation job IDs to fetch (format `tpj-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=tpj definitionIDs: type: array description: |- Time-series definition IDs to include (format `tsd-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=tsd statuses: type: array description: Job statuses to include. items: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJobStatus" x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,oneof=pending running completed failed scheduledAfterMs: type: integer format: int64 description: Inclusive lower bound on job scheduled time in milliseconds since epoch. x-oapi-codegen-extra-tags: validate: omitempty,min=0 scheduledBeforeMs: type: integer format: int64 description: Exclusive upper bound on job scheduled time in milliseconds since epoch. x-oapi-codegen-extra-tags: validate: omitempty,min=0 limit: type: integer description: Maximum number of jobs to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeTimeSeriesPrecalculationJobSearchRsp: type: object required: - jobs properties: jobs: type: array description: Matching jobs in descending scheduled time order, capped at `limit`. items: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJob" observeTimeSeriesPrecalculationJob: type: object required: - id - definitionID - name - timeInterval - jobType - status - windowFromMs - windowToMs - scheduledMs - attempts properties: id: type: string description: |- Precalculation job ID (format `tpj-`). definitionID: type: string description: |- Time-series definition ID (format `tsd-`). name: type: string timeInterval: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJobTimeInterval" jobType: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJobType" status: $ref: "#/components/schemas/observeTimeSeriesPrecalculationJobStatus" windowFromMs: type: integer format: int64 windowToMs: type: integer format: int64 scheduledMs: type: integer format: int64 startedMs: type: integer format: int64 completedMs: type: integer format: int64 attempts: type: integer error: type: string observeTimeSeriesPrecalculationJobTimeInterval: type: string enum: - hourly - daily - monthly - total observeTimeSeriesPrecalculationJobType: type: string enum: - live - consistency - manual - experiment observeTimeSeriesPrecalculationJobStatus: type: string enum: - pending - running - completed - failed observeTimeSeriesPrecalculationJobCounts: type: object required: - pending - running - completed - failed properties: pending: type: integer minimum: 0 running: type: integer minimum: 0 completed: type: integer minimum: 0 failed: type: integer minimum: 0 integrationStatsGetRsp: type: object required: - flows - subFlows - otherErrors - created - updated properties: flows: type: object additionalProperties: $ref: "#/components/schemas/flowTypeStats" description: Per-flow-type raw time-series stats. subFlows: type: object additionalProperties: $ref: "#/components/schemas/subFlowTypeStats" description: Per-subflow-type raw time-series stats. otherErrors: type: array items: $ref: "#/components/schemas/otherClassificationErrorStats" description: >- Classification errors of the last 24 hours whose sub-type names no flow or subflow type (scope-level failures such as "tree", "parallel" or "flow_enriched"), ordered by count descending. created: type: string format: date-time updated: type: string format: date-time flowTypeStats: type: object required: - enabled - errorCount24h - warnCount24h properties: enabled: type: boolean description: Whether the flow is currently enabled for time-series analytics. errorCount24h: type: integer format: int64 description: Classification errors (severity error) in the last 24 hours. warnCount24h: type: integer format: int64 description: Classification warnings (severity warn) in the last 24 hours. flowTypeDefinition: type: object required: - name - label - description - segmentCode - isGlobal properties: name: type: string description: Unique flow type name (e.g. login, signup, custom-checkout) label: type: string description: Human-readable label description: type: string description: Optional description segmentCode: type: string description: |- Short code identifying this flow type inside flow long paths (`f_`) isGlobal: type: boolean description: Whether this is a built-in definition shared by all projects subFlowTypeStats: type: object required: - enabled - errorCount24h - warnCount24h properties: enabled: type: boolean description: Whether the subflow is currently enabled for time-series analytics. errorCount24h: type: integer format: int64 description: Classification errors (severity error) in the last 24 hours. warnCount24h: type: integer format: int64 description: Classification warnings (severity warn) in the last 24 hours. otherClassificationErrorStats: type: object required: - type - subType - errorCount24h - warnCount24h properties: type: type: string enum: - flow - sub_flow subType: type: string description: Classification error sub-type (e.g. tree, parallel, flow_enriched). errorCount24h: type: integer format: int64 description: Classification errors (severity error) in the last 24 hours. warnCount24h: type: integer format: int64 description: Classification warnings (severity warn) in the last 24 hours. observeMdsEntry: type: object description: A single authenticator entry from a FIDO Metadata Service (MDS) BLOB. required: - identifier - identifierType - name - protocolFamily - latestStatus - metadataStatement - statusReports - blobNo properties: identifier: type: string description: Canonical key for this entry (aaguid, aaid, or a u2f cert-key-id derived value). identifierType: type: string description: Which identifier family keys this entry. enum: - aaguid - aaid - u2f aaguid: type: string description: Authenticator AAGUID (present for FIDO2 authenticators). aaid: type: string description: Authenticator AAID (present for FIDO UAF authenticators). certKeyIds: type: array description: Attestation certificate key identifiers (present for FIDO U2F authenticators). items: type: string name: type: string description: Human-readable authenticator description, e.g. "YubiKey 5 Series with NFC". protocolFamily: type: string description: FIDO protocol family, e.g. fido2, u2f or uaf. latestStatus: type: string description: Most recent certification status, e.g. FIDO_CERTIFIED_L1 or NOT_FIDO_CERTIFIED. timeOfLastStatusChange: type: string description: Date of the last certification status change (YYYY-MM-DD). metadataStatement: type: object additionalProperties: true description: Full FIDO MDS metadata statement JSON (icons extracted into the icon fields). statusReports: type: array description: Full FIDO MDS certification status report history. items: type: object additionalProperties: true icon: type: string description: Light-mode authenticator icon as a base64 PNG data URI. iconDark: type: string description: Dark-mode authenticator icon as a base64 PNG data URI. blobNo: type: integer description: Sequence number of the source MDS BLOB this entry was imported from. observePasskeyAaguid: type: object description: >- A single passkey/platform-authenticator entry from the community passkey-authenticator-aaguids catalog, keyed by AAGUID. required: - aaguid - name - passwordManager properties: aaguid: type: string description: Authenticator AAGUID (UUID format). name: type: string description: Human-readable authenticator name, e.g. "Apple iCloud Keychain". iconLight: type: string description: Light-mode authenticator icon as an SVG data URI. iconDark: type: string description: Dark-mode authenticator icon as an SVG data URI. passwordManager: type: boolean description: Whether this authenticator is a password manager (curated by Corbado). observeIDList: type: object required: - id - type - flowIDs - count - createdMs properties: id: type: string description: |- ID-list handle (format `idl-`). type: type: string description: Identifier family stored in this list. For this endpoint, the value is always flowID. enum: - flowID flowIDs: type: array description: |- Stored flow IDs (format `flw-`). items: type: string count: type: integer description: Number of stored flow IDs. createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 observeFlowTagSearchReq: type: object required: - flowIDs properties: flowIDs: type: array description: |- Flow IDs to fetch tags for (format `flw-`). items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=500,dive,id=flw keys: type: array description: Optional tag keys to include. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=100,dive,min=1,max=100 limit: type: integer description: Maximum number of tags to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeIDListCreateReq: type: object required: - type - flowIDs properties: type: type: string description: Identifier family to store. Currently only flowID is accepted. x-oapi-codegen-extra-tags: validate: required,oneof=flowID flowIDs: type: array description: |- Flow IDs to store (format `flw-`). items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=10000,dive,id=flw observeIDListCreateRsp: type: object required: - id - type - count - createdMs properties: id: type: string description: |- ID-list handle (format `idl-`). type: type: string description: Identifier family stored in this list. Currently always flowID. count: type: integer description: Number of stored flow IDs after deduplication. createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 observeFlowTag: type: object required: - id - flowID - sessionID - key - value - createdMs properties: id: type: string description: |- Flow tag ID (format `flt-`). flowID: type: string description: |- Parent flow ID (format `flw-`). sessionID: type: string description: Session ID (UUID format). key: type: string description: Tag key. value: type: string description: Tag value. createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 observePasskeyCohortReq: type: object required: - fromMs - toMs - maxGroupSize properties: authenticatorClass: type: string enum: - security-key - synced-passkey - device-bound-passkey - unknown description: Optional credential-class filter, applied after the user limit. Returns matching holders and credentials from the capped user cohort; matching holders outside that cohort are omitted. Activity includes only subflows linked to those credentials; unlinked attempts and enrollment-flow summaries are excluded. Omit for the existing all-credentials user cohort. x-oapi-codegen-extra-tags: validate: omitempty,oneof=security-key synced-passkey device-bound-passkey unknown fromMs: type: integer format: int64 description: Cohort lower bound — users created at or after this epoch-ms timestamp toMs: type: integer format: int64 description: Cohort upper bound — users created strictly before this epoch-ms timestamp maxGroupSize: type: integer description: Maximum number of users to return (newest first) x-oapi-codegen-extra-tags: validate: required,min=1,max=50000 observePasskeyCohortSubflowSummary: type: object required: - total - completed - errored properties: total: type: integer description: Number of subflows of this type for the user completed: type: integer description: Number that completed successfully errored: type: integer description: Number that had at least one error firstCompletedMs: type: - integer - "null" format: int64 x-omitempty: false description: Epoch-ms of the user's first successful subflow of this type (activation marker for login) observePasskeyCohortEnrollmentFlowSummary: type: object required: - complete - skipped - invisible properties: complete: type: integer description: Number of the user's enrollment flows that completed (a passkey was created) skipped: type: integer description: > Number of enrollment flows the user was offered and explicitly skipped (explicitOutcome=skipped). Separates "offered but declined self-registration" from "never eligible". invisible: type: integer description: Number of enrollment flows that were denied by the system (explicitOutcome=invisible — already-enrolled or not-eligible) observePasskeyCohortPasskey: type: object required: - credentialID - dataStatus - transports - backupState - createdMs properties: type: type: string description: Credential type stored by Observe, when classified. enum: - passkey - hardware-security-key - non-discoverable-key - u2f-key authenticatorClass: type: string enum: - security-key - synced-passkey - device-bound-passkey - unknown description: Class derived from stored credential type, roaming transports and backup state. Unknown means insufficient evidence, not absence from MDS. credentialID: type: string description: base64url-encoded credential ID dataStatus: type: string description: pre-registered | full-observed | full-patched | partial-login aaguid: type: - string - "null" x-omitempty: false aaguidStatus: type: - string - "null" x-omitempty: false transports: type: array items: type: string backupState: type: boolean createdMs: type: integer format: int64 observePasskeyCohortUser: type: object required: - userID - createdMs - passkeys - passkeyLogin - passkeyEnrollment - passkeyEnrollmentFlow properties: userID: type: string externalID: type: string createdMs: type: integer format: int64 passkeys: type: array items: $ref: '#/components/schemas/observePasskeyCohortPasskey' passkeyLogin: $ref: '#/components/schemas/observePasskeyCohortSubflowSummary' passkeyEnrollment: $ref: '#/components/schemas/observePasskeyCohortSubflowSummary' passkeyEnrollmentFlow: $ref: '#/components/schemas/observePasskeyCohortEnrollmentFlowSummary' observePasskeySearchReq: type: object required: - userIDs properties: userIDs: type: array description: |- User IDs to fetch passkeys for (format `tus-`). items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=500,dive,id=tus status: type: array description: Optional passkey statuses to include. items: $ref: "#/components/schemas/observePasskeyStatus" x-oapi-codegen-extra-tags: validate: omitempty,max=2,dive,oneof=created deleted limit: type: integer description: Maximum number of passkeys to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observePasskey: type: object required: - id - userID - credentialID - transports - backupState - dataStatus - status - createdMs properties: id: type: string description: |- Passkey ID (format `tpk-`). userID: type: string description: |- User ID (format `tus-`). credentialID: type: string description: Base64-encoded credential ID. serialNumber: type: string description: YubiKey hardware serial number, when available (pre-registered keys only). type: type: string description: Derived credential type, when classified. enum: - passkey - hardware-security-key - non-discoverable-key - u2f-key discoverable: type: boolean description: Whether the credential is discoverable/resident (from credProps.rk at enrollment), when observed. attestationFormat: type: string description: Attestation statement format at enrollment (e.g. none, packed, fido-u2f, apple, android-key), when observed. backupEligible: type: boolean description: Whether the credential is backup-eligible (BE flag at enrollment), when observed. aaguid: type: string description: AAGUID, when available. aaguidStatus: $ref: "#/components/schemas/observePasskeyAaguidStatus" transports: type: array description: Transport types. items: type: string backupState: type: boolean description: Whether the passkey is backed up. dataStatus: $ref: "#/components/schemas/observePasskeyDataStatus" status: $ref: "#/components/schemas/observePasskeyStatus" createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 createdOnClientEnvID: type: string description: |- Client environment ID where the passkey was created, when available (format `tce-`). observePasskeyAaguidStatus: type: string description: AAGUID status. enum: - estimate-weak - estimate-strong - estimate-authenticator-provided - confirmed-weak - confirmed-strong - unknown observePasskeyDataStatus: type: string description: Passkey data status. enum: - full-observed - full-patched - partial-login - pre-registered observePasskeyStatus: type: string description: Passkey status. enum: - created - deleted observeClientEnvSearchReq: type: object required: - userIDs properties: userIDs: type: array description: |- User IDs to fetch client environments for (format `tus-`). items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=500,dive,id=tus type: $ref: "#/components/schemas/observeClientEnvType" limit: type: integer description: Maximum number of client environments to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeClientEnv: type: object required: - id - handle - osName - clientEnvType - createdMs properties: id: type: string description: |- Client environment container ID (format `tce-`). handle: type: string description: Client environment handle. osName: $ref: "#/components/schemas/observeClientEnvOsName" clientEnvType: $ref: "#/components/schemas/observeClientEnvType" createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 dataWeb: type: array items: $ref: "#/components/schemas/observeClientEnvDataWeb" dataApp: type: array items: $ref: "#/components/schemas/observeClientEnvDataApp" observeClientEnvOsName: type: string description: Operating system name. enum: - Windows - macOS - Linux - iOS - iPadOS - Android - ChromeOS - Other observeClientEnvType: type: string description: Client environment type. enum: - web - app observeClientEnvDataWeb: type: object required: - id - createdMs properties: id: type: string osVersion: type: string browserName: type: string browserVersion: type: string privateMode: type: boolean webdriver: type: boolean bluetoothAvailable: type: boolean conditionalMediationAvailable: type: boolean userVerifyingPlatformAuthenticatorAvailable: type: boolean conditionalGet: type: boolean conditionalCreate: type: boolean hybridTransport: type: boolean passkeyPlatformAuthenticator: type: boolean relatedOrigins: type: boolean signalAllAcceptedCredentials: type: boolean signalCurrentUserDetails: type: boolean signalUnknownCredential: type: boolean userVerifyingPlatformAuthenticator: type: boolean extensionAppid: type: boolean extensionAppidExclude: type: boolean extensionCredBlob: type: boolean extensionCredProps: type: boolean extensionCredentialProtectionPolicy: type: boolean extensionEnforceCredentialProtectionPolicy: type: boolean extensionGetCredBlob: type: boolean extensionHmacCreateSecret: type: boolean extensionLargeBlob: type: boolean extensionMinPinLength: type: boolean extensionPayment: type: boolean extensionPrf: type: boolean maxTouchPoints: type: integer description: >- navigator.maxTouchPoints as reported by the client. 0 on devices without a touchscreen. Absent on older data and when the client did not report it. createdMs: description: Creation time in milliseconds since epoch. type: integer format: int64 observeClientEnvDataApp: type: object required: - id - createdMs properties: id: type: string osVersion: type: string model: type: string description: Device model (e.g. "iPhone15,3", "Pixel 8"). brand: type: string description: Device manufacturer/brand (e.g. "Apple", "Google"). appName: type: string description: Host application name (e.g. "Acme Banking"). appVersion: type: string description: Host application version (e.g. "3.2.1"). deviceOwnerAuth: type: string enum: - none - code - bio-face - bio-touch - bio-strong - bio-weak - bio description: Device owner authentication / screen-lock method. isBluetoothAvailable: type: boolean description: Whether Bluetooth is available on the device. androidGooglePlayServicesVersion: type: string description: Google Play Services version (Android only; null on iOS). locale: type: string description: Device locale (BCP-47, e.g. "en-US"). screen: $ref: "#/components/schemas/observeAppScreen" createdMs: description: Creation time in milliseconds since epoch type: integer format: int64 observeEventSearchReq: type: object required: - flowIDs properties: subFlowIDs: type: array description: Optional exact subflow owners, intersected with flowIDs. Include descendant IDs explicitly for a subtree. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=sfl flowIDs: type: array description: |- Flow IDs to fetch events for (format `flw-`). items: type: string x-oapi-codegen-extra-tags: validate: required,min=1,max=500,dive,id=flw limit: type: integer description: Maximum number of events to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeEventSearchRsp: type: object required: - events - totalCount properties: events: type: array description: SDK tracking events for the selected flows, oldest first, capped at `limit`. items: $ref: "#/components/schemas/observeEventSearchEntry" totalCount: type: integer description: Total number of matching events regardless of limit observeEventSearchEntry: type: object required: - id - flowID - sessionID - batchID - type - name - data - createdMs properties: subFlowID: type: string description: Exact owning subflow (sfl-...). Absent for directly flow-owned events. id: type: string description: |- Event ID (format `tev-`) flowID: type: string description: |- Flow ID (format `flw-`) sessionID: type: string description: Public session UUID. batchID: type: string description: |- Tracking event batch ID (format `teb-`). type: $ref: "#/components/schemas/observeEventType" name: type: string description: Name of the tracking event data: type: object description: Additional event data additionalProperties: true metadata: $ref: "#/components/schemas/observeEventSearchEntryMetadata" createdMs: description: Event creation time in milliseconds since epoch (client-provided) type: integer format: int64 observeEventSearchEntryMetadata: type: object description: Event-scoped metadata properties: trackingSourcePath: type: string description: >- Tracking source path of the event including query string, resolved from the event's ingestion batch (the path is stored once per batch) and with email addresses and phone numbers redacted to "*email*" / "*phone*". observeUIPatternSearchReq: type: object properties: sessionIDs: type: array description: Public session UUIDs to fetch UI patterns for. Mutually exclusive with other selectors. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,uuid subFlowIDs: type: array description: |- Subflow IDs to fetch UI patterns for (format `sfl-`). Mutually exclusive with other selectors. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=sfl types: type: array description: Optional UI pattern types to include. items: $ref: "#/components/schemas/observeUIPatternType" x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,oneof=input-click input-manual input-autofill-unprotected input-autofill-protected-1 input-autofill-protected-2 overlay-generic limit: type: integer description: Maximum number of UI patterns to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeUIPatternSearchRsp: type: object required: - uiPatterns properties: uiPatterns: type: array description: Matching UI patterns in stable timeline order, capped at `limit`. items: $ref: "#/components/schemas/observeUIPatternSearchEntry" observeUIPatternSearchEntry: type: object required: - id - sessionID - type - startMs - endMs properties: id: type: string description: |- UI pattern ID (format `uip-`). sessionID: type: string description: Public session UUID. subFlowID: type: string description: |- Parent subflow ID (format `sfl-`). captureVersion: type: integer format: int32 target: type: string enum: - input-identifier - input-password - input-otp - input-data - window - unknown initiator: type: string enum: - input-identifier - input-password - input-otp - input-data - passkey-button - automatic - unknown subType: type: string enum: - single-stage - handoff - protected-1 - protected-2 endObserved: type: boolean description: Whether a duration-bearing pattern has an observed close; absent when not applicable. effects: type: array description: Observed field effects; absent on legacy patterns. items: type: string enum: - identifier-fill - password-fill - otp-fill - data-fill - identifier-modify - password-modify - otp-modify - data-modify - identifier-clear - password-clear - otp-clear - data-clear overlayPatternID: type: string description: Related separable overlay (uip ID), when evidence establishes an association. pageID: type: string flowID: type: string type: $ref: "#/components/schemas/observeUIPatternType" startMs: type: integer format: int64 description: Pattern start time in milliseconds since epoch. endMs: type: integer format: int64 description: Pattern end time in milliseconds since epoch. observeUIPatternType: type: string description: Low-level UI pattern type. enum: - input-click - input-manual - input-autofill-unprotected - input-autofill-protected-1 - input-autofill-protected-2 - overlay-generic - overlay-ceremony - overlay-ceremony-handoff - overlay-ceremony-open - input-focus - input-prefill - input-clear - input-autofill - input-autofill-protected - input-paste - window-overlay-ceremony - window-overlay-input - window-leave - window-enter - window-navigate-back observeSubFlowErrorSearchReq: type: object properties: sessionIDs: type: array description: Public session UUIDs to fetch subflow errors for. Mutually exclusive with other selectors. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,uuid subFlowIDs: type: array description: |- Subflow IDs to fetch subflow errors for (format `sfl-`). Mutually exclusive with other selectors. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=sfl flavourIDs: type: array description: |- Optional error flavour IDs to include (format `erf-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=erf limit: type: integer description: Maximum number of subflow errors to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeSubFlowErrorSearchRsp: type: object required: - subFlowErrors properties: subFlowErrors: type: array description: Matching subflow error occurrences in stable timeline order, capped at `limit`. items: $ref: "#/components/schemas/observeSubFlowErrorSearchEntry" observeSubFlowErrorSearchEntry: type: object required: - id - sessionID - subFlowID - flavourID - createdMs properties: id: type: string description: |- Subflow error occurrence ID (format `sfe-`). sessionID: type: string description: Public session UUID. subFlowID: type: string description: |- Parent subflow ID (format `sfl-`). flowID: type: string description: |- Flow the subflow belongs to (format `flw-`); absent when the subflow never attached to a flow. flavourID: type: string description: |- Raw-signature error flavour (format `erf-`). Resolve signature details and the mapped error via the error flavour list. durationMs: type: integer format: int64 description: Raw step-start to error latency in milliseconds; absent when not measurable. createdMs: type: integer format: int64 description: Occurrence time in milliseconds since epoch (the error event's timestamp). observeTrackingEventBatchSearchReq: type: object properties: sessionIDs: type: array description: Public session UUIDs to fetch tracking event batches for. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,uuid batchIDs: type: array description: |- Tracking event batch IDs to fetch (format `teb-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=teb createdAfterMs: type: integer format: int64 description: Inclusive lower bound on batch creation time in milliseconds since epoch. x-oapi-codegen-extra-tags: validate: omitempty,min=0 createdBeforeMs: type: integer format: int64 description: Exclusive upper bound on batch creation time in milliseconds since epoch. x-oapi-codegen-extra-tags: validate: omitempty,min=0 limit: type: integer description: Maximum number of batches to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeTrackingEventBatchSearchRsp: type: object required: - trackingEventBatches properties: trackingEventBatches: type: array description: Matching tracking event batches in stable timeline order, oldest first, capped at `limit`. items: $ref: "#/components/schemas/observeTrackingEventBatchSearchEntry" observeTrackingEventBatchSearchEntry: type: object required: - id - sessionID - status - createdMs properties: id: type: string description: |- Tracking event batch ID (format `teb-`). sessionID: type: string description: Public session UUID. status: $ref: "#/components/schemas/observeTrackingEventBatchStatus" createdMs: type: integer format: int64 description: Batch creation time in milliseconds since epoch. origin: type: string description: HTTP Origin header of the ingestion request, when available. transport: type: string description: Client-reported delivery transport, when available. flushReason: type: string description: Client-reported trigger that caused this flush, when available. sentMs: type: integer format: int64 description: Client-reported send time in milliseconds since epoch, when available. retryCount: type: integer format: int32 description: Number of prior failed delivery attempts reported by the client, when available. configVersion: type: string description: SDK reliability configuration version, when available. dataPolicy: type: integer format: int32 description: Data policy code (0..255) the client reported with this batch (`meta.dataPolicy`), when available. observeTrackingEventBatchStatus: type: string description: Deduplication status of a tracking event batch. enum: - clean - partial_duplicate - full_duplicate - backfilled observeTrackingEventLowSearchReq: type: object properties: sessionIDs: type: array description: Public session UUIDs to fetch low-level tracking events for. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,uuid batchIDs: type: array description: |- Tracking event batch IDs to fetch low-level tracking events for (format `teb-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=teb types: type: array description: Optional low-level tracking event types to include. items: $ref: "#/components/schemas/observeTrackingEventLowType" x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,oneof=focus blur click pointerdown pointerup keyup-escape input big-input-add big-input-paste big-input-rem input-idle input-prefill input-clear input-paste window-navigate-back window-focus window-blur visualviewport-resize visualviewport-scroll document-visibilitychange-hidden document-visibilitychange-visible pwm-1pwd-button pwm-1pwd-menu pwm-1pwd-notification pwm-lastpass pwm-bitwarden pwm-icloud-passwords page-ready createdAfterMs: type: integer format: int64 description: Inclusive lower bound on client capture time in milliseconds since epoch. x-oapi-codegen-extra-tags: validate: omitempty,min=0 createdBeforeMs: type: integer format: int64 description: Exclusive upper bound on client capture time in milliseconds since epoch. x-oapi-codegen-extra-tags: validate: omitempty,min=0 limit: type: integer description: Maximum number of low-level tracking events to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeTrackingEventLowSearchRsp: type: object required: - trackingEventLows properties: trackingEventLows: type: array description: Matching low-level tracking events in stable timeline order, oldest first, capped at `limit`. items: $ref: "#/components/schemas/observeTrackingEventLowSearchEntry" observeTrackingEventLowSearchEntry: type: object required: - id - sessionID - batchID - type - createdMs - durationMs properties: captureSeq: type: integer format: int64 minimum: 0 maximum: 4294967295 description: Unsigned per-page capture order, reserved at observation start and retained through retries. Zero or missing means unavailable. captureVersion: type: integer format: int32 clientEventID: type: string subflowStartEventId: type: string pageID: type: string sourceKind: type: string fieldRole: type: string initiator: type: string inputEffect: type: string id: type: string description: |- Low-level tracking event ID (format `tel-`). sessionID: type: string description: Public session UUID. batchID: type: string description: |- Tracking event batch ID of the ingestion request this low-level event arrived with (format `teb-`). type: $ref: "#/components/schemas/observeTrackingEventLowType" createdMs: type: integer format: int64 description: Client capture time in milliseconds since epoch, corrected against the batch send time. durationMs: type: integer format: int64 description: Duration of the low-level tracking event in milliseconds, 0 when the client reported none. observeTrackingEventLowType: type: string description: Type of a low-level tracking event. enum: - focus - blur - click - pointerdown - pointerup - keyup-escape - input - input-idle - big-input-add - big-input-paste - input-prefill - input-clear - input-paste - window-navigate-back - big-input-rem - window-focus - window-blur - visualviewport-resize - visualviewport-scroll - document-visibilitychange-hidden - document-visibilitychange-visible - pwm-1pwd-button - pwm-1pwd-menu - pwm-1pwd-notification - pwm-lastpass - pwm-bitwarden - pwm-icloud-passwords - page-ready trackingStats: type: object required: - trackingEvent - trackingSession - trackingUserReference - trackingTag - trackingDeviceInfo properties: trackingEvent: $ref: "#/components/schemas/trackingTableStats" trackingSession: $ref: "#/components/schemas/trackingTableStats" trackingUserReference: $ref: "#/components/schemas/trackingTableStats" trackingTag: $ref: "#/components/schemas/trackingTableStats" trackingDeviceInfo: $ref: "#/components/schemas/trackingTableStats" trackingTableStats: type: object required: - total - averagePerMinute - maxPerMinute properties: total: type: integer format: int64 description: Total rows ingested in the last 60 minutes. averagePerMinute: type: number format: double description: Average rows ingested per minute over the last 60 minutes. maxPerMinute: type: integer format: int64 description: Maximum rows ingested in a single minute over the last 60 minutes. observeUserSearchReq: type: object properties: userIDs: type: array description: |- List of exact user IDs to search for (format `tus-`). Mutually exclusive with other search fields. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=1000,dive,id=tus userIDPattern: type: string description: |- User ID pattern for prefix search (format `tus-`%, e.g., "tus-123%" matches all user IDs starting with tus-123...). Mutually exclusive with other search fields. x-oapi-codegen-extra-tags: validate: omitempty,min=6,max=24 externalIDs: type: array description: List of exact external IDs to search for. Mutually exclusive with other search fields. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=1000,dive,min=1,max=100 externalIDPattern: type: string description: External ID pattern for prefix search, ending with '%' (e.g., "abc%" matches all external IDs starting with abc). Mutually exclusive with other search fields. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=100 flowIDs: type: array description: List of flow IDs to search for (e.g., "flw-123"). Returns the users owning those flows. Mutually exclusive with other search fields. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=1000,dive,min=5,max=50 serialNumbers: type: array description: List of exact YubiKey serial numbers. Returns the users owning a passkey with a matching serial number (pre-registered keys). Mutually exclusive with other search fields. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=1000,dive,min=1,max=32 page: type: integer description: Page number for pagination (1-based). Defaults to 1. default: 1 minimum: 1 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=1000 pageSize: type: integer description: Number of items per page. Defaults to 25, maximum 1000. default: 25 minimum: 1 maximum: 1000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=1000 observeUser: type: object required: - id - externalID - status - createdMs properties: id: type: string description: |- User ID (format `tus-`) externalID: type: string description: Customer-provided external ID status: type: string description: User status enum: - confirmed - temporary createdMs: description: Creation time in milliseconds since epoch type: integer format: int64 observeClassificationRun: type: object required: - status properties: sessions: type: array description: Per-session outcomes, including expanded linked sessions and unavailable requested UUIDs. items: $ref: "#/components/schemas/observeClassificationSessionResult" status: type: string description: Status of the classification run enum: - inProgress - completed - failed observeClassificationError: type: object required: - sessionID - type - severity - subType - code - createdMs properties: sessionID: type: string description: Session ID (UUID format) x-oapi-codegen-extra-tags: validate: required,uuid type: type: string description: Classification error scope enum: - flow - sub_flow severity: type: string description: | Severity of the issue. `error` means the surrounding subflow/flow could not be produced (hard fail). `warn` means a non-fatal enrichment failure — the subflow was still emitted alongside this row. enum: - error - warn subType: type: string description: Flow type or subflow type name (e.g. passkey_login, provide_identifier) code: type: string description: Machine-readable error code (e.g. missingSpecType) createdMs: description: Error creation time in milliseconds since epoch type: integer format: int64 observeDataDeletionJob: type: object required: - id - externalID - created - updated - status properties: id: type: string description: ID of the data deletion job externalID: type: string description: External user ID created: $ref: "#/components/schemas/unixMilliTimestamp" updated: $ref: "#/components/schemas/unixMilliTimestamp" status: type: string description: Current status of the data deletion job enum: - pending - processing - completed observeDataExport: type: object additionalProperties: type: array items: type: object additionalProperties: true observeTableExportList: type: object required: - tableExport properties: tableExport: type: array items: $ref: "#/components/schemas/observeTableExportItem" observeTableExportItem: type: object required: - table - date - size - created - createdMs - files properties: table: type: string date: type: string example: "2026-05-26" size: type: integer format: int64 created: type: string example: "2026-05-27 03:14:15" createdMs: $ref: "#/components/schemas/unixMilliTimestamp" files: type: array items: $ref: "#/components/schemas/observeTableExportFile" observeTableExportFile: type: object required: - filename - size - checksum - created - createdMs properties: filename: type: string example: "pro-123/ob_tracking_event/2026-05-26-00000.parquet" size: type: integer format: int64 checksum: type: string created: type: string example: "2026-05-27 03:14:15" createdMs: $ref: "#/components/schemas/unixMilliTimestamp" observeTableExportDownloadLink: type: object required: - link properties: link: type: string unixMilliTimestamp: type: integer format: int64 description: Unix timestamp in milliseconds elapsed since January 1, 1970, 00:00:00 UTC example: 1752738240000 observeLow: required: - lowType - ts properties: captureSeq: type: integer format: int64 minimum: 0 maximum: 4294967295 description: Unsigned per-page capture order, reserved at observation start and retained through retries. Zero or missing means unavailable. x-oapi-codegen-extra-tags: validate: omitempty,min=0,max=4294967295 captureVersion: type: integer format: int32 description: Capture contract version. Missing means legacy v0. x-oapi-codegen-extra-tags: validate: omitempty,min=0,max=255 pageId: type: string description: Document capture UUID, retained through retries. x-oapi-codegen-extra-tags: validate: omitempty,uuid initiator: type: string description: Semantic initiating control when observed; unknown otherwise. x-oapi-codegen-extra-tags: validate: omitempty,max=32 id: type: string description: Immutable client low-event UUID for retry deduplication. x-oapi-codegen-extra-tags: validate: omitempty,uuid subflowStartEventId: type: string description: Client UUID of the owning subflow_started, scoped to this project and session. x-oapi-codegen-extra-tags: validate: omitempty,uuid sourceKind: type: string description: Capture source category. Unknown future values are stored as NULL. x-oapi-codegen-extra-tags: validate: omitempty,max=32 fieldRole: type: string description: Logical field role (password, identifier, otp, data). Unknown values are stored as NULL. x-oapi-codegen-extra-tags: validate: omitempty,max=32 inputEffect: type: string description: Observed value effect (fill, modify, clear); unknown values are ignored. x-oapi-codegen-extra-tags: validate: omitempty,max=32 lowType: type: string ts: type: integer format: int64 durationMs: type: integer format: int64 fieldType: type: string description: >- Semantic field the low relates to, named by subflow-type vocabulary (e.g. provide-identifier, password-login). Native SDK extension; free-form on the wire — the backend stores known values and drops unknown ones. x-oapi-codegen-extra-tags: validate: omitempty,max=64 actor: type: string description: >- Who caused the observed effect, when known (password-manager, app). Native SDK extension; free-form on the wire — the backend stores known values and drops unknown ones. x-oapi-codegen-extra-tags: validate: omitempty,max=64 observeTelemetry: type: object description: | A single diagnostic telemetry entry (a level + free-form message) tied to the batch's session. Used for SDK/integration-side diagnostics; it is never classified as an auth-flow event. required: - level - message - ts properties: id: type: string description: Client-generated idempotency id (uuidv7). Lets safe resends (retry/beacon/outbox) dedupe server-side. x-oapi-codegen-extra-tags: validate: omitempty,uuid level: type: string description: Severity of the telemetry message. enum: - info - error x-oapi-codegen-extra-tags: validate: required,oneof=info error message: type: string description: Free-form diagnostic message. Truncated server-side. Must not contain credentials or PII. x-oapi-codegen-extra-tags: validate: required,max=1000 ts: type: integer format: int64 description: Client capture time (unix ms). Corrected against batch send time like low events. x-oapi-codegen-extra-tags: validate: required observeEventMetaSession: type: object required: - sent - transport properties: sent: type: integer format: int64 transport: type: string description: Transport used by the client to send events flushReason: type: string description: >- What triggered the flush this batch was sent in (timer, backoff, recovery, flow-finished, telemetry, visibility-change, pagehide, low-event-teardown, destroy, manual). Deliberately not an enum: a newer SDK must never have its batch rejected for reporting a trigger this backend does not know yet. Absent for legacy SDKs. x-oapi-codegen-extra-tags: validate: omitempty,max=32 configVersion: type: string description: Version of the SDK reliability configuration the client was running when it captured this batch. Absent for legacy SDKs or when no config was cached yet. x-oapi-codegen-extra-tags: validate: omitempty,max=64 retryCount: type: integer format: int32 description: Number of prior failed delivery attempts for this batch; absent on the first attempt. x-oapi-codegen-extra-tags: validate: omitempty,min=0 dataPolicy: type: integer format: int32 description: | Project-scoped data policy code (0..255) the tracker is running under, as set through the SDK's `setDataPolicy(code)` / `init({ dataPolicy })`. Sent on every batch once known, including an explicit 0; absent for legacy SDKs and before the first call. Codes are opaque project-scoped selectors of the project's data policies (0 = default). Stored as-is on the batch and copied onto the session (last write wins); never validated at ingestion (unknown codes are reported by classification). x-oapi-codegen-extra-tags: validate: omitempty,min=0,max=255 observeEventMetaEvent: type: object properties: captureVersion: type: integer format: int32 description: Capture contract version. Missing means legacy v0. x-oapi-codegen-extra-tags: validate: omitempty,min=0,max=255 pageId: type: string description: Document capture UUID, retained through retries. x-oapi-codegen-extra-tags: validate: omitempty,uuid initiator: type: string description: Semantic initiating control when observed; unknown otherwise. x-oapi-codegen-extra-tags: validate: omitempty,max=32 subflowStartEventId: type: string description: Client UUID of the owning start event; preserved on each step event through retries. x-oapi-codegen-extra-tags: validate: omitempty,uuid trackingSourcePath: type: string description: >- Tracking source path of the event including query string ("where" was this event created). Web SDKs send it (page path); native app SDKs send the host-provided screen name and omit the field when no screen is set. The backend stores it ONCE PER BATCH — on the first event of the batch that reports one; later events of the batch are stored without it and resolve the batch's path on read — so an SDK may omit it on all but the first event of a batch. Email addresses and phone numbers are redacted before storage. tabId: type: string description: > Per-tab id (sessionStorage-scoped) of the tab that CREATED this event, stamped at track() time. Distinguishes tabs that share one localStorage-backed session; late-flushed events keep the tab they originated in, regardless of which page delivers them. Native app SDKs send their per-process id here on every event (the process-incarnation marker used for stream splitting and seq disambiguation). observeEventType: type: string description: Type of the tracking event enum: - predefined - custom x-oapi-codegen-extra-tags: validate: oneof=predefined custom observeEvent: type: object additionalProperties: true required: - type - name - timestamp properties: id: type: string description: Client-generated unique event ID (UUID) used for idempotent ingestion. When provided, the backend deduplicates events with the same id within the same session, so safe client retries do not create duplicates. Optional for backwards compatibility. example: "550e8400-e29b-41d4-a716-446655440000" x-oapi-codegen-extra-tags: validate: omitempty,uuid type: $ref: "#/components/schemas/observeEventType" name: type: string description: >- Name of the event. `flow_enriched` carries a user reference and/or tags and is accepted on both unauthenticated and authenticated endpoints. Its optional `data` section selects the matching flow and controls tag expansion: Explicit targeting uses `{ targetEventId: "" }` and enriches the flows that directly own that event in the same project and session, including completed flows: every flow a `flow_started` opened, the flow a `flow_finished` finished, or the flow of one of its subflow steps — never a nested flow's event and never another enrichment — so an integration can enrich a flow from the page that finished it. `flowStartedEventId` is deprecated: it remains accepted as an alias of `targetEventId` for SDKs that predate it, and both may be sent together only with the same UUID. Explicit targeting is mutually exclusive with `match`; it never falls back to temporal matching, advances flow duration, or establishes identity for unrelated later flows. Delivery order does not matter once both events are available to classification. Without an explicit target, temporal targeting uses `{ match: { flowType?: string, at?: "started" | "finished" | "during" }, expCh?: boolean, expFol?: boolean }` — defaults `flowType` login, `at` finished, `expCh`/`expFol` true. The explicit `flowType` value `*` accepts any flow type; omission retains the login default. `started` and `finished` select the nearest qualifying start or finish; `during` selects the innermost matching flow at the event time. Temporal unauthenticated enrichments require a flow started or explicitly continued in the emitting session before the enrichment and still open when it is emitted. Timestamp and sequence determine emission order; delivery time does not affect ownership. Matching has no grace period, and these references cannot identify earlier flows through late or future-reference fallback. Sequences must be non-negative. Authenticated enrichment retains a symmetric 10-second matching tolerance. `expCh` and `expFol` control tag expansion to child and following flows; user identity propagates forward independently. An unmatched enrichment has no flow association and its tags are dropped, while its reference remains available for forward propagation. The legacy alias `session_enriched` remains accepted; on the unauthenticated endpoint its `data` must remain empty for compatibility. User references on other events remain supported. enum: - flow_started - flow_finished - flow_reset - flow_decided - flow_auto_finished - auth_method_decision_started - auth_method_decision_finished - auth_decision_started - auth_decision_finished - subflow_started - subflow_step_started - subflow_step_finished - subflow_step_error - subflow_trigger - subflow_spacer - subflow_error - conversion - session_enriched - flow_enriched example: "flow_started" x-oapi-codegen-extra-tags: validate: required,oneof=flow_started flow_finished flow_reset flow_decided flow_auto_finished auth_method_decision_started auth_method_decision_finished auth_decision_started auth_decision_finished subflow_started subflow_step_started subflow_step_finished subflow_step_error subflow_trigger subflow_spacer subflow_error conversion session_enriched flow_enriched timestamp: type: integer format: int64 description: Unix timestamp of when the event was created (in milliseconds elapsed since January 1, 1970, 00:00:00 UTC) example: 1752738240000 x-oapi-codegen-extra-tags: validate: required data: type: object description: Additional event data (arbitrary JSON) additionalProperties: true meta: $ref: "#/components/schemas/observeEventMetaEvent" deviceInfo: $ref: "#/components/schemas/observeDevicesInfo" user: $ref: "#/components/schemas/observeUserReference" tags: type: object additionalProperties: type: string experiments: type: object description: > Experiment assignments active for this event, as a map of experiment key to variant value (e.g. {"button_color": "blue"}). First-class, prefix-free representation of A/B-test exposure; the backend attributes the flow to these. The SDK sends the full active set on every event, so the latest change is the complete truth. additionalProperties: type: string seq: type: integer description: > Sequence number to order events within the same session (must be strictly increasing for each subsequent event in the same session). It belongs to the SDK's counter, so a server sending events into a browser session does not share it: on the authenticated endpoint the value is moved into negative space at ingest, where it orders that sender's own events only and is excluded from gap detection. Send -1 (or any negative value, which is stored unchanged) to state explicitly that the event carries no sequence information. Never try to force sort order with an out-of-band positive value such as 100000 — relative to the client's counter it means "everything in between was lost in transit". observeUserReference: type: object properties: userId: type: string description: User ID identifier: type: string description: User identifier (e.g. email) crossEnvironmentTransactionIDStart: type: string description: Cross-environment transaction ID used to correlate events across sessions/devices crossEnvironmentTransactionIDFinish: type: string description: Cross-environment transaction ID used to correlate events across sessions/devices crossEnvironmentTransactionID: type: string description: Generic transaction ID that links any sessions sharing the same value so they are classified together (independent of subflow type) observeDevicesInfo: type: object required: - type - clientEnvHandle - clientEnvHandleMeta properties: type: type: string enum: - "web" - "app" clientEnvHandle: type: string clientEnvHandleMeta: $ref: "#/components/schemas/observeClientEnvHandleMeta" tabId: type: string description: Per-tab id (sessionStorage-scoped) distinguishing tabs that share one localStorage-backed session. data: oneOf: - $ref: "#/components/schemas/observeDeviceInfoWeb" - $ref: "#/components/schemas/observeDeviceInfoApp" collectionErrors: type: array items: $ref: "#/components/schemas/observeDeviceInfoCollectionError" observeDeviceInfoWeb: type: object properties: bluetoothAvailable: type: boolean userVerifyingPlatformAuthenticatorAvailable: type: boolean conditionalMediationAvailable: type: boolean javaScriptHighEntropy: $ref: "#/components/schemas/observeJavaScriptHighEntropy" webDriver: type: boolean privateMode: type: boolean clientCapabilities: type: object additionalProperties: type: string maxTouchPoints: type: integer description: >- navigator.maxTouchPoints, the maximum number of simultaneous touch contact points. Stored raw. Values outside 0-255 are ignored. observeDeviceInfoCollectionError: type: object required: - field - source - error properties: field: type: string enum: - bluetoothAvailable - conditionalMediationAvailable - userVerifyingPlatformAuthenticatorAvailable - clientCapabilities - javaScriptHighEntropy - privateMode - webdriver - maxTouchPoints source: type: string error: $ref: "#/components/schemas/observeDeviceInfoCollectionErrorDetail" observeDeviceInfoCollectionErrorDetail: type: object required: - message properties: name: type: string message: type: string observeDeviceInfoApp: type: object required: - osName - osVersion properties: osName: type: string osVersion: type: string model: type: string description: Device model (e.g. "iPhone15,3", "Pixel 8"). Optional; older SDKs omit it. brand: type: string description: Device manufacturer/brand (e.g. "Apple", "Google"). Optional; older SDKs omit it. appName: type: string description: Host application name (e.g. "Acme Banking"). Optional; older SDKs omit it. appVersion: type: string description: Host application version (e.g. "3.2.1"). Optional; older SDKs omit it. deviceOwnerAuth: type: string enum: - none - code - bio-face - bio-touch - bio-strong - bio-weak - bio description: >- Device owner authentication / screen-lock method. iOS reports bio-face/bio-touch, Android reports bio-strong/bio-weak, bio is a catch-all for other biometrics. Optional; older SDKs omit it. isBluetoothAvailable: type: boolean description: Whether Bluetooth is available on the device. Optional; older SDKs omit it. androidGooglePlayServicesVersion: type: string description: Google Play Services version (Android only; null on iOS). Optional; older SDKs omit it. locale: type: string description: Device locale (BCP-47, e.g. "en-US"). Optional; older SDKs omit it. screen: $ref: "#/components/schemas/observeAppScreen" observeAppScreen: type: object description: Native app screen geometry in logical points plus the backing scale factor. properties: widthPoints: type: number format: float heightPoints: type: number format: float scale: type: number format: float observeJavaScriptHighEntropy: type: object required: - platform - platformVersion - mobile properties: platform: type: string platformVersion: type: string mobile: type: boolean model: type: string description: Device model from the UA-CH model hint (only populated on Android browsers). observeClientEnvHandleMeta: type: object required: - ts - source properties: ts: type: integer format: int64 source: type: string enum: - "ls" - "cookie" - "storage" observeTimeSeriesInterval: type: string enum: - hourly - daily - monthly description: Aggregation interval for the time series observeTimeSeriesReadInterval: type: string enum: - hourly - daily - monthly - 1m - 5m description: > Interval of a time series read: the precalculated intervals plus the dynamic intervals (1m, 5m) that are always computed live observeTimeSeriesLiveMode: type: string enum: - latest description: Which buckets of a precalculated read are computed live instead of read from storage observeTimeSeriesGetRsp: type: object required: - panel properties: panel: $ref: "#/components/schemas/observeTimeSeriesPanel" observeTimeSeriesPrecalculateReq: type: object properties: fromDate: type: string description: > Range start as a local datetime without timezone, formatted as YYYY-MM-DDTHH:MM:SS (e.g. "2026-01-01T00:00:00"). Must be provided together with toDate. When omitted, only the most recent window is recomputed. pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$' example: "2026-01-01T00:00:00" x-oapi-codegen-extra-tags: validate: required_with=ToDate,omitempty,datetime=2006-01-02T15:04:05 toDate: type: string description: > Range end as a local datetime without timezone, formatted as YYYY-MM-DDTHH:MM:SS (e.g. "2026-02-01T00:00:00"). Must be provided together with fromDate. pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$' example: "2026-02-01T00:00:00" x-oapi-codegen-extra-tags: validate: required_with=FromDate,omitempty,datetime=2006-01-02T15:04:05 observeTimeSeriesPrecalculate: type: object required: - status - jobsExecuted properties: status: type: string description: Status of the time series precalculation run enum: - completed jobsExecuted: type: integer description: Number of time series window jobs executed format: int32 observeTimeSeriesPanel: type: object required: - times - namedTimeSeries - customTags properties: times: type: array items: type: integer format: int64 live: type: array description: > Aligned with times: true when the bucket was computed live from the source tables instead of read from the precalculated data. Omitted when no bucket is live. items: type: boolean namedTimeSeries: type: array items: $ref: "#/components/schemas/observeNamedTimeSeries" customTags: type: array description: Ordered custom tag names configured on the project assignment (maps to customTag1..6 dimensions) items: type: string facets: type: object description: > Distinct values per filterable dimension over the unprojected window. Flow series omit t2 because it is the long path. additionalProperties: type: array items: type: string observeNamedTimeSeries: type: object required: - name - dimensions - values properties: name: type: string dimensions: type: object additionalProperties: type: string values: type: array items: type: number format: float observeTimeSeriesExportFormat: type: string description: File format of a time series export enum: - csv - parquet observeTimeSeriesExportStatus: type: string description: > Lifecycle status of a time series export. `running` while it is generated, `completed` once every file is stored, `failed` when generation was aborted (deadline, error, disconnect), `expired` once the files were removed after the retention period. `pending` is reserved for queued exports. enum: - pending - running - completed - failed - expired observeTimeSeriesExportReq: type: object required: - fromDate - toDate - interval - format - timeSeries properties: fromDate: type: string description: Range start in UTC, formatted as YYYY-MM-DDTHH:MM:SS without a timezone suffix. Convert project-local selections to UTC before calling. Applies to every exported time series. pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$' example: "2026-05-20T00:00:00" x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 toDate: type: string description: Exclusive range end in UTC, formatted as YYYY-MM-DDTHH:MM:SS without a timezone suffix. Must be after fromDate; the maximum range depends on the interval. pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$' example: "2026-06-20T00:00:00" x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 interval: type: string description: "Aggregation interval, applies to every exported time series. One of: hourly, daily, monthly." example: "daily" x-oapi-codegen-extra-tags: validate: required,oneof=hourly daily monthly format: type: string description: "File format, applies to every exported time series. One of: csv, parquet." example: "csv" x-oapi-codegen-extra-tags: validate: required,oneof=csv parquet timeSeries: type: array description: Time series to export, one file each. Names must be unique within the request. minItems: 1 maxItems: 20 items: $ref: "#/components/schemas/observeTimeSeriesExportSeriesReq" x-oapi-codegen-extra-tags: validate: required,min=1,max=20,dive observeTimeSeriesExportSeriesReq: type: object required: - name properties: name: type: string description: Time series definition name (see GET /observe/timeSeriesDefinitions), e.g. login-flow-v1 example: "login-flow-v1" x-oapi-codegen-extra-tags: validate: required,min=1,max=100 excludeColumns: type: array description: > Dimension columns to leave out of the file. Excluding a dimension collapses it: rows that differ only in excluded dimensions are summed (same semantics as omitting the key from groupBy). Allowed: applicationId, browser, os, osVersion, customTag1..6, t1..t10. `time` and `value` cannot be excluded. maxItems: 22 items: type: string example: ["t2", "osVersion"] x-oapi-codegen-extra-tags: validate: omitempty,max=22,unique,dive,oneof=applicationId browser os osVersion customTag1 customTag2 customTag3 customTag4 customTag5 customTag6 t1 t2 t3 t4 t5 t6 t7 t8 t9 t10 engagement: type: string description: "Flow-series engagement filter, same semantics as GET /observe/timeSeries. One of: all, engaged, non-engaged. Defaults to all." example: "all" x-oapi-codegen-extra-tags: validate: omitempty,oneof=all engaged non-engaged observeTimeSeriesExportFile: type: object required: - name - size - checksum - rows properties: name: type: string description: File name within the export, e.g. login-flow-v1.csv size: type: integer format: int64 description: File size in bytes checksum: type: string description: Checksum of the stored object as reported by the object store rows: type: integer format: int64 description: Number of data rows in the file (excluding the CSV header) observeTimeSeriesColumn: type: object description: Meaning of one stable export column for a specific time series. required: - key - label - description - values properties: key: type: string description: Stable column key, matching the exported header. label: type: string description: Human-readable column label. description: type: string description: Explanation of the column meaning for this series. values: type: string description: Value meanings or guidance for open-ended values and missing data. observeTimeSeriesColumnGuide: type: object description: Column descriptions and interpretation notes for one time series. required: - version - columns - notes properties: version: type: integer description: Version of the column guide format. columns: type: array description: Only the exported columns, in file order. In precalculation config, all available export columns. items: $ref: "#/components/schemas/observeTimeSeriesColumn" notes: type: array items: type: string description: How to interpret aggregated rows, omitted values and excluded dimensions. observeTimeSeriesExportSeries: type: object required: - name - excludeColumns - engagement - columns - customTags properties: name: type: string excludeColumns: type: array items: type: string engagement: type: string columns: type: array description: Column names of the file in order items: type: string customTags: type: object description: Configured custom tag name per positional column key (customTag1..6) of this time series, as used in the file additionalProperties: type: string columnGuide: description: Column meanings captured when this export was created. Absent on older exports. allOf: - $ref: "#/components/schemas/observeTimeSeriesColumnGuide" file: $ref: "#/components/schemas/observeTimeSeriesExportFile" observeTimeSeriesExport: type: object required: - exportID - status - createdMs - fromDate - toDate - interval - format - timeZone - timeSeries properties: exportID: type: string description: |- Export ID (format `tse-`) example: "tse-123456" status: $ref: "#/components/schemas/observeTimeSeriesExportStatus" createdMs: $ref: "#/components/schemas/unixMilliTimestamp" completedMs: $ref: "#/components/schemas/unixMilliTimestamp" expiresAtMs: $ref: "#/components/schemas/unixMilliTimestamp" fromDate: type: string description: UTC range start without a timezone suffix. toDate: type: string description: Exclusive UTC range end without a timezone suffix. interval: $ref: "#/components/schemas/observeTimeSeriesInterval" format: $ref: "#/components/schemas/observeTimeSeriesExportFormat" timeZone: type: string description: IANA timezone of the project at export time; the files' timeLocal column renders bucket starts in it. example: "Europe/Berlin" sizeBytes: type: integer format: int64 description: Total size of all files in bytes timeSeries: type: array items: $ref: "#/components/schemas/observeTimeSeriesExportSeries" error: type: string description: Failure reason for failed exports observeTimeSeriesExportList: type: object required: - exports properties: exports: type: array items: $ref: "#/components/schemas/observeTimeSeriesExport" observeTimeSeriesExportDownloadLink: type: object required: - link properties: link: type: string observeTimeSeriesExportEvent: type: object description: One line of the export progress stream. required: - type - exportID properties: type: type: string enum: - started - progress - completed - failed exportID: type: string series: type: string description: Time series name the progress event refers to sliceFrom: type: string description: Start of the time slice just written (progress) sliceTo: type: string description: Exclusive end of the time slice just written (progress) rows: type: integer format: int64 description: Rows written for this series so far (progress) bytes: type: integer format: int64 description: Bytes written for this series so far (progress) export: $ref: "#/components/schemas/observeTimeSeriesExport" observeEventFeedEntry: type: object required: - id - sessionID - name - data - metadata - classified - ingestedMs - createdMs properties: id: type: string description: |- Event ID (format `tev-`) sessionID: type: string description: Session public ID (UUID format) name: type: string description: Name of the tracking event data: type: object description: Additional event data additionalProperties: true metadata: type: object description: Event-scoped metadata additionalProperties: true batchMetadata: $ref: '#/components/schemas/observeEventBatchMetadata' classified: type: boolean description: True when the batch ingestion time is before or equal to the latest completed classification job created timestamp for the same session ingestedMs: description: Batch ingestion time in milliseconds since epoch (server-side) type: integer format: int64 createdMs: description: Event creation time in milliseconds since epoch (client-provided) type: integer format: int64 observeEventBatchMetadata: type: object description: Metadata of the ingestion batch (one delivery attempt) the event arrived with; shared by all events of the batch required: - status - createdMs properties: origin: type: string description: HTTP Origin header of the ingestion request transport: type: string description: Transport used by the client to send the batch flushReason: type: string description: Client-reported trigger that caused the flush this batch was sent in sentMs: type: integer format: int64 description: Client-reported batch send time in milliseconds since epoch retryCount: type: integer format: int32 description: Number of prior failed delivery attempts reported by the client configVersion: type: string description: Version of the SDK reliability configuration the client was running when it captured this batch dataPolicy: type: integer format: int32 description: Data policy code (0..255) the client reported with this batch (`meta.dataPolicy`), when available status: type: string description: How client-side deduplication affected the batch ('backfilled' marks rows synthesized from pre-batch-table data) enum: - clean - partial_duplicate - full_duplicate - backfilled createdMs: type: integer format: int64 description: Server-side batch ingestion time in milliseconds since epoch responses: error: description: Error content: application/json: schema: $ref: "#/components/schemas/errorRspV2" "204": description: Operation succeeded without content security: - bearerAuth: []