SIDEX/Docs
Documentation

API Documentation

Complete guide for using SIDEX API for URL security scanning and analysis with 6-dimension response structure.

Authentication

API Key Format

API keys follow the format: sidx_8chars_64hexhash

Authorization Header

Authorization: Bearer sidx_YOUR_API_KEY

Permissions (Scopes)

read_only

Read Only Access

View and list scans (GET requests only)

read_and_write

Read & Write Access

Create, view, and delete scans (full access)

Rate Limiting

Single Scan

60 requests per minute

Bulk Scan

10 requests per minute

Rate limit headers are included in all responses:

  • X-RateLimit-Limit - Maximum requests
  • X-RateLimit-Remaining - Remaining requests
  • X-RateLimit-Reset - Reset time (Unix timestamp)

Response Structure

6-Dimension Response Format

All scan responses return data organized into 6 dimensions. The availability of dimensions depends on your subscription plan.

security

Threat level, SSL analysis, brand impersonation, risk factors

business

Company information, industry classification, business type

technical

HTTP status, IP addresses, ASN, content type

content

Page title, meta description, forms, content analysis

trust

Domain age, SSL validation, original domain

insight

AI summary, confidence score, recommendations

Note: Dimensions not included in your subscription plan will return as null.

Endpoints

POST/api/v1/scans

Create Single Scan

Create a new URL security scan.

Required Permission: read_and_write

Parameters

urlstringrequired

The URL to scan (must be a valid URL)

scanTypestring

Type of scan: "quick" (default) or "deep"

timeoutnumber

Scan timeout in seconds (default: 30, max: 300)

Request Body

{
  "url": "https://example.com",
  "scanType": "quick",
  "timeout": 30
}

Response

{
  "msg": "Quick scan started successfully",
  "data": {
    "linkId": "uuid-string",
    "status": "pending",
    "scanType": "quick",
    "estimatedDuration": 30000
  }
}

cURL Example

curl -X POST http://localhost:3007/api/v1/scans \
  -H "Authorization: Bearer sidx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "scanType": "quick",
    "timeout": 30
  }'
POST/api/v1/bulk

Create Bulk Scans

Scan multiple URLs in a single request (max 100 URLs).

Required Permission: read_and_write

Parameters

urlsstring[]required

Array of URLs to scan (1-100 URLs)

scanTypestring

Type of scan: "quick" (default) or "deep"

timeoutnumber

Scan timeout in seconds (default: 30, max: 300)

Request Body

{
  "urls": [
    "https://example.com",
    "https://another.com"
  ],
  "scanType": "quick",
  "timeout": 30
}

Response

{
  "msg": "Quick scan started for 2 URL(s)",
  "data": {
    "totalRequested": 2,
    "totalQueued": 2,
    "scanType": "quick",
    "estimatedDuration": 30000,
    "links": [
      {
        "linkId": "uuid-string",
        "url": "https://example.com",
        "status": "pending"
      }
    ]
  }
}

cURL Example

curl -X POST http://localhost:3007/api/v1/bulk \
  -H "Authorization: Bearer sidx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://another.com"
    ],
    "scanType": "quick",
    "timeout": 30
  }'
GET/api/v1/scans

List Scans

Retrieve all scans with optional filtering and pagination.

Parameters

pagenumber

Page number (default: 1)

perPagenumber

Results per page (default: 10)

qstring

Search by URL or domain

statusstring

Filter by status: pending, scanning, completed, failed

threatLevelstring

Filter by threat level: critical, high, medium, low, none

dateFromstring

ISO 8601 date filter (from)

dateTostring

ISO 8601 date filter (to)

Response

{
  "data": [
    {
      "id": "scan-id",
      "url": "https://example.com",
      "domain": "example.com",
      "status": "completed",
      "scanType": "quick",
      "timeout": 30,
      "redirectChain": [],
      "security": {
        "treatLevel": "low",
        "threatScore": 15,
        "threats": [],
        "ssl": {
          "valid": true,
          "issuer": "Let's Encrypt",
          "expiryDays": 89
        },
        "brandImpersonation": {
          "risk": "none"
        },
        "riskFactors": []
      },
      "business": {
        "category": "technology",
        "companyName": "Example Corp",
        "businessType": "corporate",
        "industryClassification": "software"
      },
      "technical": {
        "httpStatusCode": 200,
        "contentType": "text/html",
        "ipAddresses": [
          "192.168.1.1"
        ],
        "ipCountry": "US",
        "asn": "AS12345"
      },
      "content": {
        "pageTitle": "Example Website",
        "metaDescription": "This is an example website",
        "forms": [],
        "gambling": false,
        "adult": false
      },
      "trust": {
        "ssl": {
          "valid": true,
          "issuer": "Let's Encrypt"
        },
        "domain": {
          "age": 10,
          "ageDays": 3652
        },
        "originalDomain": "example.com"
      },
      "insight": {
        "summary": "The website appears safe and legitimate",
        "confidence": 0.95,
        "riskAssessment": "low",
        "keyFindings": [
          "Valid SSL certificate",
          "No security threats detected"
        ],
        "recommendations": [
          "No action required"
        ]
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:35:00Z",
      "completedAt": "2024-01-15T10:35:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "perPage": 10,
    "pages": 15
  }
}

cURL Example

curl -X GET "http://localhost:3007/api/v1/scans?page=1&perPage=10&status=completed" \
  -H "Authorization: Bearer sidx_YOUR_API_KEY"
GET/api/v1/scans/:id

Get Scan Details

Retrieve detailed information about a specific scan.

Parameters

idstringrequired

The scan ID (UUID)

Response

{
  "data": {
    "id": "scan-id",
    "url": "https://example.com",
    "domain": "example.com",
    "status": "completed",
    "scanType": "quick",
    "timeout": 30,
    "redirectChain": [],
    "security": {
      "treatLevel": "low",
      "threatScore": 15,
      "threats": [],
      "ssl": {
        "valid": true,
        "issuer": "Let's Encrypt",
        "expiryDays": 89
      },
      "brandImpersonation": {
        "risk": "none"
      },
      "riskFactors": []
    },
    "business": {
      "category": "technology",
      "companyName": "Example Corp",
      "businessType": "corporate",
      "industryClassification": "software"
    },
    "technical": {
      "httpStatusCode": 200,
      "contentType": "text/html",
      "ipAddresses": [
        "192.168.1.1"
      ],
      "ipCountry": "US",
      "asn": "AS12345"
    },
    "content": {
      "pageTitle": "Example Website",
      "metaDescription": "This is an example website",
      "forms": [],
      "gambling": false,
      "adult": false
    },
    "trust": {
      "ssl": {
        "valid": true,
        "issuer": "Let's Encrypt"
      },
      "domain": {
        "age": 10,
        "ageDays": 3652
      },
      "originalDomain": "example.com"
    },
    "insight": {
      "summary": "The website appears safe and legitimate",
      "confidence": 0.95,
      "riskAssessment": "low",
      "keyFindings": [
        "Valid SSL certificate",
        "No security threats detected"
      ],
      "recommendations": [
        "No action required"
      ]
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:00Z",
    "completedAt": "2024-01-15T10:35:00Z"
  }
}

cURL Example

curl -X GET http://localhost:3007/api/v1/scans/scan-uuid \
  -H "Authorization: Bearer sidx_YOUR_API_KEY"
DELETE/api/v1/scans/:id

Delete Scan

Delete a scan. Only pending scans can be deleted.

Required Permission: read_and_write

Parameters

idstringrequired

The scan ID (UUID)

Response

{
  "msg": "Scan deleted successfully",
  "data": {
    "linkId": "scan-id"
  }
}

cURL Example

curl -X DELETE http://localhost:3007/api/v1/scans/scan-uuid \
  -H "Authorization: Bearer sidx_YOUR_API_KEY"

HTTP Status Codes

200

OK

Request successful

400

Bad Request

Invalid parameters or validation failed

401

Unauthorized

Missing or invalid API key

403

Forbidden

Insufficient permissions for this resource

429

Too Many Requests

Rate limit exceeded. Check Retry-After header

500

Server Error

Internal server error

For support or questions, please contact our team.