The REST API

Most of what you do in the dashboard, you can do programmatically. The Dregs REST API covers identities, events, scores, escalations, and configuration, while team members, credentials, and billing stay in the dashboard. Build custom integrations, automate workflows, and embed fraud intelligence directly into your application.

Authentication

The public API authenticates with one of your API credential's keys in the Authorization header. Your server-side calls use the secret key; the tracking script uses the public key, and only on the two routes that accept it.

Customer Secret Keys

A credential's secret key starts with sk_. Create one under Settings → Credentials and keep it on your server, because it acts as an admin of that credential's team. Send it on each request:

Authorization: Bearer sk_your_secret_key_here

The operations you can call this way are listed in the public OpenAPI document.

Don't confuse the secret key with a webhook signing secret. Your API credential's secret key authenticates your requests to the Dregs API, while a webhook channel's signing secret lets you verify that incoming webhook payloads came from Dregs. See Webhooks for details on signature verification.

Customer Public Keys

A credential's public key starts with pk_. It's the key you embed in the tracking script. Send it the same way:

Authorization: Bearer pk_your_public_key_here

A public key is accepted on POST /api/events and on GET /api/devices/{fingerprint}. Every other route in the public document expects the secret key.

MCP Tokens

MCP tokens (they start with dmcp_) authenticate AI agents at the Dregs MCP server only. You create them under Settings → AI Agents. They act as the user who created them within that team, and are refused by every REST endpoint, so a token issued to an agent cannot be turned into API access. Agents that support OAuth do not need one.

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, authenticated with the public key. Your backend can send the same request with the secret key. Reading events via GET /api/events requires the secret key and returns a paginated, filterable list of tracked events for your account.

Ingestion reports its outcome with the HTTP status code: 200 when the event is accepted, 400 for a malformed body or an event carrying neither an identity nor a device, 401 for an unrecognized key, 402 when the account is over its monthly event limit, and 429 when the credential exceeds its ingestion rate limit. A few rejections are deliberately quiet: an event from an origin the public key does not allow, one carrying a malformed device signature, or one whose client-supplied id fails validation (longer than 64 characters, or starting with dregs-), returns 200 with a null id rather than telling the caller which check it failed.

Include an id in the body to make ingestion idempotent. Reposting the same id returns the original event instead of recording a second one, which makes a retry after a timeout safe. The value must be at most 64 characters and must not start with dregs-, which is reserved for identifiers Dregs generates.

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 your fraud decisions.

• GET /api/identities: paginated list with search and filtering
• GET /api/identities/{id}: full identity detail
• GET /api/identities/{id}/scores: the four current category scores
• GET /api/identities/{id}/analysis: the most recent analysis cycle, with the observations behind each score
• POST /api/identities/{id}/actions/analyze: trigger re-scoring

Groups

Groups are the organizations, companies, teams, workspaces, and other collectives your users belong to. They are created by events that carry groups; see Groups for the event format. A group is addressed by its type and ID.

• GET /api/groups: paginated list with member counts; filter by type, or by identity to list the groups one identity belongs to
• GET /api/groups/{type}/{id}: full group detail, including its data
• PATCH /api/groups/{type}/{id}: merge new attributes into a group
• PUT /api/groups/{type}/{id}/identities/{identityId}: add an identity to a group
• DELETE /api/groups/{type}/{id}/identities/{identityId}: remove an identity from a group

To list the members of a group, filter identities by it: GET /api/identities?group=team_42&groupType=team. Events take the same filter. When groupType is omitted it is organization.

Devices

List fingerprinted devices with the secret key, or fetch one device by fingerprint. GET /api/devices/{fingerprint} also accepts the public key, which is how the tracking script reads device info. Updating a device requires the secret key.

Escalations

List escalations with filtering by status, severity, and identity via GET /api/escalations. Get one escalation with GET /api/escalations/{id}, update its status (acknowledge or close) with PATCH /api/escalations/{id}, and retrieve summary counts with GET /api/escalations/summary. These endpoints let you build triage workflows outside the dashboard.

Escalation Rules and Badge Rules

The API offers full CRUD for escalation rules at /api/escalation-rules and for badge rules at /api/badge-rules. Escalation rules open escalations when scores or badges match conditions you define, and badge rules 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 an integration, and 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. Use it to build custom dashboards or to feed Dregs data into your 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

Team membership, invitations, and API credentials are managed in the dashboard, under Settings → Team and Settings → Credentials. Those routes are tied to a signed-in dashboard session and are not part of the published OpenAPI. Create a secret key there, then call the API with it.

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. For groups, it searches identifier and name.

Structured filters are also available. Identity endpoints accept score range parameters and a group filter. Event endpoints accept identity, group, and fingerprint filters. Escalation endpoints accept status and severity filters. Filters combine freely, so you can use several 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. Triggering a re-analysis is POST /api/identities/{id}/actions/analyze. This convention distinguishes a plain data operation from a more significant action.

Responses use versioned V1 types rather than Dregs's internal data models, so the contract you code against stays stable and includes only the data you need, with no sensitive internal fields.

Response Examples

The following examples show the JSON response structure for common endpoints. Authenticated requests send Authorization: Bearer followed by the secret key. The two routes that also accept a public key are called out above.

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

GET /api/identities/{id}/scores returns the four current category scores. This is the cheap read, and it is the one most integrations want: it reports the persisted scores without recomputing anything.

[
  {"category": "HUMANITY", "value": 85},
  {"category": "AUTHENTICITY", "value": 72},
  {"category": "UNIQUENESS", "value": 91},
  {"category": "BEHAVIOR", "value": 68}
]

Each value is an integer from 0 to 100. A category is omitted entirely until the identity has been scored in that category, so an identity that has never been analyzed returns an empty array.

Analysis with Observations

GET /api/identities/{id}/analysis returns the most recent analysis cycle, including the individual analyzer observations that produced each score. Use this endpoint when you need to see exactly why an identity received its scores. It returns 404 when the identity has not been analyzed yet.

{
  "id": 2000871,
  "identityId": "user_12345",
  "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": [ ... ]}
  ],
  "humanityScore": 85,
  "authenticityScore": 72,
  "uniquenessScore": 91,
  "behaviorScore": 68,
  "eventCount": 47,
  "deviceCount": 2,
  "durationMillis": 312,
  "startedAt": "2026-09-21T14:22:09Z",
  "finishedAt": "2026-09-21T14:22:09Z"
}

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

The curated public API is an OpenAPI 3 document at https://dregs.com/api/openapi.json. It lists the operations you call with a secret key: events, identities, scores, devices, escalations, badge rules, channels, datasets, mappings, and the dashboard summaries. Each operation has an operationId, a description, and typed parameters and responses. Authenticate with Authorization: Bearer sk_ followed by the secret key from Settings → Credentials (OpenAPI scheme secretKey). POST /api/events and GET /api/devices/{fingerprint} also accept the public key (scheme publicKey, Bearer pk_).

That document is the customer API you call with your keys. It doesn't include dashboard sign-in, billing, team and credential management, or the trainer tools Dregs staff use, and the full internal specification isn't published. For help beyond the document, contact dregs@dregs.com.