# Overview

DOSafe is the safety and threat intelligence engine for the DOS ecosystem. It aggregates data from **19+ sources** with over **3.93 million threat intelligence entries** to provide real-time risk assessments for entities such as domains, URLs, wallets, phone numbers, and more.

## Key Capabilities

* **Entity check** -- Assess the risk of a single entity against the threat intelligence database, on-chain attestations, and DOS.Me identity data.
* **Bulk check** -- Evaluate up to 50 entities in a single request.
* **URL check** -- Analyze a URL for phishing, scam, and malware indicators.
* **AI text detection** -- Determine whether a piece of text was generated by AI.
* **AI image detection** -- Determine whether an image was generated or manipulated by AI.

## Supported Entity Types

| Type           | Example                  |
| -------------- | ------------------------ |
| `domain`       | `evil.com`               |
| `url`          | `https://evil.com/phish` |
| `wallet`       | `0xdeadbeef...`          |
| `phone`        | `+84901234567`           |
| `bank_account` | `VCB:1234567890`         |
| `email`        | `scammer@evil.com`       |
| `facebook`     | `fakeshop.vn`            |

## API Endpoints

All DOSafe endpoints use the base URL `https://api.dos.ai/v1/dosafe`.

| Method | Endpoint                  | Description                |
| ------ | ------------------------- | -------------------------- |
| POST   | `/v1/dosafe/check`        | Single entity safety check |
| POST   | `/v1/dosafe/check/bulk`   | Bulk entity check (max 50) |
| POST   | `/v1/dosafe/url-check`    | URL/domain safety check    |
| POST   | `/v1/dosafe/detect`       | AI text detection          |
| POST   | `/v1/dosafe/detect-image` | AI image detection         |

## Authentication

DOSafe endpoints accept authentication via the `X-Api-Key` header:

```
X-Api-Key: your_api_key_here
```

Alternatively, if you already have a DOS AI API key (`dos_sk_*`), you can use the standard `Authorization` header:

```
Authorization: Bearer dos_sk_...
```

Anonymous access is available with a limited daily quota for evaluation purposes.

## Risk Scoring

Risk scores range from 0 to 100 and map to the following levels:

| Score   | Level      |
| ------- | ---------- |
| 0--19   | `safe`     |
| 20--49  | `low`      |
| 50--74  | `medium`   |
| 75--89  | `high`     |
| 90--100 | `critical` |

Scores are computed by weighted aggregation of signals from multiple data sources. No single source determines the final verdict.

### Data Sources

| Source           | Description                                                                |
| ---------------- | -------------------------------------------------------------------------- |
| DOSafe Threat DB | 3.93M+ entries from 19 scrapers covering phishing, scam, malware, and spam |
| DOS Chain        | Immutable on-chain risk attestations via EAS                               |
| DOS.Me Identity  | Member trust scores, verified providers, and flagged status                |
| Web Analysis     | Real-time web search and LLM-powered risk analysis                         |

## Quick Example

### Check an entity

```bash
curl -X POST https://api.dos.ai/v1/dosafe/check \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "domain",
    "entityId": "suspicious-site.com"
  }'
```

**Response:**

```json
{
  "entityType": "domain",
  "entityId": "suspicious-site.com",
  "riskScore": 85,
  "riskLevel": "high",
  "flagged": true,
  "signals": ["db_flagged_phishing"],
  "categories": ["phishing"],
  "sources": ["phishing_database"],
  "checkedAt": "2026-03-24T10:00:00Z"
}
```

### Check a URL

```bash
curl -X POST https://api.dos.ai/v1/dosafe/url-check \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://suspicious-site.com/login"
  }'
```

### Bulk check

```bash
curl -X POST https://api.dos.ai/v1/dosafe/check/bulk \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": [
      { "entityType": "wallet", "entityId": "0xdeadbeef..." },
      { "entityType": "phone", "entityId": "+84901234567" }
    ]
  }'
```

## Next Steps

* [DOSafe Partner API Reference](https://docs.dos.ai/dosafe/partner-api) -- Full endpoint documentation with request/response schemas and signal reference.
* [Error Codes](https://docs.dos.ai/support/error-codes) -- Common error responses and how to handle them.