Documentation

API Reference

Base URL https://api.phishmind.com

Auth X-API-Key: pm_...

Format JSON

Interactive Swagger UI

Quick Start

Analyze your first URL in under a minute.

Get your API key

Submit a URL

POST to /api/v1/analyze with the URL and options. You'll get back an analysis ID.

Poll for results

GET /api/v1/results/{id} until status is complete. Typical analysis takes 8-15 seconds.

curl -X POST https://api.phishmind.com/api/v1/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pm_live_abc123" \
  -d '{
    "url": "https://suspicious-link.com/login",
    "reflow": true
  }'

import requests

resp = requests.post(
    "https://api.phishmind.com/api/v1/analyze",
    headers={"X-API-Key": "pm_live_abc123"},
    json={
        "url": "https://suspicious-link.com/login",
        "reflow": True,
    },
)
data = resp.json()
print(f"Analysis ID: {data['id']}")

# Poll for results
import time
while True:
    result = requests.get(
        f"https://api.phishmind.com/api/v1/results/{data['id']}",
        headers={"X-API-Key": "pm_live_abc123"},
    ).json()
    if result["status"] == "complete":
        print(f"Verdict: {result['verdict']} ({result['confidence']}%)")
        break
    time.sleep(2)

const resp = await fetch("https://api.phishmind.com/api/v1/analyze", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "pm_live_abc123",
  },
  body: JSON.stringify({
    url: "https://suspicious-link.com/login",
    reflow: true,
  }),
});
const { id } = await resp.json();
console.log(`Analysis ID: ${id}`);

// Poll for results
let result;
do {
  await new Promise((r) => setTimeout(r, 2000));
  const res = await fetch(
    `https://api.phishmind.com/api/v1/results/${id}`,
    { headers: { "X-API-Key": "pm_live_abc123" } }
  );
  result = await res.json();
} while (result.status !== "complete");

console.log(`Verdict: ${result.verdict} (${result.confidence}%)`);

Endpoints

POST /api/v1/analyze

Submit a URL for analysis

Request Body

{
  "url": "https://suspicious-link.com/login",
  "reflow": true,
  "reflow_language": "en",
  "reflow_audience": "non-technical"
}

Response 202

{
  "id": "a7f3c2e1-8b4d-4f6a-9c3e-1d2e3f4a5b6c",
  "status": "pending",
  "estimated_seconds": 12
}

POST /api/v1/analyze/email

Submit an .eml file for email analysis

Request Body

multipart/form-data
  file: message.eml
  reflow: true

Response 202

{
  "id": "b8c4d3e2-9a5f-4e7b-8d2c-3e4f5a6b7c8d",
  "input_type": "email",
  "status": "pending"
}

GET /api/v1/results/{id}

Get analysis results with verdict, indicators, and reasoning

Response 200

{
  "id": "a7f3c2e1-...",
  "verdict": "malicious",
  "confidence": 94,
  "category": "credential_harvesting",
  "brand": "Microsoft 365",
  "indicators": [
    {"label": "Brand impersonation", "severity": "critical"},
    {"label": "Domain age: 2 days", "severity": "critical"}
  ],
  "artifacts": ["screenshot", "dom", "har", "trace"]
}

GET /api/v1/reflow/{id}

Get human-facing Reflow explanation (requires reflow: true on submit)

Response 200

{
  "markdown_content": "## This link is dangerous\n\nThe link leads to a fake...",
  "html_content": "<h2>This link is dangerous</h2>...",
  "language": "en",
  "audience": "non-technical"
}

GET /api/v1/trace/{id}

Get Flow Trace — visual replay timeline of the browser session

Response 200

{
  "steps": [
    {"t": 0, "action": "navigate", "url": "https://..."},
    {"t": 1200, "action": "redirect", "url": "https://..."},
    {"t": 4800, "action": "screenshot", "bytes": 48210}
  ],
  "duration_ms": 8200
}

GET /api/v1/usage

Get current usage stats for your API key

Response 200

{
  "api_key_prefix": "pm_abc12345",
  "today": 12,
  "this_month": 84
}

Rate Limits

All endpoints are rate-limited per API key. Limits vary by plan.

Plan	Requests/min	Analyses/month	Concurrent
Free	10	5	1
Starter	30	25	3
Professional	60	100	5
Business	120	350	10
Enterprise	Custom	1,000+	Custom

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. If you exceed the limit, you'll receive a 429 with a Retry-After header.

Error Codes

All errors return a JSON body with error and message fields.

400

Bad Request

Invalid URL format or missing required fields.

401

Unauthorized

Missing or invalid API key.

403

Forbidden

API key does not have access to this resource.

404

Not Found

Analysis ID does not exist or has expired.

409

Conflict

Analysis is still in progress. Poll again shortly.

429

Too Many Requests

Rate limit exceeded. Check Retry-After header.

500

Internal Error

Unexpected error — contact support if persistent.

Authentication

Include your API key in the X-API-Key header on every request.

X-API-Key: pm_live_abc123def456

Key types: pm_live_* for production, pm_test_* for sandbox (no billing, mock verdicts).

Rotate keys at any time from your dashboard settings. Revoked keys stop working immediately.

Webhooks

Instead of polling, configure a webhook URL in your dashboard. PhishMind will POST the full result payload when analysis completes.

POST https://your-app.com/webhooks/phishmind
Content-Type: application/json
X-PhishMind-Signature: sha256=abc123...

{
  "event": "analysis.complete",
  "data": {
    "id": "a7f3c2e1-...",
    "verdict": "malicious",
    "confidence": 94,
    ...
  }
}

Verify webhook signatures using the X-PhishMind-Signature header with your webhook secret. Available on Starter plans and above.