Introduction

The TLINK PRO API is a RESTful API that lets you programmatically manage assets, alert rules, run threat intelligence tools, and retrieve results. All responses are JSON.

Base URL

https://api-pro.threatgrid.tech/api

All API responses follow this shape:

{
  "success": true,
  "data": { ... },       // present on success
  "message": "...",      // present on errors
  "meta": { ... }        // present on list endpoints (pagination, counts)
}

Authentication

TLINK PRO uses two authentication methods: Bearer tokens for user sessions and API keys for programmatic access.

Session tokens (login flow)

Call POST /api/auth/login to get an access token and refresh token.

curl -X POST https://api-pro.threatgrid.tech/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}'

The response includes accessToken (15-minute TTL) and refreshToken (30-day TTL). Pass the access token as a Bearer header on subsequent requests:

curl https://api-pro.threatgrid.tech/api/users/me \
  -H "Authorization: Bearer <accessToken>"

When the access token expires, refresh it:

curl -X POST https://api-pro.threatgrid.tech/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "<refreshToken>"}'

API keys

For automated workflows, create an API key in Dashboard → API Keys. Send it as a Bearer token in the Authorization header (keys start with tlk_):

curl https://api-pro.threatgrid.tech/api/orgs/{orgId}/assets \
  -H "Authorization: Bearer tlk_your_api_key_here"

Never commit API keys to source control. Rotate compromised keys immediately from the dashboard.

Rate Limits

Rate limits apply per API key or session token. Exceeded limits return 429 Too Many Requests.

Plan	Requests / minute	Tool runs / month
Free	30	100
Pro	120	5,000
Business	300	Unlimited
Enterprise	Custom	Unlimited

Retry-After and X-RateLimit-* headers are included in every response.

Assets

Assets represent entities you want to monitor — domains, IPs, emails, URLs, hashes, ASNs, or certificates.

GET

/api/orgs/{orgId}/assets

List all assets in the organization

Auth required

POST

/api/orgs/{orgId}/assets

Create a new asset

Auth required

GET

/api/orgs/{orgId}/assets/{assetId}

Get a single asset and its latest scan results

Auth required

PATCH

/api/orgs/{orgId}/assets/{assetId}

Update asset label or monitoring status

Auth required

DELETE

/api/orgs/{orgId}/assets/{assetId}

Delete an asset

Auth required

POST

/api/orgs/{orgId}/assets/{assetId}/monitor-now

Trigger an immediate check on this asset

Auth required

Create asset

curl -X POST https://api-pro.threatgrid.tech/api/orgs/{orgId}/assets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DOMAIN",
    "value": "example.com",
    "label": "Main site",
    "isMonitored": true
  }'

Request body

`type`required	string	DOMAIN, IP, EMAIL, URL, HASH, ASN, or CERTIFICATE
`value`required	string	The asset value (e.g. example.com, 1.2.3.4)
`label`	string	Optional human-readable label
`isMonitored`	boolean	Whether to enable continuous monitoring (default: false)

Alert Rules

Alert rules define conditions that trigger alerts when asset scan results match. Supports threshold, equality, contains, exists, and changed operators.

GET

/api/orgs/{orgId}/alert-rules

List all alert rules

Auth required

POST

/api/orgs/{orgId}/alert-rules

Create a new alert rule

Auth required

PATCH

/api/orgs/{orgId}/alert-rules/{ruleId}

Update rule (name, condition, enabled, etc.)

Auth required

DELETE

/api/orgs/{orgId}/alert-rules/{ruleId}

Delete a rule

Auth required

Create a rule

curl -X POST https://api-pro.threatgrid.tech/api/orgs/{orgId}/alert-rules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High abuse score",
    "condition": {
      "tool": "ip-reputation",
      "field": "summary.abuseScore",
      "operator": "gte",
      "value": 75
    },
    "severity": "HIGH",
    "notifyEmail": true,
    "notifyWebhook": false
  }'

Supported operators

gt / lt / gte / lte

Numeric comparisons

eq / neq

Equality checks

contains

String contains

exists

Field is present and truthy

changed

Value changed since last scan

Alerts

Alerts are triggered when a rule condition is met during a scheduled or manual asset scan.

GET

/api/orgs/{orgId}/alerts

List alerts (filterable by status, severity, assetId)

Auth required

GET

/api/orgs/{orgId}/alerts/{alertId}

Get alert details including triggering scan data

Auth required

PATCH

/api/orgs/{orgId}/alerts/{alertId}

Update alert status (OPEN → RESOLVED, ACKNOWLEDGED, etc.)

Auth required

List open alerts

curl "https://api-pro.threatgrid.tech/api/orgs/{orgId}/alerts?status=OPEN&severity=HIGH" \
  -H "Authorization: Bearer <token>"

Alert severities

CRITICALHIGHMEDIUMLOWINFO

Tool Runner

The Tool Runner lets you run threat intelligence scans against any target. Results are saved as reports and can trigger alert rules.

POST

/api/tools/{toolKey}

Run a tool against a target (returns results; saved as a report when orgId is set)

Auth required

GET

/api/tools/reports?orgId={orgId}

List all saved reports

Auth required

GET

/api/tools/reports/{reportId}?orgId={orgId}

Get a report and its full result data

Auth required

Available tools

dns

DNS lookup (A, NS, MX, CNAME, TXT)

whois

WHOIS registration data

ip-reputation

AbuseIPDB + VirusTotal IP check

email

MX, SPF, DMARC, HIBP breach check

exposure

Open ports, CVEs, risk score

ssl

SSL/TLS certificate analysis

threat-feed

OTX + GreyNoise threat feeds

Run a tool

curl -X POST https://api-pro.threatgrid.tech/api/tools/ip-reputation \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "1.2.3.4",
    "orgId": "{orgId}",
    "saveReport": true,
    "assetId": "optional-asset-id-to-link-result",
    "aiSummary": true
  }'

Set aiSummary to false to skip the AI analysis and get the raw result back faster.

Webhooks

TLINK PRO can POST events to your own endpoints. There are two ways to receive them:

Organization webhooks (Dashboard → Webhooks): pick the events you want and optionally set a secret so every request is signed.
Rule webhooks: set webhookUrl on an alert rule to get that rule's alert.triggered events. These are not signed.

Events

alert.triggered

An alert rule or anomaly check fired

alert.acknowledged

An alert was acknowledged

alert.resolved

An alert was resolved or marked a false positive

asset.created

An asset was added

asset.updated

An asset was changed

asset.deleted

An asset was removed

rule.created

An alert rule was added

rule.updated

An alert rule was changed

rule.deleted

An alert rule was removed

report.created

A tool report was saved (manual or monitoring)

vuln.created

A vulnerability was recorded

vuln.status_changed

A vulnerability changed status

breach.detected

A breach scan found exposed member accounts

webhook.test

Sent by the Test button

Payload

Every event uses the same envelope. The fields inside data depend on the event.

{
  "id": "6f1c2a9e-0b7d-4a51-9a63-2d8f3e1c7b40",
  "event": "alert.triggered",
  "orgId": "org_123",
  "createdAt": "2026-10-02T10:30:00.000Z",
  "data": {
    "alertId": "abc123",
    "title": "High abuse score on 1.2.3.4",
    "severity": "HIGH",
    "assetId": "asset789",
    "assetValue": "1.2.3.4",
    "ruleId": "rule456",
    "ruleName": "High abuse score",
    "triggeredAt": "2026-10-02T10:30:00.000Z"
  }
}

Use id to ignore duplicates. Respond with any 2xx status within 10 seconds.

Verifying signatures

When an organization webhook has a secret, each request carriesX-TLINK-Signature: sha256=<hex>, an HMAC-SHA256 of the raw request body using your secret. The event name is also sent in X-TLINK-Event.

import crypto from 'crypto'

function isValid(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return header && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}

Slack and Teams

TLINK PRO sends plain JSON. To post into Slack or Teams, point the webhook at a Slack workflow, Zapier or a small relay that reformats the message.

API Keys

API keys allow machine-to-machine access without user sessions. Manage them from Dashboard → API Keys.

GET

/api/orgs/{orgId}/api-keys

List the organization's API keys

Auth required

POST

/api/orgs/{orgId}/api-keys

Create a new API key (Admin/Owner)

Auth required

PATCH

/api/orgs/{orgId}/api-keys/{keyId}

Rename an API key (Admin/Owner)

Auth required

DELETE

/api/orgs/{orgId}/api-keys/{keyId}

Revoke an API key (Admin/Owner)

Auth required

Create an API key

curl -X POST https://api-pro.threatgrid.tech/api/orgs/{orgId}/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline key"}'

The full key value is only returned once at creation time. Store it securely. Subsequent requests will only show the key name and last-used timestamp.

Usage

# Send the key as a Bearer token
curl https://api-pro.threatgrid.tech/api/orgs/{orgId}/assets \
  -H "Authorization: Bearer tlk_xxxxxxxxxxxxxxxxxxxx"

Org Webhooks

Org Webhooks let you register persistent outbound endpoints that receive alert events from the whole organization. Unlike per-rule webhook URLs, org webhooks have a full CRUD API, delivery history, and a test-fire button.

GET

/api/orgs/{orgId}/webhooks

List all configured webhook endpoints

Auth required

POST

/api/orgs/{orgId}/webhooks

Create a new endpoint (Admin/Owner)

Auth required

PATCH

/api/orgs/{orgId}/webhooks/{id}

Update URL, name, or enabled state (Admin/Owner)

Auth required

DELETE

/api/orgs/{orgId}/webhooks/{id}

Delete an endpoint (Admin/Owner)

Auth required

POST

/api/orgs/{orgId}/webhooks/{id}/test

Send a test payload to the endpoint (Admin/Owner)

Auth required

GET

/api/orgs/{orgId}/webhooks/{id}/deliveries

View recent delivery log and HTTP response codes

Auth required

Create a webhook

curl -X POST https://api-pro.threatgrid.tech/api/orgs/{orgId}/webhooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack #security-alerts",
    "url": "https://hooks.slack.com/services/T.../B.../...",
    "enabled": true
  }'

Each delivery includes an X-TLINK-Signature HMAC-SHA256 header for payload verification. See the Alert Webhooks section for the payload shape.

Threat Feed

The Threat Feed aggregates platform-wide threat intelligence: CISA Known Exploited Vulnerabilities (KEV) and custom security bulletins published by Admiresty. All authenticated users can read; creating or managing bulletins requires a platform admin account.

GET

/api/threats

List threat bulletins — filterable by severity, tag, and search

Auth required

GET

/api/threats/cisa

CISA KEV feed (cached, refreshed daily)

Auth required

POST

/api/threats

Publish a bulletin (platform admin only)

Auth required

PATCH

/api/threats/{id}

Update a bulletin (platform admin only)

Auth required

DELETE

/api/threats/{id}

Delete a bulletin (platform admin only)

Auth required

List threats

curl "https://api-pro.threatgrid.tech/api/threats?severity=CRITICAL&limit=25" \
  -H "Authorization: Bearer <token>"

Query parameters

`severity`	string	CRITICAL, HIGH, MEDIUM, LOW, or INFO
`search`	string	Full-text search across title and body
`tag`	string	Filter by tag
`limit`	number	Results per page (default 25, max 100)
`offset`	number	Pagination offset

Incidents

Incidents represent declared under-attack states. When an incident is active, a warning banner is shown across every team member's dashboard and an alert email is sent to all org admins. Only one incident can be active per organization at a time.

GET

/api/orgs/{orgId}/incidents/active

Get the currently active incident, or null

Auth required

GET

/api/orgs/{orgId}/incidents

List all past and present incidents (newest first)

Auth required

POST

/api/orgs/{orgId}/incidents/declare

Declare an active incident (Admin/Owner)

Auth required

DELETE

/api/orgs/{orgId}/incidents/resolve

Resolve the active incident (Admin/Owner)

Auth required

Declare an incident

curl -X POST https://api-pro.threatgrid.tech/api/orgs/{orgId}/incidents/declare \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "severity": "HIGH",
    "notes": "DDoS against api.example.com — volumetric attack began at 14:30 UTC. Mitigation in progress."
  }'

Resolve

curl -X DELETE https://api-pro.threatgrid.tech/api/orgs/{orgId}/incidents/resolve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "resolveNotes": "Upstream scrubbing in place; traffic back to baseline." }'

Vulnerabilities

Track vulnerabilities discovered across your monitored assets. Vulns can be created from scan results automatically or added manually. Each follows a status lifecycle: NEW → INVESTIGATING → REMEDIATED (or ACCEPTED_RISK).

GET

/api/orgs/{orgId}/vulns

List vulnerabilities (filterable by status, severity)

Auth required

POST

/api/orgs/{orgId}/vulns

Create or import a vulnerability

Auth required

PATCH

/api/orgs/{orgId}/vulns/{id}

Update status, severity, assignee, or notes

Auth required

DELETE

/api/orgs/{orgId}/vulns/{id}

Delete a vulnerability record

Auth required

Create a vulnerability

curl -X POST https://api-pro.threatgrid.tech/api/orgs/{orgId}/vulns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "TLS 1.0 still accepted",
    "severity": "HIGH",
    "cveId": "CVE-2021-3449",
    "description": "Server negotiates TLS 1.0 with legacy clients",
    "affectedAssets": ["api.example.com"],
    "dueDate": "2025-07-01"
  }'

Status lifecycle

NEWINVESTIGATINGREMEDIATEDACCEPTED_RISK

Breach Scanning

Breach scanning checks whether email addresses associated with your monitored assets have appeared in known data breaches. Results are cached per address and refreshed on demand.

GET

/api/orgs/{orgId}/breach-scan

List cached breach-scan results for the organization

Auth required

POST

/api/orgs/{orgId}/breach-scan

Scan all org members' email addresses for known breaches (Admin/Owner, max once per hour)

Auth required

Trigger a scan

curl -X POST https://api-pro.threatgrid.tech/api/orgs/{orgId}/breach-scan \
  -H "Authorization: Bearer <token>"

Breach scanning requires a Pro plan or above. Free accounts receive a 403 Forbidden response.

Correlation

The correlation endpoint aggregates threat signals across your organization — open alerts, active vulnerabilities, breach hits, and CVE matches — and returns a unified risk view with an AI-generated summary. This powers the correlation panel in the dashboard.

GET

/api/orgs/{orgId}/correlate

Get correlated threat intelligence and risk summary for the org

Auth required

Example

curl "https://api-pro.threatgrid.tech/api/orgs/{orgId}/correlate" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "riskScore": 74,
    "summary": "3 critical CVEs detected across 2 assets. 1 monitored email address found in recent breach.",
    "findings": [
      { "type": "cve",    "assetId": "...", "cveId": "CVE-2024-1234", "severity": "CRITICAL" },
      { "type": "breach", "assetId": "...", "email": "admin@...",     "breachCount": 2 }
    ]
  }
}

Digest

The digest is a scheduled security summary delivered by email. It aggregates alerts, scan findings, and threat intel from the past interval. You can configure delivery schedule, retrieve past digests, and trigger on-demand sends.

GET

/api/orgs/{orgId}/digest

List past digests (paginated, newest first)

Auth required

GET

/api/orgs/{orgId}/digest/{digestId}

Get a specific digest with full content

Auth required

GET

/api/orgs/{orgId}/digest/config

Get the digest schedule (sent to every member)

Auth required

PATCH

/api/orgs/{orgId}/digest/config

Turn the digest on or off and set daily/weekly, day and hour (UTC) (Admin/Owner)

Auth required

POST

/api/orgs/{orgId}/digest/intel

Send the intel digest now, or preview it with { "preview": true } (Admin/Owner). Scheduled digests send automatically.

Auth required

Update digest config

curl -X PATCH https://api-pro.threatgrid.tech/api/orgs/{orgId}/digest/config \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "frequency": "weekly",
    "dayOfWeek": 1,
    "hour": 8
  }'

frequency is daily or weekly; dayOfWeek is 0–6 (0 = Sunday); hour is 0–23 UTC. The digest goes to every org member.

Platform Status

Returns the current health of TLINK PRO platform components. This endpoint is unauthenticated and safe to poll from external uptime monitors. The public /status page reads from this endpoint.

GET

/api/platform-status

Get current component health — no auth required

Example response

{
  "success": true,
  "data": {
    "status": "degraded",
    "components": [
      { "name": "API",        "status": "operational" },
      { "name": "Monitoring", "status": "operational" },
      { "name": "Alerts",     "status": "degraded",   "message": "Elevated latency" },
      { "name": "Database",   "status": "operational" }
    ],
    "updatedAt": "2026-06-13T14:00:00Z"
  }
}

Top-level status is operational only when all components are operational. Any degraded or outage component sets the top-level to the worst status present.