The REST API

Everything you can do in the dashboard, you can do programmatically — the Dregs REST API gives you full control over identities, events, scores, alerts, and configuration. Build custom integrations, automate workflows, and embed fraud intelligence directly into your application.

Authentication

The API supports two authentication methods, each designed for a different use case.

JWT Tokens

Used by the dashboard and server-side integrations. Obtain a token by calling the login endpoint with your username and password. Include the token in the Authorization header as a Bearer token for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT tokens expire after a set period. When a token expires, call the login endpoint again to get a new one. Tokens are also invalidated if the user changes their password or their account is disabled.

Customer Public Keys

Used by the tracking script and device-related endpoints. The public key from your API credentials is sent as a Bearer token in the same header format. This method provides read-only access to device information and is the only authentication method available to client-side code.

Authorization: Bearer your-public-key-here

Key Endpoint Groups

The API is organized around the core entities in Dregs. Here is an overview of what is available.

Events

The tracking script sends events via POST /api/events, which accepts anonymous requests authenticated by customer key. Reading events via GET /api/events requires JWT authentication and returns a paginated, filterable list of all tracked events for your account.

Identities

List all identities, get detail for a specific identity, retrieve scores and analysis results, and trigger a re-analysis. The identity endpoints are the core of the API — this is where you access the scores and observations that drive fraud decisions.

• GET /api/identities — paginated list with search and filtering
• GET /api/identities/{id} — full identity detail
• GET /api/identities/{id}/scores — current scores
• GET /api/identities/{id}/analysis — detailed analyzer observations
• POST /api/identities/{id}/actions/analyze — trigger re-scoring

Devices

List all fingerprinted devices or get detail for a specific device by fingerprint. Device endpoints support both JWT and customer key authentication — the tracking script uses the public key to fetch device info, while the dashboard uses JWT.

Alerts

List alerts with filtering by status, severity, and identity. Get alert detail, update alert status (acknowledge or close), and retrieve summary counts. The alert endpoints let you build your own triage workflows outside the dashboard.

Alert Rules and Badge Rules

Full CRUD for both alert rules and badge rules. Create rules that trigger alerts when scores cross thresholds, or badge rules that automatically label identities. Admin role required for creating, updating, and deleting rules.

Channels

Create and manage notification channels (email, Slack, webhook). Send test deliveries to verify integrations. View delivery history for any channel. See Channels and Webhooks for details on channel types and webhook configuration.

Dashboard

Programmatic access to the same data the home page displays: aggregate stats, score distributions, and recently active identities. Useful for building custom dashboards or feeding Dregs data into other monitoring tools.

Datasets

Create and manage datasets and their entries. The API supports bulk operations — replace all entries in a dataset or append new ones — making it the right tool for importing large datasets from external sources.

Team

Manage team invitations and API credentials programmatically. Invite new members, revoke invitations, create and disable credentials, and update allowed origins.

Pagination

All list endpoints return paginated results. Control pagination with these query parameters:

• pageNumber — the page to retrieve (zero-indexed)
• pageSize — number of items per page
• sort — the field to sort by (varies by endpoint)

Responses include the items for the current page plus metadata: total number of items, total number of pages, current page number, and page size. This gives you everything you need to build pagination controls in your own UI.

Filtering

Most list endpoints support filtering parameters specific to the entity type. The term parameter provides free-text search across relevant fields — for identities, it searches across identifier, display name, email, and username. For events, it searches event name, IP address, and identity. For devices, it searches fingerprint, IP, city, country, and user agent.

Structured filters are also available. Identity endpoints accept score range parameters. Event endpoints accept identity and fingerprint filters. Alert endpoints accept status and severity filters. All filters combine freely — you can use multiple filters in a single request to narrow down results precisely.

API Design Conventions

The API follows RESTful conventions throughout. Standard CRUD operations use the expected HTTP methods: GET for reads, POST for creates, PATCH for updates, DELETE for deletes.

Non-CRUD operations — actions that trigger side effects or state changes rather than simply modifying a resource — use POST to /actions/ sub-paths. For example, triggering a re-analysis is POST /api/identities/{id}/actions/analyze, and changing your password is POST /api/account/actions/change-password. This convention makes it clear when you are performing a simple data operation versus triggering something more significant.

Response objects use V1 wrapper types rather than exposing internal data models directly. This means the API contract is stable and only includes the data you need — no sensitive internal fields leak through.

Interactive Documentation

Full OpenAPI (Swagger) documentation is available upon request. It is the fastest way to understand the API and test your integrations during development.

Please contact dregs@dregs.com to request additional API documentation and guidance to speed up your integration.