The REST API

Everything you 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 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. Dregs also invalidates tokens when the user changes their password or their account is disabled.

Customer Public Keys

Used by the tracking script and device-related endpoints. Send the public key from your API credentials 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 pk_your_public_key_here

Customer Secret Keys

For server-side integrations that need full API access, use your credential's secret key (starts with sk_). Secret keys authenticate as the credential's customer account and grant access to all authenticated endpoints. Include the key as a Bearer token:

Authorization: Bearer sk_your_secret_key_here

Secret keys are separate from webhook signing secrets. Your API credential's secret key authenticates requests to the Dregs API. A webhook channel's signing secret verifies that incoming webhook payloads come from Dregs. These are different values serving different purposes. See Webhooks for details on signature verification.

Key Endpoint Groups

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

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 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 — they expose 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 with observations
• 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; 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 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 label identities automatically. Creating, updating, and deleting rules requires the Admin role.

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 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 items, total 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 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 — use multiple filters in a single request to narrow 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 modify 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 distinguishes a plain data operation from a more significant action.

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

Response Examples

The following examples show the JSON response structure for common endpoints. All authenticated requests require a Bearer token (JWT or secret key) in the Authorization header.

Identity Detail

GET /api/identities/{id} returns the identity's profile, current scores, badges, and timestamps. Scores are integers from 0 to 100, or null if the identity hasn't been scored yet.

{
  "id": "user_12345",
  "displayName": "Jane Cooper",
  "displayEmail": "jane@example.com",
  "displayUsername": "janecooper",
  "humanityScore": 85,
  "authenticityScore": 72,
  "uniquenessScore": 91,
  "behaviorScore": 68,
  "createdAt": "2025-11-15T08:30:00Z",
  "updatedAt": "2026-01-20T14:15:30Z",
  "lastTrackedAt": "2026-01-20T14:15:30Z",
  "lastScoredAt": "2026-01-20T14:15:32Z",
  "disregarded": false,
  "badges": [
    {
      "name": "Trusted User",
      "type": "GOOD"
    }
  ],
  "data": {
    "plan": "pro",
    "company": "Acme Inc"
  }
}

Scores with Observations

GET /api/identities/{id}/scores returns the four category scores along with the individual analyzer observations that produced each score. Use this endpoint when you need the full breakdown of why an identity received its scores.

[
  {
    "category": "HUMANITY",
    "value": 85,
    "observations": [
      {
        "category": "HUMANITY",
        "id": "humanity.user-agent",
        "label": "User Agent Analysis",
        "explanation": "Browser fingerprint consistent with standard Chrome on macOS",
        "value": 0.92,
        "confidence": 0.85,
        "weight": 0.85,
        "metadata": {
          "browser": "Chrome",
          "platform": "macOS",
          "isHeadless": false
        }
      },
      {
        "category": "HUMANITY",
        "id": "humanity.event-timing",
        "label": "Event Timing Analysis",
        "explanation": "Event intervals show natural human variation",
        "value": 0.78,
        "confidence": 0.72,
        "weight": 0.72,
        "metadata": {
          "medianInterval": 4200,
          "eventCount": 47
        }
      }
    ]
  },
  {
    "category": "AUTHENTICITY",
    "value": 72,
    "observations": [ ... ]
  },
  {
    "category": "UNIQUENESS",
    "value": 91,
    "observations": [ ... ]
  },
  {
    "category": "BEHAVIOR",
    "value": 68,
    "observations": [ ... ]
  }
]

The response is an array of four score objects, one per category. Each category's value is an integer (0-100) computed as a weighted average of its observations, with confidence as the weight. Observation value and confidence are decimals between 0.0 and 1.0.

Paginated Lists

All list endpoints (GET /api/identities, GET /api/events, GET /api/devices, etc.) return a consistent page structure:

{
  "content": [ ... ],
  "pageNumber": 0,
  "pageSize": 25,
  "totalElements": 1482,
  "totalPages": 60
}

Interactive Documentation

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

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