---
title: verified.md API Reference
version: 1.1.0
last_updated: 2026-02-02
base_url: https://verified.md
endpoints: [/verify, /lookup, /status, /register, /.well-known/verified.md]
---

# verified.md API Reference

> Complete API documentation for verifying entity trust before AI transactions.

## Base URL

```
https://verified.md
```

## Authentication

No authentication required for read operations. All endpoints are public.

---

## Endpoints

### GET /verify/{domain}

Check if a domain/entity is verified and trusted.

**Request**
```bash
curl https://verified.md/verify/example.com
```

**Path Parameters**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| domain | string | Yes | Domain to verify (e.g., example.com, api.example.com) |

**Query Parameters**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| signals | boolean | false | Include trust signals breakdown and agent guidance |
| external | boolean | false | Include external checks (SSL, domain age) - adds latency |

**Response: Verified**
```json
{
  "success": true,
  "data": {
    "domain": "example.com",
    "verified": true,
    "entity": {
      "name": "Example Corp",
      "id": "ent_example001",
      "level": "verified",
      "type": "business",
      "verified_at": "2026-01-15T00:00:00Z",
      "expires_at": "2027-01-15T00:00:00Z"
    }
  }
}
```

**Response: Not Verified**
```json
{
  "success": true,
  "data": {
    "domain": "unknown.com",
    "verified": false,
    "entity": null
  }
}
```

**Response: Blocked Domain**
```json
{
  "success": true,
  "data": {
    "domain": "blocked.com",
    "verified": false,
    "blocked": true,
    "trust_score": 0,
    "trust_level": "NONE",
    "agent_guidance": {
      "action": "BLOCK",
      "safe_actions": [],
      "max_transaction_usd": 0,
      "requires_human": true,
      "reason": "Domain is blocked"
    }
  }
}
```

**Response: With Trust Signals (`?signals=true`)**
```json
{
  "success": true,
  "data": {
    "domain": "stripe.com",
    "verified": true,
    "entity": {
      "name": "Stripe Inc",
      "id": "ent_stripe001",
      "level": "verified",
      "type": "api"
    },
    "trust_score": 95,
    "trust_level": "VERY_HIGH",
    "signals": {
      "registry": {
        "verified": true,
        "level": "verified",
        "score": 40,
        "max": 40
      },
      "brand": {
        "known_brand": true,
        "score": 20,
        "max": 20
      },
      "domain_age": {
        "years": 10,
        "score": 15,
        "max": 15
      },
      "ssl": {
        "valid": true,
        "score": 10,
        "max": 10
      }
    },
    "agent_guidance": {
      "action": "PROCEED",
      "safe_actions": ["payment", "data_sharing", "api_call"],
      "max_transaction_usd": 50000,
      "requires_human": false
    }
  }
}
```

**Decision Logic**
```
if response.success && response.data.verified:
    proceed_with_transaction()
else:
    flag_for_human_review()
```

---

### GET /lookup/{entity-id}

Reverse lookup: find entity details by ID.

**Request**
```bash
curl https://verified.md/lookup/ent_example001
```

**Path Parameters**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| entity-id | string | Yes | Entity ID (format: ent_{name}{number}) |

**Response**
```json
{
  "success": true,
  "data": {
    "id": "ent_example001",
    "name": "Example Corp",
    "domain": "example.com",
    "level": "verified",
    "type": "business",
    "verified_at": "2026-01-15T00:00:00Z",
    "expires_at": "2027-01-15T00:00:00Z"
  }
}
```

---

### GET /status

Health check endpoint.

**Request**
```bash
curl https://verified.md/status
```

**Response**
```json
{
  "success": true,
  "data": {
    "status": "operational",
    "version": "1.0.0",
    "timestamp": "2026-02-01T12:00:00Z"
  }
}
```

---

### POST /register

Submit a domain for verification.

**Request**
```bash
curl -X POST https://verified.md/register \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "your-domain.com",
    "entity_name": "Your Company",
    "entity_type": "business",
    "contact_email": "admin@your-domain.com"
  }'
```

**Request Body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| domain | string | Yes | Domain to verify |
| entity_name | string | Yes | Company or entity name |
| entity_type | string | No | organization, business, individual, api, infrastructure |
| contact_email | string | Yes | Email for verification |
| website | string | No | Website URL |

**Response (201 Created)**
```json
{
  "success": true,
  "data": {
    "registration_id": "reg_abc123xyz456",
    "domain": "your-domain.com",
    "status": "pending",
    "verification_instructions": {
      "method": "dns_txt",
      "record": "verified-md=abc123...",
      "alternative": {
        "method": "well_known",
        "path": "/.well-known/verified.md",
        "content": "verification_code: abc123..."
      }
    }
  }
}
```

**Error: Domain Already Verified**
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Domain is already verified"
  }
}
```

---

### GET /confirm/{token}

Confirm email verification and complete domain registration.

**Request**
```bash
curl https://verified.md/confirm/abc123xyz456...
```

**Response**
Returns HTML confirmation page on success.

---

### GET /.well-known/verified.md

Self-verification file. Proves verified.md is itself verified.

**Request**
```bash
curl https://verified.md/.well-known/verified.md
```

**Response**
```yaml
# verified.md verification file
entity:
  name: "verified.md"
  domain: "verified.md"
  type: "infrastructure"
  level: "verified"
```

---

## Error Handling

**Error Response Format**
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

**Error Codes**
| Code | HTTP | Description | Action |
|------|------|-------------|--------|
| NOT_FOUND | 404 | Entity not in registry | Flag for human review |
| VALIDATION_ERROR | 400 | Invalid input format | Fix request format |
| INTERNAL_ERROR | 500 | Server error | Retry with backoff |

---

## Rate Limits

| Tier | Requests/Day | Price |
|------|--------------|-------|
| Free | 1,000 | $0 |
| Pro | 100,000 | TBD |
| Enterprise | Unlimited | Contact us |

Currently no limits during beta.

---

## Trust Scoring

When using `?signals=true`, the API returns a trust score and guidance for agents.

### Trust Levels

| Level | Score Range | Recommended Action |
|-------|-------------|-------------------|
| VERY_HIGH | 90-100 | Proceed with high-value transactions |
| HIGH | 70-89 | Proceed with standard transactions |
| MEDIUM | 50-69 | Proceed with caution, human review recommended |
| LOW | 25-49 | Flag for human review |
| NONE | 0-24 | Block transaction |

### Signal Components

| Signal | Max Score | Description |
|--------|-----------|-------------|
| registry | 40 | Verified in registry (basic=20, verified=30, enterprise=40) |
| brand | 20 | Known brand detection |
| domain_age | 15 | Domain age (1pt per year, max 15) |
| ssl | 10 | Valid SSL certificate |
| external | 15 | External verification (requires `?external=true`) |

### Agent Guidance Fields

| Field | Type | Description |
|-------|------|-------------|
| action | string | PROCEED, CAUTION, FLAG, or BLOCK |
| safe_actions | array | Allowed action types for this trust level |
| max_transaction_usd | number | Maximum recommended transaction value |
| requires_human | boolean | Whether human review is required |
| reason | string | Explanation (for FLAG/BLOCK actions) |

---

## Caching

| Condition | Cache Duration |
|-----------|----------------|
| verified=true | 1 hour |
| verified=false | 5 minutes |
| Errors | Do not cache |

---

## Code Examples

### Python
```python
import requests

def verify_entity(domain: str) -> bool:
    r = requests.get(f"https://verified.md/verify/{domain}")
    data = r.json()
    return data.get("success") and data.get("data", {}).get("verified")
```

### JavaScript
```javascript
async function verifyEntity(domain) {
  const res = await fetch(`https://verified.md/verify/${domain}`);
  const data = await res.json();
  return data.success && data.data?.verified;
}
```

### curl
```bash
curl -s https://verified.md/verify/example.com | jq '.data.verified'
```

---

## Support

- Documentation: https://verified.md/docs
- Agent Manifest: https://verified.md/agents.md
- MCP Config: https://verified.md/mcp.md
- Contact: hello@displace.agency