Recorded Future Integration Guide

Overview

The Recorded Future integration connects NINA workflows to Recorded Future's threat intelligence platform across seven API modules:

Alert — Manage and query Recorded Future alerts (v2 and v3)
Analyst Note — Create, publish, search, and manage analyst notes
Entity Match — Resolve entity names to RF entity IDs and look up entities
Identity — Query credential exposures, detections, and incident reports
List — Read and write user-managed entity watch lists
Playbook Alert — Search, retrieve, and update playbook alerts across all categories
Threat — Retrieve threat maps (actor and malware), search threat actors, and list categories

Authentication uses a single API key (X-RFToken header). All seven modules share the same credential.

Credential Configuration

Authentication

Field	Description	Default
API Key	Your Recorded Future API key (`X-RFToken`)	—
Base URL	API endpoint	`https://api.recordedfuture.com`

How to Get Your Recorded Future API Key

Log in to the Recorded Future Portal
Navigate to User Settings → API Access
Copy your existing key or generate a new one
Verify your key has access to the modules your workflows require (Identity, Playbook Alert, etc.)

Subscription notes:

Identity and Playbook Alert APIs require specific subscription tiers
Some endpoints are in Beta — check Recorded Future docs for current availability

Creating a Credential in NINA

Navigate to Credentials → Add New Credential
Select integration service: Recorded Future
Auth type: API Key
Fill in your API Key and optionally override the Base URL
Click Test Connection then Save

Supported Resources and Operations

Alert

Interact with Recorded Future alerts (rule-triggered intelligence alerts). Supports both the legacy v2 and current v3 APIs.

Operation	Name	HTTP	Description
`listV2Search`	List V2 Search	GET /v2/search	Search alerts with filters (status, assignee, alertRule, freetext, date range)
`listV2SearchDetails`	List V2 Search Details	GET /v2/search/details	Same as above with additional detail fields
`listV3`	List V3	GET /v3	Search alerts using the v3 API (statusInPortal filter)
`getV2ById`	Get V2 By Id	`GET /v2/{alert_id}`	Fetch a single alert by ID (v2)
`getV3ById`	Get V3 By Id	`GET /v3/{alert_id}`	Fetch a single alert by ID (v3) with field selection
`listV3Hits`	List V3 Hits	GET /v3/hits	Fetch a flat collection of hits for one or more alert IDs
`listV3Image`	List V3 Image	GET /v3/image	Fetch raw image data by image ID
`createV2Update`	Create V2 Update	POST /v2/update	Update status/assignee on one or more alerts
`listV2Rule`	List V2 Rule	GET /v2/rule	Search alert rules (freetext, limit, taggedText)

Key parameters for listV2Search / listV2SearchDetails:

status — enum: unassigned, assigned, pending, dismiss, no-action, actionable, tuning
triggered — date range filter (e.g., [-24h,] for last 24 hours)
alertRule — filter by alert rule ID
limit / from — pagination (max limit+from = 1000)
direction — asc or desc

Analyst Note

Create, publish, look up, export, and delete analyst notes in Recorded Future.

Operation	Name	HTTP	Description
`searchSearch`	Search	POST /search	Search analyst notes by entity, topic, title, label, date, source
`createLookupById`	Lookup By Id	`POST /lookup/{note_id}`	Fetch a specific analyst note by ID
`createDraft`	Create Draft	POST /draft	Save a note as a draft
`createPreview`	Create Preview	POST /preview	Preview note rendering before publishing
`createPublish`	Create Publish	POST /publish	Publish or edit an analyst note
`deleteDeleteById`	Delete By Id	`DELETE /delete/{note_id}`	Delete an analyst note by ID
`getAttachmentById`	Get Attachment	`GET /attachment/{note_id}`	Retrieve an attachment for a note
`getExportByFormatById`	Export By Format	`GET /export/{format}/{note_id}`	Export a note as `html` or `pdf`

Common parameters:

note_id — required for all *ById operations (path parameter)
attributes — note content object (title, text, topic, etc.)
source — entity ID for the note source
tagged_text — boolean; inline entity tags in output
serialization — id, min, or full

Entity Match

Resolve entity names to Recorded Future IDs and look up entities by ID. Useful as a pre-step before other operations that require RF entity IDs.

Operation	Name	HTTP	Description
`createEntityMatchMatch`	Match Entities	POST /entity-match/match	Find entity IDs by name (and optionally type)
`getEntityMatchEntityById`	Get Entity By Id	`GET /entity-match/entity/{id}`	Look up a specific entity by its RF ID

Parameters for createEntityMatchMatch:

name (required) — entity name to search
type — array of entity types to filter (e.g., ["IpAddress", "InternetDomainName"])
limit — number of results (default: 10)

Identity

Query Recorded Future's Identity Intelligence module for credential exposures, compromised accounts, and incident reports.

Operation	Name	HTTP	Description
`searchCredentials`	Search Credentials	POST /identity/credentials/search	Search exposed credentials by domain
`lookupCredentials`	Lookup Credentials	POST /identity/credentials/lookup	Look up credentials by subject, SHA1 hash, or login
`lookupPassword`	Lookup Password	POST /identity/password/lookup	Check if specific passwords have been exposed
`lookupHostname`	Lookup Hostname	POST /identity/hostname/lookup	Find credential exposure for a hostname
`lookupIP`	Lookup IP	POST /identity/ip/lookup	Find credential exposure for an IP or IP range
`getDetections`	Get Detections	POST /identity/detections	(Beta) List identity detections for an organization
`getIncidentReport`	Get Incident Report	POST /identity/incident/report	Get a detailed incident report for a data dump/breach
`getDumpMetadata`	Get Dump Metadata	POST /identity/metadata/dump/search	Search metadata for known data dumps by name

Common parameters:

organization_id — string; scopes results to your organization
domains / domain_types — filter by domain for credential searches
limit / offset — pagination

lookupCredentials lookup methods (use one):

subjects — list of email addresses or usernames to look up directly
subjects_sha1 — list of SHA1-hashed subject identifiers (privacy-preserving)
subjects_login + subjects_domain — paired arrays for domain/login lookup (e.g., login: ["j.doe"], domain: ["corp.com"]). Both arrays are required and matched by index. The API requires a domain for each login entry.

lookupPassword parameters:

passwords — array of password hash objects, each with:
- algorithm (required) — hash algorithm enum: SHA1, SHA256, MD5, NTLM, BCRYPT, and 20 others
- hash — full hash value (use this OR hash_prefix)
- hash_prefix — hash prefix for partial matching (use this OR hash)

getDetections filter object children:

novel_only / malware_only — boolean filters
domains — array of domain names
detection_types / detection_type — enum: Workforce, External, Vip
cookies — enum: Cookies, UnexpiredCookies
authorization_technology — object with any (boolean), id (array), name (array)
created — date range object with gte / lt (ISO-8601)

Credential filter parameters (available on searchCredentials, lookupCredentials, lookupHostname, lookupIP):

time_window — quick preset: last_24h, last_7d, last_30d, last_90d (overrides date filters below)
first_downloaded_gte — credentials first seen after this date (ISO-8601)
latest_downloaded_gte — credentials last downloaded after this date
exfiltration_date_gte — malware exfiltration date filter
properties — enum array: Letter, Number, Symbol, UpperCase, LowerCase, MixedCase, AtLeast8Characters, AtLeast10Characters, AtLeast12Characters, AtLeast16Characters, AtLeast24Characters, Cookies, UnexpiredCookies, AuthorizationTechnology, MalwareOnly
username_properties — enum array: Email
breach_properties — object with name and date children
dump_properties — object with name and date children
authorization_technologies — free-text array (e.g., SAML, OAuth, Okta Single Sign-On)
authorization_protocols — free-text array (e.g., RDP, SSH, HTTPS, FTP)
malware_families — free-text array (e.g., RedLine Stealer, Vidar Stealer)
mask_passwords — boolean; masks cleartext passwords in response (keeps first 2 chars visible)

List

Read and write user-managed entity watch lists in Recorded Future.

Operation	Name	HTTP	Description
`createListCreate`	Create List	POST /list/create	Create a new watch list
`searchListSearch`	Search Lists	POST /list/search	Find lists by name or type
`getListInfoByListid`	Get List Info	`GET /list/{listId}/info`	Get metadata for a specific list
`getListStatusByListid`	Get List Status	`GET /list/{listId}/status`	Get status information for a list
`getListEntitiesByListid`	Get List Entities	`GET /list/{listId}/entities`	Get entities on a list
`getListEntitieswithtagsByListid`	Get List Entities With Tags	`GET /list/{listId}/entitiesWithTags`	Get entities including their list-specific tags
`getListTextentriesByListid`	Get List Text Entries	`GET /list/{listId}/textEntries`	Get text entries on a list
`createListEntityAddByListid`	Add Entity To List	`POST /list/{listId}/entity/add`	Add an entity to a list
`createListEntityRemoveByListid`	Remove Entity From List	`POST /list/{listId}/entity/remove`	Remove an entity from a list
`createListEntityTagsByListid`	Update Entity Tags	`POST /list/{listId}/entity/tags`	Set all tags for an entity on a watch list (replaces existing)

Key parameters:

listId (required) — path parameter identifying the target list; use searchListSearch to find IDs
entity — object with id and/or name fields
type — list type filter (e.g., ip, domain, hash, url, vulnerability)

Playbook Alert

Programmatic access to Recorded Future Playbook Alerts — structured, analyst-ready alerts with typed categories (Domain Abuse, Vulnerability, Malware, etc.).

Core Operations

Operation	Name	HTTP	Description
`searchSearch`	Search	POST /search	Search playbook alerts with filters (status, priority, category, assignee, date ranges)
`getCommonById`	Get Common By Id	`GET /common/{playbook_alert_id}`	Fetch common preview data for any playbook alert
`updateCommonById`	Update Common By Id	`PUT /common/{playbook_alert_id}`	Update status, priority, assignee, or add log entries
`listMetadataCommon`	List Metadata Common	GET /metadata/common	Enumerate valid statuses, priorities, and categories
`createMetadataAssignees`	Create Metadata Assignees	POST /metadata/assignees	List available assignees for a playbook alert

Category-Specific Operations

Each category supports both single-ID and bulk lookup:

Category	Single ID Operation	Bulk Operation
Domain Abuse	`createDomainAbuseById`	`createDomainAbuse`
Vulnerability	`createVulnerabilityById`	`createVulnerability`
Code Repo Leakage	`createCodeRepoLeakageById`	`createCodeRepoLeakage`
Third Party Risk	`createThirdPartyRiskById`	`createThirdPartyRisk`
Identity Novel Exposures	`createIdentityNovelExposuresById`	`createIdentityNovelExposures`
Geopolitics Facility	`createGeopoliticsFacilityById`	`createGeopoliticsFacility`
Malware Report	`createMalwareReportById`	`createMalwareReport`
Compromised Bank Checks	`createCompromisedBankChecksById`	`createCompromisedBankChecks`

Single-ID operations accept playbook_alert_id (required path param) + optional panels array. Bulk operations accept playbook_alert_ids array (required) + optional panels array. Bulk max: 250 IDs.

Image Operations

Operation	Name	HTTP	Description
`getDomainAbuseImageByIdById`	Get Domain Abuse Image	`GET /domain_abuse/{playbook_alert_id}/image/{image_id}`	Screenshot for a Domain Abuse alert
`getGeopoliticsFacilityImageById`	Get Geopolitics Facility Image	`GET /geopolitics_facility/image/{image_id}`	Image for a Geopolitics Facility alert
`getCompromisedBankChecksImageById`	Get Compromised Bank Checks Image	`GET /compromised_bank_checks/image/{playbook_alert_id}`	Check image for a Compromised Bank Checks alert

Key searchSearch parameters:

statuses — array; enum: New, InProgress, Dismissed, Resolved
priority — array; enum: High, Moderate, Informational
category — array; enum: domain_abuse, cyber_vulnerability, code_repo_leakage, third_party_risk, identity_novel_exposures, geopolitics_facility
assignee — array of assignee IDs
created_range / updated_range — time range objects with from and until children (ISO-8601 date-time)
entity — array of RF entity IDs
limit / offset — pagination (max limit+from = 10,000)
order_by — created or modified; direction — asc or desc

Key updateCommonById parameters:

status — enum: New, InProgress, Dismissed, Resolved
priority — enum: High, Moderate, Informational
reopen — enum: Never, SignificantUpdates (only valid for Dismissed/Resolved alerts)
assignee — assignee ID string
log_entry — freetext message (max 5000 chars)
added_actions_taken / removed_actions_taken — arrays of action IDs (only when status is Dismissed or Resolved)

Threat

Retrieve threat intelligence maps, search threat actors, and list categories for filtering. Threat maps show actor/malware activity mapped against your organization's watchlists.

Operation	Name	HTTP	Description
`getMaps`	Get Maps	GET /threat/maps	List available threat maps for your account
`getActorThreatMap`	Get Actor Threat Map	POST /threat/map/actors	Actor threat map for your primary organization
`getActorThreatMapByOrg`	Get Actor Threat Map By Org	`POST /threat/map/{orgId}/actors`	Actor threat map for a specific organization
`getMalwareThreatMap`	Get Malware Threat Map	POST /threat/map/malware	Malware threat map for your primary organization
`getMalwareThreatMapByOrg`	Get Malware Threat Map By Org	`POST /threat/map/{orgId}/malware`	Malware threat map for a specific organization
`searchActors`	Search Threat Actors	POST /threat/actor/search	Search threat actors by name with pagination
`getActorCategories`	Get Actor Categories	GET /threat/actor/categories	List threat actor categories (for filtering maps)
`getMalwareCategories`	Get Malware Categories	GET /threat/malware/categories	List malware categories (for filtering maps)

Threat map filter parameters (for getActorThreatMap / getActorThreatMapByOrg):

actors — array of threat actor IDs to filter by
categories — array of actor category IDs
watchlists — array of watchlist IDs to include

Malware map filter parameters (for getMalwareThreatMap / getMalwareThreatMapByOrg):

malware — array of malware IDs to filter by
categories — array of malware category IDs
watchlists — array of watchlist IDs to include

searchActors parameters:

name — search string (matches names, common names, and aliases)
limit — max results, 1-10000 (default: 10000)
offset — pagination token from next_offset in previous response

Examples

Search for Open Playbook Alerts

{
  "integration_service": "recorded-future",
  "resource": "playbook-alert",
  "operation": "searchSearch",
  "parameters": {
    "statuses": ["New"],
    "priority": ["High"],
    "order_by": "created",
    "direction": "desc",
    "limit": 25
  }
}

Update a Playbook Alert Status

{
  "integration_service": "recorded-future",
  "resource": "playbook-alert",
  "operation": "updateCommonById",
  "parameters": {
    "playbook_alert_id": "abc-123-xyz",
    "status": "InProgress",
    "assignee": "uhash:40wXmPVONA",
    "log_entry": "Reviewed domain registration — confirmed abuse. Escalating."
  }
}

Get Domain Abuse Alert Detail

{
  "integration_service": "recorded-future",
  "resource": "playbook-alert",
  "operation": "createDomainAbuseById",
  "parameters": {
    "playbook_alert_id": "abc-123-xyz",
    "panels": ["dns", "whois", "screenshot"]
  }
}

Search Exposed Credentials by Domain

{
  "integration_service": "recorded-future",
  "resource": "identity",
  "operation": "searchCredentials",
  "parameters": {
    "domains": ["example.com", "corp.example.com"],
    "domain_types": ["corporate"],
    "limit": 50
  }
}

Look Up Credentials for Specific Users

{
  "integration_service": "recorded-future",
  "resource": "identity",
  "operation": "lookupCredentials",
  "parameters": {
    "subjects": ["[email protected]", "[email protected]"],
    "limit": 100
  }
}

Use subjects_login + subjects_domain when you have a login/domain pair rather than an email:

{
  "integration_service": "recorded-future",
  "resource": "identity",
  "operation": "lookupCredentials",
  "parameters": {
    "subjects_login": ["j.doe", "admin"],
    "subjects_domain": ["corp.example.com", "portal.example.com"],
    "limit": 50
  }
}

Search Credentials with Filters

{
  "integration_service": "recorded-future",
  "resource": "identity",
  "operation": "searchCredentials",
  "parameters": {
    "domains": ["example.com"],
    "time_window": "last_30d",
    "properties": ["AtLeast8Characters", "MixedCase"],
    "malware_families": ["RedLine Stealer"],
    "limit": 100
  }
}

Get Actor Threat Map

{
  "integration_service": "recorded-future",
  "resource": "threat",
  "operation": "getActorThreatMap",
  "parameters": {
    "categories": ["GK7qU"],
    "watchlists": ["report:Hsxme2"]
  }
}

Search Threat Actors

{
  "integration_service": "recorded-future",
  "resource": "threat",
  "operation": "searchActors",
  "parameters": {
    "name": "Fancy Bear",
    "limit": 10
  }
}

Resolve an Entity Name to RF ID

{
  "integration_service": "recorded-future",
  "resource": "entity-match",
  "operation": "createEntityMatchMatch",
  "parameters": {
    "name": "APT29",
    "type": ["ThreatActor"],
    "limit": 5
  }
}

Search Alerts by Status

{
  "integration_service": "recorded-future",
  "resource": "alert",
  "operation": "listV2Search",
  "parameters": {
    "status": "unassigned",
    "triggered": "[-7d,]",
    "limit": 50,
    "direction": "desc"
  }
}

Add Entity to a Watch List

{
  "integration_service": "recorded-future",
  "resource": "list",
  "operation": "createListEntityAddByListid",
  "parameters": {
    "listId": "my-list-id-here",
    "entity": { "id": "ip:8.8.8.8" },
    "context": { "comment": "Added during incident IR-2024-001" }
  }
}

Search Analyst Notes

{
  "integration_service": "recorded-future",
  "resource": "analyst-note",
  "operation": "searchSearch",
  "parameters": {
    "entity": "idn:example.com",
    "published": "-30d",
    "limit": 20,
    "serialization": "full"
  }
}

Bulk Vulnerability Playbook Alert Lookup

{
  "integration_service": "recorded-future",
  "resource": "playbook-alert",
  "operation": "createVulnerability",
  "parameters": {
    "playbook_alert_ids": ["alert-id-1", "alert-id-2", "alert-id-3"],
    "panels": ["summary", "affected_products"]
  }
}

Common Workflow Patterns

Playbook Alert Triage Workflow

searchSearch (playbook-alert) — fetch new/unassigned alerts
getCommonById — get preview for each alert
createDomainAbuseById / createVulnerabilityById / etc. — get category-specific detail
updateCommonById — set status, assign to analyst, add log entry

Identity Exposure Investigation

searchCredentials — find exposed accounts for your domains (use time_window or date filters to scope)
lookupCredentials — look up specific users by email (subjects) or by login/domain pair (subjects_login + subjects_domain)
getIncidentReport — get full incident report for a known breach source
getDumpMetadata — look up metadata about a specific dump by name

Entity-Driven Intelligence

createEntityMatchMatch (entity-match) — resolve an observable name to RF entity ID
Use the entity ID in searchSearch (analyst-note or playbook-alert) to find related intelligence
getEntityMatchEntityById — enrich entity with full RF metadata

Threat Map Analysis

getMaps (threat) — list available threat maps for your organization
getActorCategories / getMalwareCategories — fetch category IDs for filtering
getActorThreatMap or getMalwareThreatMap — retrieve the threat map with optional filters
searchActors — search for specific threat actors by name for deeper investigation

Watch List Management

searchListSearch — find your target list by name
getListEntitiesByListid — review current list contents
createListEntityAddByListid / createListEntityRemoveByListid — add/remove entities
getListStatusByListid — verify list sync status

Troubleshooting

Issue	Resolution
401 Unauthorized	API key invalid or expired — verify in RF portal and update credential
403 Forbidden	Subscription does not include this endpoint (e.g., Identity, Playbook Alert)
404 Not Found	Wrong entity/alert/note ID, or endpoint path mismatch
429 Too Many Requests	Rate limit hit — implement exponential backoff; reduce request frequency
Empty results	Entity or alert may not exist in RF database; verify IDs from a prior search
Missing path parameter error	Ensure `playbook_alert_id`, `alert_id`, `note_id`, or `listId` is included in params
Bulk request limit exceeded	Playbook alert bulk ops max 250 IDs per request — split into batches
Identity data unavailable	Requires Identity Intelligence subscription tier
Playbook alerts unavailable	Requires Playbook Alert subscription — confirm with RF account team
`panels` returns partial data	Specific panels may not apply to all alert subtypes; omit to return all available panels
400 error on `lookupCredentials` with `subjects_login`	`subjects_domain` is required when using `subjects_login` — provide both arrays matched by index
400 error on `lookupPassword`	`passwords` must be an array of hash objects (`{algorithm, hash}`), not plain password strings
Wrong enum values on `updateCommonById`	Use exact casing: `InProgress` (not `in-progress`), `High` (not `high`), `Resolved` (not `resolved`)

Security Considerations

Protect API Keys: Store exclusively through NINA credential management — never in workflow parameters or logs
Sensitive Data: Credential lookups and identity data are highly sensitive — restrict workflow access accordingly
IOC Submission Awareness: IOCs submitted to RF APIs may be logged for service improvement
Subscription Scoping: Ensure your API key subscription tier covers the modules your workflows use
Credential Rotation: Rotate API keys regularly; revoke immediately if compromised

Additional Resources

Updated: 2026-03-19

Overview​

Credential Configuration​

Authentication​

How to Get Your Recorded Future API Key​

Creating a Credential in NINA​

Supported Resources and Operations​

Alert​

Analyst Note​

Entity Match​

Identity​

List​

Playbook Alert​

Core Operations​

Category-Specific Operations​

Image Operations​

Threat​

Examples​

Search for Open Playbook Alerts​

Update a Playbook Alert Status​

Get Domain Abuse Alert Detail​

Search Exposed Credentials by Domain​

Look Up Credentials for Specific Users​

Look Up Credentials by Login and Domain​

Search Credentials with Filters​

Get Actor Threat Map​

Search Threat Actors​

Resolve an Entity Name to RF ID​

Search Alerts by Status​

Add Entity to a Watch List​

Search Analyst Notes​

Bulk Vulnerability Playbook Alert Lookup​

Common Workflow Patterns​

Playbook Alert Triage Workflow​

Identity Exposure Investigation​

Entity-Driven Intelligence​

Threat Map Analysis​

Watch List Management​

Troubleshooting​

Security Considerations​

Additional Resources​