Recorded Future Links API

openapi: 3.0.3
info:
  title: Links API
  description: "An API to retrieve verified links between entities. \nLinks may come from technical analysis of cyber threats or Insikt Group research.\n\nPlease read the [detailed support article](https://support.recordedfuture.com/hc/en-us/articles/11345110640403-Links-API) before using this API.\n"
  version: 1.0.0
  x-rf-service-id: service:links
servers:
- url: https://api.recordedfuture.com/links
  x-internal: false
- url: /links
  x-internal: false
paths:
  /metadata/entities:
    get:
      summary: Target entity types
      description: 'Return a list of available types of target entities,  this can be used to indicate which entity types should be returned for a query.

        '
      tags:
      - Metadata
      security:
      - ApiKeyAuth: []
      - idp: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Enumeration'
                example:
                  data:
                  - id: IpAddress
                    name: An IP address
  /metadata/events:
    get:
      summary: Technical analysis event types
      description: 'Returns a list of available types of technical analysis sources for the link, like Malware Analysis.  This can be used to indicate which technical sources that should be included in a search query.

        '
      tags:
      - Metadata
      security:
      - ApiKeyAuth: []
      - idp: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Enumeration'
                example:
                  data:
                  - id: MalwareAnalysis
                    name: Malware Analysis
  /metadata/sections:
    get:
      summary: Link sections
      description: 'Return a list of available types of links, representing different relationships between target entities  and linked entities.

        '
      tags:
      - Metadata
      security:
      - ApiKeyAuth: []
      - idp: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Enumeration'
                example:
                  data:
                  - id: iU_ZsI
                    name: Victims & Exploit Targets
  /search:
    post:
      summary: Search for links
      description: "Search for validated relationships between entities in the Links graph.\n\nLinks represent technically validated relationships between entities — established through sandbox\nanalysis, infrastructure analysis, network traffic analysis, and Insikt Group research — not mere\nco-occurrence in articles.\n\nThe Entity Match API may be used to determine the ID for a certain entity.\n\nFor quick single-entity triage, the `links` enrichment field on entity Lookup endpoints provides the\nsame intelligence in a more compact format combined with other enrichment. Use this dedicated Links API\ninstead when you need filtering, batch queries across multiple entities, per-entity risk scores on\nlinked entities, or graph traversal via the `connected_entities` filter.\n\n**Filters**\n\nThis endpoint supports a variety of filters that can be used to control either the output or the sources used.\n\nIn order to filter the output, _sections_ may be used to only return links categorized as\
        \ for example \n\"Victims & Exploit Targets\", or _entity_types_ to only return certain types of entities, like IP addresses. \nSee the metadata endpoint for possible values.\n\nSources are grouped into two types, technical analysis and Insikt Group research. \nTechnical link sources may be further filtered by specifying only the relevant event types, or a timeframe for\nevent recency (up to a maximum of 1825 days from today).\n\n**Limits**\n\nThe depth of the search is abstracted into defined _scopes_.\nA larger scope _may_ yield more links, at the cost of increased latency.\nSee the `search_scope` filter for the exact number of references searched per scope.\nA maximum number of results per entity type may also be defined.\n\n**Results**\n\nResults are grouped on the input entity ID, \nand may include an _error_ property if the search for that particular entity failed.\n\nLinked entities are always returned with a basic set of properties as well as a variable set of attributes\
        \ that \ndepend on the entity type. For example, indicators will have risk data, \nMITRE ATT&CK identifiers will have a more detailed name and organizations, \ncompanies and persons will have a boolean flag for whether or not they are threat actors.\n"
      tags:
      - Links
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
      security:
      - ApiKeyAuth: []
      - idp: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message describing the problem
                    example: string
components:
  schemas:
    Query:
      description: Query
      type: object
      required:
      - entities
      properties:
        entities:
          description: 'IDs of entities to return links for. If more than one ID is provided,  it is equivalent of calling this endpoint once for each, condensed into one call.

            '
          type: array
          items:
            type: string
            example: JLHNoH
          minItems: 1
        filters:
          description: Filters the result based on link characteristics and the source of the link.
          type: object
          properties:
            sections:
              type: array
              description: 'Filters links to only a specific section (available from Metadata: Sections), for example only "Actors, Tools & TTPs" or only "Indicators & Detection Rules".

                '
              items:
                type: string
                example: iU_ZsI
            entity_types:
              type: array
              description: 'Filters links to only a specific entity type or types. The types of entities are returned by Metadata: Entities.

                '
              items:
                type: string
                example: type:IpAddress
            sources:
              type: array
              description: 'Limits the search to only one source type: technical links, or links from Insikt notes.

                '
              items:
                type: string
                enum:
                - technical
                - insikt
              example:
              - technical
              - insikt
            technical:
              type: object
              description: Filtering options specific to links from technical sources.
              properties:
                timeframe:
                  type: string
                  description: 'Time range for links from technical sources. As an ISO Date (2022-01-01) or relative to today (-7d). Maximum of 1825 days from today.

                    '
                  example: -30d
                  default: -30d
                events:
                  type: array
                  description: 'Limits the search for links to references of a certain event type or types. The available event types are returned by Metadata: Events.

                    '
                  items:
                    type: string
                    example: type:MalwareAnalysis
                connected_entities:
                  type: array
                  description: 'Only returns technical links that themselves have links to entities specified in this list.

                    '
                  items:
                    type: string
                    example: idn:google.com
        limits:
          type: object
          properties:
            search_scope:
              type: string
              default: medium
              enum:
              - small
              - medium
              - large
              description: 'Predefined levels of search depth. A larger scope may yield more linked entities, at the cost of increased latency. The scope controls how many references are searched per technical event type, and how many Insikt notes are searched: small = 10 references of each event type, 10 Insikt notes; medium = 50 references of each event type, 50 Insikt notes; large = 100 references of each event type plus an extra 1000 references of any type, 500 Insikt notes.

                '
            per_entity_type:
              type: integer
              format: int32
              example: 100
              description: 'The maximum number of returned entities per type (IP, hash, etc), applied separately to entities found via technical links and via Insikt notes. Indicators are sorted by risk prior to filtering.

                '
    SearchResponse:
      description: The result of a links query
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ResultSet'
    ResultSet:
      description: The result of a link query.
      type: object
      properties:
        entity:
          type: object
          properties:
            type:
              type: string
              description: Type of the input entity
              example: type:Malware
            id:
              type: string
              description: ID of the input entity
              example: JLHNoH
            name:
              type: string
              description: Name of the input entity
              example: Cobalt Strike
        links:
          type: array
          items:
            $ref: '#/components/schemas/LinkedEntity'
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      description: Error information if the link search for an entity failed for some reason.
      properties:
        message:
          type: string
          example: The entity was not found
        status_code:
          type: integer
          format: int32
          example: 404
    LinkedEntity:
      type: object
      properties:
        type:
          type: string
          description: The type of the entity
          example: type:IpAddress
        id:
          type: string
          description: Internal ID of the entity
          example: ip:8.8.8.8
        name:
          type: string
          description: Human readable name of the entity
          example: 8.8.8.8
        source:
          type: string
          description: The source of the link between entities
          enum:
          - technical
          - insikt
        section:
          type: string
          description: The section or category of the link
          example: iU_ZsI
        attributes:
          type: array
          description: "A variable list of attributes that depends on the entity type.\n\nIoCs (like IpAddress and Hash) should always have risk and criticality related attributes,\nMitreAttackIdentifiers will have a display name with more details and organizations, \ncompanies and persons will have a \"threat actor\" boolean flag.\nIf \"threat actor\" is false, risk data may also be included.\n"
          items:
            oneOf:
            - type: object
              title: RiskAttribute
              properties:
                id:
                  type: string
                  enum:
                  - risk_score
                  - risk_level
                value:
                  type: integer
                  format: int32
                  minimum: 0
                  maximum: 99
                  example: 90
            - type: object
              title: CriticalityAttribute
              properties:
                id:
                  type: string
                  enum:
                  - criticality
                value:
                  type: string
                  example: Malicious
            - type: object
              title: MitreNameAttribute
              properties:
                id:
                  type: string
                  enum:
                  - display_name
                value:
                  type: string
                  example: T1001 (Data Obfuscation)
            - type: object
              title: ThreatActorAttribute
              properties:
                id:
                  type: string
                  enum:
                  - threat_actor
                value:
                  type: boolean
                  example: true
    Enumeration:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
  securitySchemes:
    ApiKeyAuth:
      description: API Credential
      type: apiKey
      in: header
      name: X-RFToken
    idp:
      description: Click on "Authorize" to be redirected to the login page.
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://id.recordedfuture.com/authorize
          tokenUrl: https://id.recordedfuture.com/token
          refreshUrl: https://id.recordedfuture.com/token
          scopes: {}
tags:
- name: Links
- name: Metadata
x-provenance:
  method: searched
  source: https://docs.recordedfuture.com/reference
  harvested: '2026-10-20'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.recordedfuture.com/reference/get_metadata-entities.md
  - https://docs.recordedfuture.com/reference/get_metadata-events.md
  - https://docs.recordedfuture.com/reference/get_metadata-sections.md
  - https://docs.recordedfuture.com/reference/post_search.md
  merge:
    pages: 4
    deduped: 8
    conflicts_kept_first: 0