What this endpoint does

Adds a single entity to an existing Recorded Future list. Obtain a listId (format report:XXXXX) from Lists: Search or Lists: Create. Specify the entity using either: (a) the id field with an RF entity ID (e.g., ip:8.8.8.8, idn:example.com), or (b) type + name for automatic resolution -- but auto-resolution only works for IpAddress, InternetDomainName, Hash, and CyberVulnerability. For all other entity types (Malware, Company, Organization, Person, Technology, etc.), use Entity Match to resolve a human-readable name to its RF entity ID, then pass that ID in the id field.

Custom metadata with `context`

You can attach arbitrary key-value metadata to an entity by including a context object in the request body. This is useful for tracking why an entity was added, linking it to external tickets, or tagging it with workflow-specific labels (e.g., "source": "threat-feed", "ticket_id": "INC-12345"). Context supports nested objects and has no fixed schema -- pass whatever fields your workflow needs. The stored context is returned when retrieving entities via Lists: Get Entities.

If you re-add an entity that already exists in the list with different context, the context is fully replaced (not merged) and the response returns "result": "added". Re-adding with identical context or no context returns "result": "unchanged" and leaves existing context intact.

Response data

This is a fire-and-forget operation -- a successful response confirms the entity is now part of the list and will be included in any alerting, monitoring, or intelligence workflows tied to that list. There is no returned entity object to inspect. If you need to verify the addition or see the full list membership, call Lists: Get Entities.

200Success

400Invalid Request

404List not found