API Reference

Base URL: https://api.dbblprotocol.org

All endpoints return JSON. All authenticated endpoints require a Bearer token. Timestamps are ISO 8601 UTC.

Authentication

All endpoints except GET /v1/health and POST /v1/platforms/register require a Bearer token obtained when your platform registered.

Authorization: Bearer dbbl_<your-api-key>

Returns API status. No authentication required. Use for uptime monitoring.

{"status": "ok",
 "version": "1",
 "timestamp": "2025-06-04T12:00:00.000Z"}

Register a new platform. Returns a one-time API key — store it immediately, it cannot be retrieved again. No authentication required.

Request Body

{"name": "Jaydslist",
 "website": "https://jaydslist.com",
 "contactEmail": "admin@jaydslist.com"}

Response 201

{"success": true,
 "platformId": "plat_01abc...",
 "apiKey": "dbbl_abc123...",
 "tier": "provisional",
 "status": "active"}

Query the risk score for an identity. At least one signal is required. Signals are checked in order: phone → email → username (exact) → username (fuzzy).

Scores are cached for 60 seconds on hit, 30 seconds on no-data. Every query is logged regardless of cache state.

Query Parameters

{"status": "no_data",
 "clean": true,
 "score": null,
 "rating": null,
 "confidence": null,
 "dimensional": null,
 "platforms": null,
 "matchedSignals": []}

{"status": "found",
 "clean": false,
 "score": 42.3,
 "rating": "cautioned",
 "confidence": "medium",
 "matchedSignals": ["phone"],
 "dimensional": {"unsolicited_dm": 10.0,
   "harassment": 55.2,
   "fake_profile": 0.0,
   "explicit_content": 20.1,
   "spam": 5.0},
 "reportCount": 3,
 "firstSeen": "2024-01-15T...",
 "lastReported": "2025-03-22T...",
 "platforms": [{"name": "Jaydslist",
   "website": "https://jaydslist.com"}]}

Submit a confirmed violation. Only submit violations your platform has already acted on — reports feed directly into scoring without review. Score is recalculated synchronously on submission.

Request Body

{"phoneHash": "a8f2c3e1b4d5...",    // optional — at least one signal required
 "emailHash": "7f3d9b2a1c4e...",    // optional
 "username": "baduser99",            // optional — stored normalized
 "usernameType": "username",         // username | display_name | real_name | nickname
 "violationCategory": "harassment",  // see categories below
 "severity": "high",                 // low | medium | high | critical
 "additionalContext": "..."          // optional, max 1000 chars — for reviewers only, never exposed via API}

Response 201

{"success": true,
 "reportId": "rep_01abc...",
 "identityId": "idr_01xyz...",
 "updatedScore": {"score": 55.1,
   "rating": "restricted",
   "confidence": "medium"}}  

Violation Categories

Error Codes