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.

Context supports nested objects and has no fixed schema, allowing you to pass any fields your workflow requires. However, there is a distinction in how this data is displayed:

• API Access: All keys and values stored in the context object are returned when retrieving entities via Lists: Get Entities.
• Platform UI: To make metadata visible within the platform interface, you must use the specific key "annotation". While the API will accept and store any other key names, only the value assigned to "annotation" will be rendered in the UI.

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.