{"openapi":"3.1.0","info":{"title":"Dregs API","description":"Customer REST API for sending events and reading fraud scores, identities, devices, escalations, channels, datasets, and mappings.\n\nAuthenticate with a secret key created in the dashboard under Settings > Credentials (security scheme secretKey). Send it as a Bearer token: Authorization: Bearer sk_... The key acts as an admin of that credential's team. POST /api/events and GET /api/devices/{fingerprint} also accept the credential's public key (security scheme publicKey, Bearer pk_...). Public keys may be embedded in a browser. Secret keys must not.\n\nThis document is the curated public surface. Dashboard sign-in, billing, team administration, and trainer tools are not included.","version":"1.0"},"servers":[{"url":"https://dregs.com","description":"Dregs API"}],"security":[{"secretKey":[]}],"tags":[{"name":"Escalations","description":"Escalation management"},{"name":"Datasets","description":"Dataset management for analyzers"},{"name":"Groups","description":"Groups (organizations, teams, workspaces, or whatever your app calls them) that identities belong to"},{"name":"Events","description":"Event tracking and management endpoints"},{"name":"Escalation Rules","description":"Escalation rule management"},{"name":"Mappings","description":"Manage mappings from customer-supplied names to canonical fields and event types"},{"name":"Devices","description":"Devices tracked by Dregs"},{"name":"Channels","description":"Notification channel management"},{"name":"Badge Rules","description":"Badge rule management"},{"name":"Dashboard","description":"Dashboard summary data"},{"name":"Identities","description":"Identities known to Dregs"}],"paths":{"/api/mappings":{"get":{"tags":["Mappings"],"summary":"List mappings","description":"List mappings for one kind at the given scope. Customer scope is the team's own mappings. Global scope is the shared defaults.","operationId":"listMappings","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["global","customer"]}},{"name":"kind","in":"query","required":true,"schema":{"type":"string","enum":["IDENTITY_FIELD","EVENT_TYPE"]}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Mapping"}}}}}},"security":[{"secretKey":[]}]},"put":{"tags":["Mappings"],"summary":"Set mapping","description":"Create or update a mapping at the given scope. Uniqueness is on (scope, kind, source).","operationId":"setMapping","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["global","customer"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SetMappingRequest"}}},"required":true},"responses":{"200":{"description":"Mapping saved","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Mapping"}}}},"400":{"description":"Target is not a valid canonical value for the given kind","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Mapping"}}}}},"security":[{"secretKey":[]}]}},"/api/groups/{type}/{id}/identities/{identityId}":{"put":{"tags":["Groups"],"summary":"Add identity to group","description":"Make an identity a member of a group. Adding an existing member is a no-op.","operationId":"addGroupIdentity","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"identityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Identity is a member"},"401":{"description":"Authentication required"},"404":{"description":"Group or identity not found"}},"security":[{"secretKey":[]}]},"delete":{"tags":["Groups"],"summary":"Remove identity from group","description":"Remove an identity from a group, for example when a user leaves a team","operationId":"removeGroupIdentity","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"identityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Identity removed"},"401":{"description":"Authentication required"},"404":{"description":"Identity is not a member of the group"}},"security":[{"secretKey":[]}]}},"/api/identities/{id}/actions/review":{"post":{"tags":["Identities"],"summary":"Request identity review","description":"Queue an LLM review of the identity's analysis","operationId":"reviewIdentity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ReviewRequest"}}}},"responses":{"201":{"description":"Review scheduled","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1IdentityReview"}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1IdentityReview"}}}},"404":{"description":"Identity not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1IdentityReview"}}}}},"security":[{"secretKey":[]}]}},"/api/identities/{id}/actions/analyze":{"post":{"tags":["Identities"],"summary":"Analyze identity","description":"Queue an analysis job for an identity","operationId":"analyzeIdentity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Analysis job scheduled"},"401":{"description":"Invalid credentials"},"404":{"description":"Identity not found"}},"security":[{"secretKey":[]}]}},"/api/events":{"get":{"tags":["Events"],"summary":"List tracked events","description":"Returns paginated list of tracked events for the current team","operationId":"listEvents","parameters":[{"name":"request","in":"query","required":true,"schema":{"$ref":"#/components/schemas/V1ListEventsRequest"}}],"responses":{"200":{"description":"Events retrieved successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1TrackedEvent"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1TrackedEvent"}}}}},"security":[{"secretKey":[]}]},"post":{"tags":["Events"],"summary":"Receive tracking event","description":"Receive a tracking event. Authenticate with a secret key (sk_) for server-side calls or a public key (pk_) for the browser tracker. Include an id to make the write idempotent.","operationId":"trackEvent","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1TrackRequest"}}},"required":true},"responses":{"200":{"description":"Event received successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackResponse"}}}},"400":{"description":"Invalid event data","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackResponse"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackResponse"}}}},"402":{"description":"Monthly event limit exceeded","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackResponse"}}}},"429":{"description":"Per-credential ingestion rate limit exceeded","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackResponse"}}}},"500":{"description":"Internal server error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackResponse"}}}}},"security":[{"secretKey":[]},{"publicKey":[]}]}},"/api/escalation-rules":{"get":{"tags":["Escalation Rules"],"summary":"List escalation rules","description":"Returns all escalation rules for the current team","operationId":"listEscalationRules","responses":{"200":{"description":"Escalation rules retrieved successfully","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1EscalationRule"}}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1EscalationRule"}}}}}},"security":[{"secretKey":[]}]},"post":{"tags":["Escalation Rules"],"summary":"Create escalation rule","description":"Creates a new escalation rule","operationId":"createEscalationRule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CreateEscalationRuleRequest"}}},"required":true},"responses":{"200":{"description":"Escalation rule created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationRule"}}}},"400":{"description":"Invalid request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationRule"}}}}},"security":[{"secretKey":[]}]}},"/api/escalation-rules/preview":{"post":{"tags":["Escalation Rules"],"summary":"Preview escalation rule","description":"Returns how many identities currently match the given conditions","operationId":"previewEscalationRule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1PreviewEscalationRuleRequest"}}},"required":true},"responses":{"200":{"description":"Preview computed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationRulePreview"}}}},"400":{"description":"Invalid conditions","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationRulePreview"}}}}},"security":[{"secretKey":[]}]}},"/api/datasets/{slug}/entries":{"get":{"tags":["Datasets"],"summary":"List entries for a dataset","description":"List entries in a dataset. Results are paginated with pageNumber and pageSize.","operationId":"listDatasetEntries","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["global","customer"]}},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":200}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1DatasetEntry"}}}}},"security":[{"secretKey":[]}]},"post":{"tags":["Datasets"],"summary":"Add entry to dataset","description":"Add or replace one entry in a dataset. Requires the admin role.","operationId":"addDatasetEntry","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["global","customer"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1DatasetEntryInput"}}},"required":true},"responses":{"200":{"description":"Entry saved"},"400":{"description":"Invalid entry"},"401":{"description":"Authentication required"}},"security":[{"secretKey":[]}]},"delete":{"tags":["Datasets"],"summary":"Remove entry from dataset","description":"Remove one entry from a dataset by key. Requires the admin role.","operationId":"removeDatasetEntry","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["global","customer"]}},{"name":"key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Entry removed"},"401":{"description":"Authentication required"},"404":{"description":"Entry not found"}},"security":[{"secretKey":[]}]}},"/api/channels":{"get":{"tags":["Channels"],"summary":"List channels","description":"Returns all notification channels for the current team","operationId":"listChannels","responses":{"200":{"description":"Channels retrieved successfully","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Channel"}}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Channel"}}}}}},"security":[{"secretKey":[]}]},"post":{"tags":["Channels"],"summary":"Create channel","description":"Creates a new notification channel. A webhook channel's response includes the signing secret, which is shown only this once. Other channel types return the channel without a secret.","operationId":"createChannel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CreateChannelRequest"}}},"required":true},"responses":{"200":{"description":"Channel created. Webhook channels include the signing secret.","content":{"application/json":{"schema":{"description":"A webhook channel includes its signing secret. Other channel types do not.","oneOf":[{"$ref":"#/components/schemas/V1Channel"},{"$ref":"#/components/schemas/V1ChannelWithSecret"}]}}}},"400":{"description":"Invalid request","content":{"*/*":{"schema":{"type":"object"}}}},"403":{"description":"Admin role required","content":{"*/*":{"schema":{"type":"object"}}}}},"security":[{"secretKey":[]}]}},"/api/channels/{id}/test":{"post":{"tags":["Channels"],"summary":"Test channel","description":"Sends a test delivery to the channel","operationId":"testChannel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Test delivery scheduled"},"404":{"description":"Channel not found"},"401":{"description":"Authentication required"},"403":{"description":"Admin role required"}},"security":[{"secretKey":[]}]}},"/api/badge-rules":{"get":{"tags":["Badge Rules"],"summary":"List badge rules","description":"Returns all badge rules for the current team","operationId":"listBadgeRules","responses":{"200":{"description":"Badge rules retrieved successfully","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1BadgeRule"}}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1BadgeRule"}}}}}},"security":[{"secretKey":[]}]},"post":{"tags":["Badge Rules"],"summary":"Create badge rule","description":"Creates a new badge rule","operationId":"createBadgeRule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CreateBadgeRuleRequest"}}},"required":true},"responses":{"200":{"description":"Badge rule created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1BadgeRule"}}}},"400":{"description":"Invalid request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1BadgeRule"}}}}},"security":[{"secretKey":[]}]}},"/api/identities/{id}":{"get":{"tags":["Identities"],"summary":"Get identity","description":"Get a single identity by ID","operationId":"getIdentity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Identity found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Identity"}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Identity"}}}},"404":{"description":"Identity not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Identity"}}}}},"security":[{"secretKey":[]}]},"patch":{"tags":["Identities"],"summary":"Update identity","description":"Update an existing identity. Requires the admin role, like the device PATCH, because disregarding re-scores linked identities.","operationId":"updateIdentity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UpdateIdentityRequest"}}},"required":true},"responses":{"200":{"description":"Identity updated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Identity"}}}},"400":{"description":"Invalid request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Identity"}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Identity"}}}},"403":{"description":"Admin role required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Identity"}}}},"404":{"description":"Identity not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Identity"}}}}},"security":[{"secretKey":[]}]}},"/api/groups/{type}/{id}":{"get":{"tags":["Groups"],"summary":"Get group","description":"Get a single group by type and ID, with its attributes and member count","operationId":"getGroup","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Group found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Group"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Group"}}}},"404":{"description":"Group not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Group"}}}}},"security":[{"secretKey":[]}]},"patch":{"tags":["Groups"],"summary":"Update group","description":"Merge attributes into an existing group","operationId":"updateGroup","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UpdateGroupRequest"}}},"required":true},"responses":{"200":{"description":"Group updated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Group"}}}},"400":{"description":"Invalid request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Group"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Group"}}}},"404":{"description":"Group not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Group"}}}}},"security":[{"secretKey":[]}]}},"/api/escalations/{id}":{"get":{"tags":["Escalations"],"summary":"Get escalation","description":"Returns a single escalation by ID","operationId":"getEscalation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Escalation found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Escalation"}}}},"404":{"description":"Escalation not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Escalation"}}}}},"security":[{"secretKey":[]}]},"patch":{"tags":["Escalations"],"summary":"Update escalation","description":"Acknowledge or resolve an escalation","operationId":"updateEscalation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UpdateEscalationRequest"}}},"required":true},"responses":{"200":{"description":"Escalation updated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Escalation"}}}},"400":{"description":"Invalid status transition","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Escalation"}}}},"404":{"description":"Escalation not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Escalation"}}}}},"security":[{"secretKey":[]}]}},"/api/escalation-rules/{id}":{"get":{"tags":["Escalation Rules"],"summary":"Get escalation rule","description":"Returns a single escalation rule by ID","operationId":"getEscalationRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Escalation rule found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationRule"}}}},"404":{"description":"Escalation rule not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationRule"}}}}},"security":[{"secretKey":[]}]},"delete":{"tags":["Escalation Rules"],"summary":"Delete escalation rule","description":"Deletes an escalation rule","operationId":"deleteEscalationRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Escalation rule deleted"},"404":{"description":"Escalation rule not found"}},"security":[{"secretKey":[]}]},"patch":{"tags":["Escalation Rules"],"summary":"Update escalation rule","description":"Updates an escalation rule","operationId":"updateEscalationRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UpdateEscalationRuleRequest"}}},"required":true},"responses":{"200":{"description":"Escalation rule updated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationRule"}}}},"404":{"description":"Escalation rule not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationRule"}}}}},"security":[{"secretKey":[]}]}},"/api/devices/{fingerprint}":{"get":{"tags":["Devices"],"summary":"Get device","description":"Get a single device by fingerprint. Accepts a secret key (sk_) or the credential's public key (pk_).","operationId":"getDevice","parameters":[{"name":"fingerprint","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Device found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Device"}}}},"401":{"description":"Invalid or missing authentication","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Device"}}}},"404":{"description":"Device not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Device"}}}}},"security":[{"secretKey":[]},{"publicKey":[]}]},"patch":{"tags":["Devices"],"summary":"Update device","description":"Update device fields (e.g., disregarded)","operationId":"updateDevice","parameters":[{"name":"fingerprint","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1PatchDeviceRequest"}}},"required":true},"responses":{"200":{"description":"Device updated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Device"}}}},"404":{"description":"Device not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Device"}}}}},"security":[{"secretKey":[]}]}},"/api/channels/{id}":{"get":{"tags":["Channels"],"summary":"Get channel","description":"Returns a single channel by ID","operationId":"getChannel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Channel found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Channel"}}}},"404":{"description":"Channel not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Channel"}}}}},"security":[{"secretKey":[]}]},"delete":{"tags":["Channels"],"summary":"Delete channel","description":"Deletes a notification channel","operationId":"deleteChannel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Channel deleted"},"403":{"description":"Admin role required"},"404":{"description":"Channel not found"}},"security":[{"secretKey":[]}]},"patch":{"tags":["Channels"],"summary":"Update channel","description":"Updates an existing notification channel","operationId":"updateChannel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UpdateChannelRequest"}}},"required":true},"responses":{"200":{"description":"Channel updated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Channel"}}}},"403":{"description":"Admin role required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Channel"}}}},"404":{"description":"Channel not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Channel"}}}}},"security":[{"secretKey":[]}]}},"/api/badge-rules/{id}":{"get":{"tags":["Badge Rules"],"summary":"Get badge rule","description":"Returns a single badge rule by ID","operationId":"getBadgeRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Badge rule found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1BadgeRule"}}}},"404":{"description":"Badge rule not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1BadgeRule"}}}}},"security":[{"secretKey":[]}]},"delete":{"tags":["Badge Rules"],"summary":"Delete badge rule","description":"Deletes a badge rule","operationId":"deleteBadgeRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Badge rule deleted"},"404":{"description":"Badge rule not found"}},"security":[{"secretKey":[]}]},"patch":{"tags":["Badge Rules"],"summary":"Update badge rule","description":"Updates a badge rule","operationId":"updateBadgeRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UpdateBadgeRuleRequest"}}},"required":true},"responses":{"200":{"description":"Badge rule updated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1BadgeRule"}}}},"404":{"description":"Badge rule not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1BadgeRule"}}}}},"security":[{"secretKey":[]}]}},"/api/mappings/discovery":{"get":{"tags":["Mappings"],"summary":"Discovery payload for the Settings → Mappings UI","description":"Returns, per mapping kind, one row per customer source — the union of sources we've seen in the customer's ingested data and sources the customer has already mapped. Each row carries the current customer mapping (if any) and a recommended canonical (if a global mapping matches the source by exact or variant rule).","operationId":"getMappingDiscovery","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1Discovery"}}}}},"security":[{"secretKey":[]}]}},"/api/identities":{"get":{"tags":["Identities"],"summary":"Identity list","description":"List identities known to Dregs","operationId":"listIdentities","parameters":[{"name":"request","in":"query","required":true,"schema":{"$ref":"#/components/schemas/V1ListIdentitiesRequest"}}],"responses":{"200":{"description":"Successfully authenticated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Identity"}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Identity"}}}}},"security":[{"secretKey":[]}]}},"/api/identities/{id}/scores":{"get":{"tags":["Identities"],"summary":"Get identity scores","description":"Get scores for an identity","operationId":"getIdentityScores","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Identity found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Score"}}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Score"}}}}},"404":{"description":"Identity not found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Score"}}}}}},"security":[{"secretKey":[]}]}},"/api/identities/{id}/reviews":{"get":{"tags":["Identities"],"summary":"List identity reviews","description":"List LLM reviews for an identity","operationId":"listIdentityReviews","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reviews found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1IdentityReview"}}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1IdentityReview"}}}}},"404":{"description":"Identity not found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1IdentityReview"}}}}}},"security":[{"secretKey":[]}]}},"/api/identities/{id}/links":{"get":{"tags":["Identities"],"summary":"Get identity links","description":"Get cross-identity links for an identity","operationId":"getIdentityLinks","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Links found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1LinkedIdentity"}}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1LinkedIdentity"}}}}},"404":{"description":"Identity not found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1LinkedIdentity"}}}}}},"security":[{"secretKey":[]}]}},"/api/identities/{id}/history":{"get":{"tags":["Identities"],"summary":"Get score history","description":"Get score history for an identity across analysis cycles","operationId":"getScoreHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"History found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1ScoreHistoryEntry"}}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1ScoreHistoryEntry"}}}}},"404":{"description":"Identity not found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1ScoreHistoryEntry"}}}}}},"security":[{"secretKey":[]}]}},"/api/identities/{id}/analysis":{"get":{"tags":["Identities"],"summary":"Get identity analysis","description":"Get the most recent analysis cycle for an identity","operationId":"getIdentityAnalysis","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Analysis found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1AnalysisCycle"}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1AnalysisCycle"}}}},"404":{"description":"Identity or analysis not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1AnalysisCycle"}}}}},"security":[{"secretKey":[]}]}},"/api/identities/{id}/analysis/{cycleId}":{"get":{"tags":["Identities"],"summary":"Get analysis cycle","description":"Get a specific analysis cycle by ID","operationId":"getAnalysisCycle","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cycleId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Analysis cycle found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1AnalysisCycle"}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1AnalysisCycle"}}}},"404":{"description":"Analysis cycle not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1AnalysisCycle"}}}}},"security":[{"secretKey":[]}]}},"/api/groups":{"get":{"tags":["Groups"],"summary":"Group list","description":"List groups of every type, or of one type, optionally only those an identity belongs to","operationId":"listGroups","parameters":[{"name":"request","in":"query","required":true,"schema":{"$ref":"#/components/schemas/V1ListGroupsRequest"}}],"responses":{"200":{"description":"Groups retrieved","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Group"}}}},"400":{"description":"Invalid group type","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Group"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Group"}}}}},"security":[{"secretKey":[]}]}},"/api/events/{id}":{"get":{"tags":["Events"],"summary":"Get event","description":"Get a single tracked event by ID","operationId":"getEvent","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackedEvent"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackedEvent"}}}},"404":{"description":"Event not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1TrackedEvent"}}}}},"security":[{"secretKey":[]}]}},"/api/escalations":{"get":{"tags":["Escalations"],"summary":"List escalations","description":"Returns escalations with optional filtering","operationId":"listEscalations","parameters":[{"name":"request","in":"query","required":true,"schema":{"$ref":"#/components/schemas/V1ListEscalationsRequest"}}],"responses":{"200":{"description":"Escalations retrieved successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Escalation"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Escalation"}}}}},"security":[{"secretKey":[]}]}},"/api/escalations/summary":{"get":{"tags":["Escalations"],"summary":"Escalation summary","description":"Returns escalation counts grouped by status","operationId":"getEscalationSummary","responses":{"200":{"description":"Summary retrieved successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationSummary"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1EscalationSummary"}}}}},"security":[{"secretKey":[]}]}},"/api/devices":{"get":{"tags":["Devices"],"summary":"Device list","description":"List devices tracked by Dregs","operationId":"listDevices","parameters":[{"name":"request","in":"query","required":true,"schema":{"$ref":"#/components/schemas/V1ListDevicesRequest"}}],"responses":{"200":{"description":"Successfully retrieved devices","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Device"}}}},"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1PageV1Device"}}}}},"security":[{"secretKey":[]}]}},"/api/datasets":{"get":{"tags":["Datasets"],"summary":"List datasets with entry counts","description":"List datasets at the requested scope, with entry counts. Customer scope is the team's datasets. Global scope is the shared catalogs.","operationId":"listDatasets","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["global","customer"]}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1DatasetOverview"}}}}}},"security":[{"secretKey":[]}]}},"/api/dashboard/timeseries":{"get":{"tags":["Dashboard"],"summary":"Dashboard timeseries","description":"Get hourly or daily buckets for events, active identities, and scored identities over the chosen range (24h/7d/30d)","operationId":"getDashboardTimeseries","parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","default":"7d"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1DashboardTimeseries"}}}}},"security":[{"secretKey":[]}]}},"/api/dashboard/stats":{"get":{"tags":["Dashboard"],"summary":"Dashboard stats","description":"Get summary statistics for the dashboard","operationId":"getDashboardStats","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1DashboardStats"}}}}},"security":[{"secretKey":[]}]}},"/api/dashboard/score-distribution":{"get":{"tags":["Dashboard"],"summary":"Score distribution","description":"Get score distribution across buckets for all four categories","operationId":"getScoreDistribution","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1ScoreDistribution"}}}}},"security":[{"secretKey":[]}]}},"/api/dashboard/rule-activity":{"get":{"tags":["Dashboard"],"summary":"Rule activity","description":"Get per-badge-rule identity groups and per-escalation-rule escalation groups with activity within the selected range","operationId":"getRuleActivity","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1RuleActivity"}}}}},"security":[{"secretKey":[]}]}},"/api/dashboard/recently-active":{"get":{"tags":["Dashboard"],"summary":"Recently active identities","description":"Get the 5 most recently active identities","operationId":"getRecentlyActive","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Identity"}}}}}},"security":[{"secretKey":[]}]}},"/api/dashboard/attention":{"get":{"tags":["Dashboard"],"summary":"Attention summary","description":"Get counts of items needing attention (open escalations by severity, high-risk identities in last 24h, failed channel deliveries in last 24h)","operationId":"getAttention","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/V1AttentionSummary"}}}}},"security":[{"secretKey":[]}]}},"/api/channels/{id}/deliveries":{"get":{"tags":["Channels"],"summary":"Get channel deliveries","description":"Returns delivery history for a channel","operationId":"listChannelDeliveries","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"description":"Deliveries retrieved successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PageV1ChannelDelivery"}}}},"404":{"description":"Channel not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PageV1ChannelDelivery"}}}},"401":{"description":"Authentication required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PageV1ChannelDelivery"}}}}},"security":[{"secretKey":[]}]}},"/api/mappings/{id}":{"delete":{"tags":["Mappings"],"summary":"Delete mapping","description":"Delete a mapping. Requires the admin role. Deleting a customer mapping makes that source fall back to the global default.","operationId":"deleteMapping","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["global","customer"]}}],"responses":{"204":{"description":"Mapping deleted"},"404":{"description":"Mapping not found"}},"security":[{"secretKey":[]}]}}},"components":{"schemas":{"V1SetMappingRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["IDENTITY_FIELD","EVENT_TYPE"]},"source":{"type":"string"},"target":{"type":"string"},"description":{"type":"string"}}},"V1Mapping":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"scope":{"type":"string","enum":["global","customer"]},"kind":{"type":"string","enum":["IDENTITY_FIELD","EVENT_TYPE"]},"source":{"type":"string"},"target":{"type":"string"},"description":{"type":"string"}}},"V1ReviewRequest":{"type":"object","properties":{"feedback":{"type":"string"}}},"V1AnalyzerComparison":{"type":"object","properties":{"baselineAnalyzerName":{"type":"string"},"changedCount":{"type":"integer","format":"int32"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/V1AnalyzerComparisonRow"}}}},"V1AnalyzerComparisonRow":{"type":"object","properties":{"identityId":{"type":"string"},"underReview":{"type":"boolean"},"beforeValue":{"type":"number","format":"double"},"afterValue":{"type":"number","format":"double"},"beforeExplanation":{"type":"string"},"afterExplanation":{"type":"string"},"observationCount":{"type":"integer","format":"int32"},"changed":{"type":"boolean"},"error":{"type":"string"}}},"V1ConfigSuggestion":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"rationale":{"type":"string"}}},"V1IdentityReview":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"identityId":{"type":"string"},"userFeedback":{"type":"string"},"status":{"type":"string"},"summary":{"type":"string"},"proposedAnalyzers":{"type":"array","items":{"$ref":"#/components/schemas/V1ProposedAnalyzer"}},"proposedRevisions":{"type":"array","items":{"$ref":"#/components/schemas/V1ProposedRevision"}},"configSuggestions":{"type":"array","items":{"$ref":"#/components/schemas/V1ConfigSuggestion"}},"model":{"type":"string"},"errorMessage":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}},"V1ProposedAnalyzer":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"rationale":{"type":"string"},"status":{"type":"string"},"comparison":{"$ref":"#/components/schemas/V1AnalyzerComparison"}}},"V1ProposedRevision":{"type":"object","properties":{"analyzerName":{"type":"string"},"category":{"type":"string"},"rationale":{"type":"string"},"status":{"type":"string"},"comparison":{"$ref":"#/components/schemas/V1AnalyzerComparison"}}},"V1TrackRequest":{"type":"object","properties":{"type":{"type":"string","minLength":1},"data":{"type":"object","additionalProperties":{}},"identity":{"$ref":"#/components/schemas/V1TrackRequestIdentity"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/V1TrackRequestGroup"}},"device":{"$ref":"#/components/schemas/V1TrackRequestDevice"},"key":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"source":{"type":"string"},"id":{"type":"string","description":"Optional client-supplied event ID for idempotent ingestion. When provided, repeated posts with the same ID are silently deduplicated against the previous event for the customer. Must not start with \"dregs-\" and must be at most 64 characters. When omitted, the server generates a dregs-{UUID} identifier.","example":"stripe_evt_1Q3abc"}},"required":["data","type"]},"V1TrackRequestDevice":{"type":"object","properties":{"signature":{"type":"string"},"data":{"type":"object","additionalProperties":{}}}},"V1TrackRequestGroup":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"data":{"type":"object","additionalProperties":{}}}},"V1TrackRequestIdentity":{"type":"object","properties":{"id":{"type":"string"},"data":{"type":"object","additionalProperties":{}}}},"V1TrackResponse":{"type":"object","properties":{"status":{"type":"string"},"id":{"type":"string"},"fingerprint":{"type":"string"}}},"RuleCondition":{"type":"object","properties":{"condition":{"type":"string"},"category":{"type":"string"},"threshold":{"type":"integer","format":"int32"},"badge":{"type":"string"},"seconds":{"type":"integer","format":"int32"}}},"V1CreateEscalationRuleRequest":{"type":"object","properties":{"name":{"type":"string"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}},"severity":{"type":"string","enum":["INFO","WARNING","CRITICAL"]},"channels":{"type":"array","items":{"type":"string"}},"openAfterSeconds":{"type":"integer","format":"int32"},"closeAfterSeconds":{"type":"integer","format":"int32"},"effectiveAt":{"type":"string","format":"date-time"}}},"V1EscalationRule":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"slug":{"type":"string"},"name":{"type":"string"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}},"severity":{"type":"string","enum":["INFO","WARNING","CRITICAL"]},"channels":{"type":"array","items":{"type":"string"}},"openAfterSeconds":{"type":"integer","format":"int32"},"closeAfterSeconds":{"type":"integer","format":"int32"},"effectiveAt":{"type":"string","format":"date-time"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"V1PreviewEscalationRuleRequest":{"type":"object","properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}}}},"V1EscalationRulePreview":{"type":"object","properties":{"matchCount":{"type":"integer","format":"int64"},"totalCount":{"type":"integer","format":"int64"}}},"V1DatasetEntryInput":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"V1CreateChannelRequest":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"config":{"type":"object","additionalProperties":{}},"secrets":{"type":"object","additionalProperties":{}}}},"V1Channel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["EMAIL","WEBHOOK","SLACK","SMS"]},"config":{"type":"object","additionalProperties":{}},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"V1ChannelWithSecret":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["EMAIL","WEBHOOK","SLACK","SMS"]},"config":{"type":"object","additionalProperties":{}},"secret":{"type":"string"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"V1CreateBadgeRuleRequest":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["GOOD","BAD","NEUTRAL"]},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}},"priority":{"type":"integer","format":"int32"},"applyDelaySeconds":{"type":"integer","format":"int32"},"removeDelaySeconds":{"type":"integer","format":"int32"}}},"V1BadgeRule":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["GOOD","BAD","NEUTRAL"]},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}},"priority":{"type":"integer","format":"int32"},"applyDelaySeconds":{"type":"integer","format":"int32"},"removeDelaySeconds":{"type":"integer","format":"int32"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"V1UpdateIdentityRequest":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{}},"disregarded":{"type":"boolean"}}},"V1Badge":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["GOOD","BAD","NEUTRAL"]},"explanation":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}}}},"V1Identity":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayEmail":{"type":"string"},"displayUsername":{"type":"string"},"humanityScore":{"type":"integer","format":"int32"},"authenticityScore":{"type":"integer","format":"int32"},"uniquenessScore":{"type":"integer","format":"int32"},"behaviorScore":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastTrackedAt":{"type":"string","format":"date-time"},"lastScoredAt":{"type":"string","format":"date-time"},"disregarded":{"type":"boolean"},"badges":{"type":"array","items":{"$ref":"#/components/schemas/V1Badge"}},"data":{"type":"object","additionalProperties":{}}}},"V1UpdateGroupRequest":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{}}},"required":["attributes"]},"V1Group":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"displayName":{"type":"string"},"identityCount":{"type":"integer","format":"int64"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastTrackedAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":{}}}},"V1UpdateEscalationRequest":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","OPEN","ACKNOWLEDGED","CLOSED"]}}},"BadgeSnapshot":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["GOOD","BAD","NEUTRAL"]},"explanation":{"type":"string"}}},"ScoreSnapshot":{"type":"object","properties":{"humanity":{"type":"integer","format":"int32"},"authenticity":{"type":"integer","format":"int32"},"uniqueness":{"type":"integer","format":"int32"},"behavior":{"type":"integer","format":"int32"}}},"V1Escalation":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"escalationRule":{"$ref":"#/components/schemas/V1Reference"},"identity":{"$ref":"#/components/schemas/V1Reference"},"identityName":{"type":"string"},"identityEmail":{"type":"string"},"identityUsername":{"type":"string"},"scoreSnapshot":{"$ref":"#/components/schemas/ScoreSnapshot"},"badgeSnapshot":{"type":"array","items":{"$ref":"#/components/schemas/BadgeSnapshot"}},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}},"triggeredConditions":{"type":"array","items":{"type":"boolean"}},"severity":{"type":"string","enum":["INFO","WARNING","CRITICAL"]},"status":{"type":"string","enum":["PENDING","OPEN","ACKNOWLEDGED","CLOSED"]},"openedAt":{"type":"string","format":"date-time"},"acknowledgedBy":{"type":"integer","format":"int64"},"acknowledgedAt":{"type":"string","format":"date-time"},"closedBy":{"type":"integer","format":"int64"},"closedAt":{"type":"string","format":"date-time"},"channels":{"type":"array","items":{"type":"string"}},"ruleDeleted":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"V1Reference":{"type":"object","description":"Reference to another entity with ID, label, and API path","properties":{"id":{"type":"string","description":"Unique identifier for the entity","example":"abc123"},"label":{"type":"string","description":"Human-readable label or name","example":"Bob User"},"path":{"type":"string","description":"API path to the entity resource","example":"/api/identities/abc123"}}},"V1UpdateEscalationRuleRequest":{"type":"object","properties":{"name":{"type":"string"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}},"severity":{"type":"string","enum":["INFO","WARNING","CRITICAL"]},"channels":{"type":"array","items":{"type":"string"}},"openAfterSeconds":{"type":"integer","format":"int32"},"closeAfterSeconds":{"type":"integer","format":"int32"},"effectiveAt":{"type":"string","format":"date-time"},"enabled":{"type":"boolean"}}},"V1PatchDeviceRequest":{"type":"object","properties":{"disregarded":{"type":"boolean"}}},"V1Device":{"type":"object","properties":{"fingerprint":{"type":"string"},"ip":{"type":"string"},"asn":{"type":"string"},"asnLabel":{"type":"string"},"userAgent":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"countryCode":{"type":"string"},"timezone":{"type":"string"},"latitude":{"type":"number","format":"double"},"longitude":{"type":"number","format":"double"},"disregarded":{"type":"boolean"},"disregardedViaIdentity":{"type":"boolean"},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"}}},"V1UpdateChannelRequest":{"type":"object","properties":{"name":{"type":"string"},"config":{"type":"object","additionalProperties":{}},"secrets":{"type":"object","additionalProperties":{}},"enabled":{"type":"boolean"}}},"V1UpdateBadgeRuleRequest":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["GOOD","BAD","NEUTRAL"]},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}},"priority":{"type":"integer","format":"int32"},"applyDelaySeconds":{"type":"integer","format":"int32"},"removeDelaySeconds":{"type":"integer","format":"int32"},"enabled":{"type":"boolean"}}},"V1CanonicalDescriptor":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}},"V1Discovery":{"type":"object","properties":{"kinds":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/V1KindDiscovery"}}}},"V1KindDiscovery":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/V1SourceRow"}},"canonicals":{"type":"array","items":{"$ref":"#/components/schemas/V1CanonicalDescriptor"}}}},"V1SourceRow":{"type":"object","properties":{"source":{"type":"string"},"seen":{"type":"boolean"},"seenCount":{"type":"integer","format":"int64"},"mappingId":{"type":"integer","format":"int64"},"canonical":{"type":"string"},"description":{"type":"string"},"recommendation":{"type":"string"}}},"V1ListIdentitiesRequest":{"type":"object","properties":{"pageNumber":{"type":"integer","format":"int32","minimum":0},"pageSize":{"type":"integer","format":"int32","maximum":100,"minimum":1},"order":{"type":"string","enum":["ASC","DESC"]},"sort":{"type":"string"},"device":{"type":"string"},"group":{"type":"string"},"groupType":{"type":"string"},"search":{"type":"string"},"term":{"type":"string"},"humanityScoreMin":{"type":"integer","format":"int32"},"humanityScoreMax":{"type":"integer","format":"int32"},"authenticityScoreMin":{"type":"integer","format":"int32"},"authenticityScoreMax":{"type":"integer","format":"int32"},"uniquenessScoreMin":{"type":"integer","format":"int32"},"uniquenessScoreMax":{"type":"integer","format":"int32"},"behaviorScoreMin":{"type":"integer","format":"int32"},"behaviorScoreMax":{"type":"integer","format":"int32"},"badge":{"type":"string"},"effectiveTerm":{"type":"string"}}},"V1PageV1Identity":{"type":"object","description":"Paginated response wrapper","properties":{"pageNumber":{"type":"integer","format":"int32","description":"Current page number (0-based)"},"pageSize":{"type":"integer","format":"int32","description":"Number of items per page"},"totalPages":{"type":"integer","format":"int64","description":"Total number of pages"},"totalElements":{"type":"integer","format":"int64","description":"Total number of items across all pages"},"content":{"type":"array","description":"List of items on this page","items":{"$ref":"#/components/schemas/V1Identity"}},"first":{"type":"boolean","description":"Whether this is the first page"},"last":{"type":"boolean","description":"Whether this is the last page"},"numberOfElements":{"type":"integer","format":"int32","description":"Number of items on this page"}}},"V1Observation":{"type":"object","properties":{"category":{"type":"string","enum":["UNIQUENESS","HUMANITY","AUTHENTICITY","BEHAVIOR"]},"id":{"type":"string"},"label":{"type":"string"},"explanation":{"type":"string"},"value":{"type":"number","format":"double"},"confidence":{"type":"number","format":"double"},"weight":{"type":"number","format":"double"},"metadata":{"type":"object","additionalProperties":{}}}},"V1Score":{"type":"object","properties":{"category":{"type":"string","enum":["UNIQUENESS","HUMANITY","AUTHENTICITY","BEHAVIOR"]},"value":{"type":"integer","format":"int32"},"observations":{"type":"array","items":{"$ref":"#/components/schemas/V1Observation"}}}},"V1LinkedIdentity":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"targetIdentityId":{"type":"string"},"targetDisplayName":{"type":"string"},"type":{"type":"string","enum":["SAME_DEVICE","SIMILAR_NAME","SIMILAR_EMAIL","SHARED_IP","SHARED_SESSION","SIMILAR_BEHAVIOR"]},"value":{"type":"number","format":"double"},"confidence":{"type":"number","format":"double"},"explanation":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"createdAt":{"type":"string","format":"date-time"}}},"V1ScoreHistoryEntry":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"humanityScore":{"type":"integer","format":"int32"},"authenticityScore":{"type":"integer","format":"int32"},"uniquenessScore":{"type":"integer","format":"int32"},"behaviorScore":{"type":"integer","format":"int32"},"eventCount":{"type":"integer","format":"int32"},"deviceCount":{"type":"integer","format":"int32"},"finishedAt":{"type":"string","format":"date-time"}}},"V1AnalysisCycle":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"identityId":{"type":"string"},"scores":{"type":"array","items":{"$ref":"#/components/schemas/V1Score"}},"humanityScore":{"type":"integer","format":"int32"},"authenticityScore":{"type":"integer","format":"int32"},"uniquenessScore":{"type":"integer","format":"int32"},"behaviorScore":{"type":"integer","format":"int32"},"eventCount":{"type":"integer","format":"int32"},"deviceCount":{"type":"integer","format":"int32"},"durationMillis":{"type":"integer","format":"int64"},"startedAt":{"type":"string","format":"date-time"},"finishedAt":{"type":"string","format":"date-time"}}},"V1ListGroupsRequest":{"type":"object","properties":{"pageNumber":{"type":"integer","format":"int32","minimum":0},"pageSize":{"type":"integer","format":"int32","maximum":100,"minimum":1},"order":{"type":"string","enum":["ASC","DESC"]},"sort":{"type":"string"},"type":{"type":"string"},"identity":{"type":"string"},"term":{"type":"string"}}},"V1PageV1Group":{"type":"object","description":"Paginated response wrapper","properties":{"pageNumber":{"type":"integer","format":"int32","description":"Current page number (0-based)"},"pageSize":{"type":"integer","format":"int32","description":"Number of items per page"},"totalPages":{"type":"integer","format":"int64","description":"Total number of pages"},"totalElements":{"type":"integer","format":"int64","description":"Total number of items across all pages"},"content":{"type":"array","description":"List of items on this page","items":{"$ref":"#/components/schemas/V1Group"}},"first":{"type":"boolean","description":"Whether this is the first page"},"last":{"type":"boolean","description":"Whether this is the last page"},"numberOfElements":{"type":"integer","format":"int32","description":"Number of items on this page"}}},"V1ListEventsRequest":{"type":"object","properties":{"pageNumber":{"type":"integer","format":"int32","minimum":0},"pageSize":{"type":"integer","format":"int32","maximum":100,"minimum":1},"order":{"type":"string","enum":["ASC","DESC"]},"sort":{"type":"string"},"identity":{"type":"string"},"group":{"type":"string"},"groupType":{"type":"string"},"device":{"type":"string"},"session":{"type":"string"},"term":{"type":"string"}}},"V1GroupReference":{"type":"object","description":"Reference to a group with its type, ID, label, and API path","properties":{"type":{"type":"string","description":"The group's type, normalized to lower_snake_case","example":"organization"},"id":{"type":"string","description":"The group's ID in your system","example":"org_678"},"label":{"type":"string","description":"The group's display name, if known","example":"Acme Inc"},"path":{"type":"string","description":"API path to the group resource","example":"/api/groups/organization/org_678"}}},"V1PageV1TrackedEvent":{"type":"object","description":"Paginated response wrapper","properties":{"pageNumber":{"type":"integer","format":"int32","description":"Current page number (0-based)"},"pageSize":{"type":"integer","format":"int32","description":"Number of items per page"},"totalPages":{"type":"integer","format":"int64","description":"Total number of pages"},"totalElements":{"type":"integer","format":"int64","description":"Total number of items across all pages"},"content":{"type":"array","description":"List of items on this page","items":{"$ref":"#/components/schemas/V1TrackedEvent"}},"first":{"type":"boolean","description":"Whether this is the first page"},"last":{"type":"boolean","description":"Whether this is the last page"},"numberOfElements":{"type":"integer","format":"int32","description":"Number of items on this page"}}},"V1TrackedEvent":{"type":"object","description":"Tracked event information","properties":{"id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"identity":{"$ref":"#/components/schemas/V1Reference"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/V1GroupReference"}},"fingerprint":{"type":"string"},"session":{"type":"string"},"ip":{"type":"string"},"url":{"type":"string"},"eventSource":{"type":"string"},"eventName":{"type":"string"},"canonicalType":{"type":"string","enum":["REGISTRATION","LOGIN","LOGIN_FAILED","LOGOUT","PASSWORD_RESET","PASSWORD_CHANGE","EMAIL_CONFIRMATION","OTP_REQUEST","PROFILE_UPDATE","RESOURCE_CREATE","RESOURCE_UPDATE","RESOURCE_RETRIEVE","RESOURCE_DELETE","MESSAGE_SEND","EMAIL_SEND","INVITATION_SEND","PURCHASE","PAYMENT_ATTEMPT","REFUND_REQUEST","PROMO_REDEEM","PAGE_VIEW","SEARCH","CONTENT_POST","FILE_UPLOAD","MISCELLANEOUS"]},"eventData":{"type":"object","additionalProperties":{}}}},"V1ListEscalationsRequest":{"type":"object","properties":{"pageNumber":{"type":"integer","format":"int32","minimum":0},"pageSize":{"type":"integer","format":"int32","maximum":100,"minimum":1},"order":{"type":"string","enum":["ASC","DESC"]},"sort":{"type":"string"},"status":{"type":"string","enum":["PENDING","OPEN","ACKNOWLEDGED","CLOSED"]},"severity":{"type":"string","enum":["INFO","WARNING","CRITICAL"]},"identity":{"type":"string"},"rule":{"type":"string"},"includeDeletedRules":{"type":"boolean"}}},"V1PageV1Escalation":{"type":"object","description":"Paginated response wrapper","properties":{"pageNumber":{"type":"integer","format":"int32","description":"Current page number (0-based)"},"pageSize":{"type":"integer","format":"int32","description":"Number of items per page"},"totalPages":{"type":"integer","format":"int64","description":"Total number of pages"},"totalElements":{"type":"integer","format":"int64","description":"Total number of items across all pages"},"content":{"type":"array","description":"List of items on this page","items":{"$ref":"#/components/schemas/V1Escalation"}},"first":{"type":"boolean","description":"Whether this is the first page"},"last":{"type":"boolean","description":"Whether this is the last page"},"numberOfElements":{"type":"integer","format":"int32","description":"Number of items on this page"}}},"V1EscalationSummary":{"type":"object","properties":{"open":{"type":"integer","format":"int64"},"acknowledged":{"type":"integer","format":"int64"},"closed":{"type":"integer","format":"int64"}}},"V1ListDevicesRequest":{"type":"object","properties":{"pageNumber":{"type":"integer","format":"int32","minimum":0},"pageSize":{"type":"integer","format":"int32","maximum":100,"minimum":1},"order":{"type":"string","enum":["ASC","DESC"]},"sort":{"type":"string"},"search":{"type":"string"},"identity":{"type":"string"},"term":{"type":"string"},"effectiveTerm":{"type":"string"}}},"V1PageV1Device":{"type":"object","description":"Paginated response wrapper","properties":{"pageNumber":{"type":"integer","format":"int32","description":"Current page number (0-based)"},"pageSize":{"type":"integer","format":"int32","description":"Number of items per page"},"totalPages":{"type":"integer","format":"int64","description":"Total number of pages"},"totalElements":{"type":"integer","format":"int64","description":"Total number of items across all pages"},"content":{"type":"array","description":"List of items on this page","items":{"$ref":"#/components/schemas/V1Device"}},"first":{"type":"boolean","description":"Whether this is the first page"},"last":{"type":"boolean","description":"Whether this is the last page"},"numberOfElements":{"type":"integer","format":"int32","description":"Number of items on this page"}}},"V1DatasetOverview":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"caseSensitive":{"type":"boolean"},"type":{"type":"string"},"trainerOnly":{"type":"boolean"},"customerEntryCount":{"type":"integer","format":"int64"},"globalEntryCount":{"type":"integer","format":"int64"}}},"V1DatasetEntry":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"key":{"type":"string"},"value":{"type":"string"}}},"V1PageV1DatasetEntry":{"type":"object","description":"Paginated response wrapper","properties":{"pageNumber":{"type":"integer","format":"int32","description":"Current page number (0-based)"},"pageSize":{"type":"integer","format":"int32","description":"Number of items per page"},"totalPages":{"type":"integer","format":"int64","description":"Total number of pages"},"totalElements":{"type":"integer","format":"int64","description":"Total number of items across all pages"},"content":{"type":"array","description":"List of items on this page","items":{"$ref":"#/components/schemas/V1DatasetEntry"}},"first":{"type":"boolean","description":"Whether this is the first page"},"last":{"type":"boolean","description":"Whether this is the last page"},"numberOfElements":{"type":"integer","format":"int32","description":"Number of items on this page"}}},"V1DashboardTimeseries":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/V1TimeseriesPoint"}},"identitiesActive":{"type":"array","items":{"$ref":"#/components/schemas/V1TimeseriesPoint"}},"identitiesScored":{"type":"array","items":{"$ref":"#/components/schemas/V1TimeseriesPoint"}},"totalIdentities":{"type":"array","items":{"$ref":"#/components/schemas/V1TimeseriesPoint"}}}},"V1TimeseriesPoint":{"type":"object","properties":{"bucket":{"type":"string"},"value":{"type":"integer","format":"int64"}}},"V1DashboardStats":{"type":"object","properties":{"totalIdentities":{"type":"integer","format":"int64"},"totalScored":{"type":"integer","format":"int64"},"totalEvents":{"type":"integer","format":"int64"},"identitiesActiveInRange":{"type":"integer","format":"int64"},"identitiesScoredInRange":{"type":"integer","format":"int64"},"eventsInRange":{"type":"integer","format":"int64"}}},"V1ScoreDistribution":{"type":"object","properties":{"humanity":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}},"authenticity":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}},"uniqueness":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}},"behavior":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}}}},"V1BadgeActivityGroup":{"type":"object","properties":{"rule":{"$ref":"#/components/schemas/V1BadgeRule"},"identities":{"type":"array","items":{"$ref":"#/components/schemas/V1Identity"}},"totalIdentities":{"type":"integer","format":"int64"}}},"V1EscalationActivityGroup":{"type":"object","properties":{"rule":{"$ref":"#/components/schemas/V1EscalationRule"},"escalations":{"type":"array","items":{"$ref":"#/components/schemas/V1Escalation"}},"totalEscalations":{"type":"integer","format":"int64"}}},"V1RuleActivity":{"type":"object","properties":{"badges":{"type":"array","items":{"$ref":"#/components/schemas/V1BadgeActivityGroup"}},"escalations":{"type":"array","items":{"$ref":"#/components/schemas/V1EscalationActivityGroup"}}}},"V1AttentionSummary":{"type":"object","properties":{"openEscalationsCritical":{"type":"integer","format":"int64"},"openEscalationsWarning":{"type":"integer","format":"int64"},"openEscalationsInfo":{"type":"integer","format":"int64"},"failedDeliveries24h":{"type":"integer","format":"int64"}}},"PageV1ChannelDelivery":{"type":"object","properties":{"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"content":{"type":"array","items":{"$ref":"#/components/schemas/V1ChannelDelivery"}},"number":{"type":"integer","format":"int32"},"first":{"type":"boolean"},"last":{"type":"boolean"},"pageable":{"$ref":"#/components/schemas/PageableObject"},"numberOfElements":{"type":"integer","format":"int32"},"sort":{"$ref":"#/components/schemas/SortObject"},"empty":{"type":"boolean"}}},"PageableObject":{"type":"object","properties":{"offset":{"type":"integer","format":"int64"},"paged":{"type":"boolean"},"pageNumber":{"type":"integer","format":"int32"},"pageSize":{"type":"integer","format":"int32"},"sort":{"$ref":"#/components/schemas/SortObject"},"unpaged":{"type":"boolean"}}},"SortObject":{"type":"object","properties":{"empty":{"type":"boolean"},"sorted":{"type":"boolean"},"unsorted":{"type":"boolean"}}},"V1ChannelDelivery":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"trigger":{"type":"string","enum":["IDENTITY_SCORED","IDENTITY_BADGES_CHANGED","ESCALATION_OPENED","ESCALATION_CLOSED","TEST"]},"status":{"type":"string","enum":["PENDING","DELIVERED","FAILED"]},"statusCode":{"type":"integer","format":"int32"},"payloadSize":{"type":"integer","format":"int32"},"errorMessage":{"type":"string"},"attemptNumber":{"type":"integer","format":"int32"},"deliveredAt":{"type":"string","format":"date-time"},"failedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}},"securitySchemes":{"secretKey":{"type":"http","description":"Customer secret key from Settings > Credentials, sent as a Bearer token. The token value starts with sk_. It acts as an admin of that credential's team for every operation in this document. MCP tokens (dmcp_) are refused. Prefer the publicKey scheme on operations that accept a pk_ key.","scheme":"bearer","bearerFormat":"sk_"},"publicKey":{"type":"http","description":"Customer public key from Settings > Credentials, sent as a Bearer token. The token value starts with pk_. Accepted only by POST /api/events and GET /api/devices/{fingerprint}. It may be embedded in a browser. It cannot call the other operations in this document.","scheme":"bearer","bearerFormat":"pk_"}}}}