TLINK PRO API Reference
PricingSign inStart free

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://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://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://pro.threatgrid.tech/api/users/me \
  -H "Authorization: Bearer <accessToken>"

When the access token expires, refresh it:

curl -X POST https://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. Pass it via the X-API-Key header:

curl https://pro.threatgrid.tech/api/orgs/{orgId}/assets \
  -H "X-API-Key: tlpro_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.

PlanRequests / minuteTool runs / month
Free30100
Pro1205,000
Business300Unlimited
EnterpriseCustomUnlimited

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://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

typerequiredstringDOMAIN, IP, EMAIL, URL, HASH, ASN, or CERTIFICATE
valuerequiredstringThe asset value (e.g. example.com, 1.2.3.4)
labelstringOptional human-readable label
isMonitoredbooleanWhether 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://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": "abuseipdb.abuseConfidenceScore",
      "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://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/orgs/{orgId}/tools/run

Run a tool against a target (async, returns reportId)

Auth required
GET
/api/orgs/{orgId}/tools/reports

List all saved reports

Auth required
GET
/api/orgs/{orgId}/tools/reports/{reportId}

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://pro.threatgrid.tech/api/orgs/{orgId}/tools/run \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "toolKey": "ip-reputation",
    "target": "1.2.3.4",
    "assetId": "optional-asset-id-to-link-result"
  }'

Webhooks

When an alert rule fires, TLINK PRO can POST a JSON payload to your configured webhook URL. Set the URL in the alert rule's webhookUrl field.

Payload shape

{
  "event": "alert.fired",
  "alertId": "abc123",
  "ruleId": "rule456",
  "ruleName": "High abuse score",
  "severity": "HIGH",
  "asset": {
    "id": "asset789",
    "type": "IP",
    "value": "1.2.3.4"
  },
  "triggeredAt": "2025-11-14T10:30:00Z",
  "message": "abuseipdb.abuseConfidenceScore ≥ 75 (actual: 92)"
}

Slack example

Create a Slack Incoming Webhook and use the URL in your rule. TLINK PRO sends standard JSON — wrap it with a Slack workflow or use a bridge like Zapier if you need Slack's block format.

Webhook requests include a X-TLINK-Signature header (HMAC-SHA256 of the payload) for request verification. Support for secret-based verification is coming in a future release.

API Keys

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

GET
/api/users/me/api-keys

List your API keys

Auth required
POST
/api/users/me/api-keys

Create a new API key

Auth required
DELETE
/api/users/me/api-keys/{keyId}

Revoke an API key

Auth required

Create an API key

curl -X POST https://pro.threatgrid.tech/api/users/me/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

# Use X-API-Key header (no Bearer prefix)
curl https://pro.threatgrid.tech/api/orgs/{orgId}/assets \
  -H "X-API-Key: tlpro_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://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://pro.threatgrid.tech/api/threats?severity=CRITICAL&limit=25" \
  -H "Authorization: Bearer <token>"

Query parameters

severitystringCRITICAL, HIGH, MEDIUM, LOW, or INFO
searchstringFull-text search across title and body
tagstringFilter by tag
limitnumberResults per page (default 25, max 100)
offsetnumberPagination 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://pro.threatgrid.tech/api/orgs/{orgId}/incidents/declare \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "DDoS against api.example.com",
    "severity": "HIGH",
    "description": "Volumetric attack began at 14:30 UTC. Mitigation in progress."
  }'

Resolve

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

Vulnerabilities

Track vulnerabilities discovered across your monitored assets. Vulns can be created from scan results automatically or added manually. Each follows a status lifecycle: OPEN → IN_PROGRESS → RESOLVED.

GET
/api/orgs/{orgId}/vulns

List vulnerabilities (filterable by status, severity, assetId)

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://pro.threatgrid.tech/api/orgs/{orgId}/vulns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "asset-id",
    "title": "TLS 1.0 still accepted",
    "severity": "HIGH",
    "cve": "CVE-2021-3449",
    "description": "Server negotiates TLS 1.0 with legacy clients"
  }'

Status lifecycle

OPENIN_PROGRESSRESOLVED

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

Trigger a breach scan for one or more email addresses

Auth required

Trigger a scan

curl -X POST https://pro.threatgrid.tech/api/orgs/{orgId}/breach-scan \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["user@example.com", "admin@example.com"]
  }'

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://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
POST
/api/orgs/{orgId}/digest/send

Send a digest immediately (Admin/Owner)

Auth required
GET
/api/orgs/{orgId}/digest/config

Get current schedule and recipient configuration

Auth required
PATCH
/api/orgs/{orgId}/digest/config

Update schedule or recipients (Admin/Owner)

Auth required
POST
/api/orgs/{orgId}/digest/intel

Add an intelligence note to the next digest (Admin/Owner)

Auth required

Update digest config

curl -X PATCH https://pro.threatgrid.tech/api/orgs/{orgId}/digest/config \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "weekly",
    "dayOfWeek": "Monday",
    "hour": 8,
    "recipients": ["security@example.com", "ciso@example.com"]
  }'

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.