---
updatedAt: 2026-08-12T16:50:41.000Z
agentTools:
  projectIndex: https://docs.stairwell.com/llms.txt
---

# SearchIocs

SearchIocs answers "which investigations mention this IOC": every
 investigation in the requested environments that recorded the IOC, with
 its current disposition. Hostname IOCs match subdomains by default
 (exact=true restricts); file hashes and IPs always match exactly. The
 returned investigation ids resolve against GetResult / GetGraphState.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Stairwell Backstory (Beta)",
    "description": "APIs for driving Backstory background investigations: submit an IOC (file hash, hostname, or IP), poll the job to completion, and fetch the verdict, incident report, remediation recommendations, and raw graph state. The base URL for this API is https://app.stairwell.com/backstory/v1beta1. BETA: this surface carries no compatibility promise — routes and response shapes may change; breaking changes are announced in the changelog. Requires the Backstory (Constellation) entitlement.",
    "contact": {
      "name": "Stairwell",
      "email": "support@stairwell.com"
    },
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://app.stairwell.com/backstory"
    }
  ],
  "paths": {
    "/v1beta1/investigations/iocs:search": {
      "get": {
        "tags": [
          "Backstory"
        ],
        "summary": "SearchIocs",
        "description": "SearchIocs answers \"which investigations mention this IOC\": every\n investigation in the requested environments that recorded the IOC, with\n its current disposition. Hostname IOCs match subdomains by default\n (exact=true restricts); file hashes and IPs always match exactly. The\n returned investigation ids resolve against GetResult / GetGraphState.",
        "operationId": "Backstory_SearchIocs",
        "parameters": [
          {
            "name": "environmentIds",
            "in": "query",
            "description": "Environments to search (e.g. \"VXKCDN-GSPRN8-M4QW7Z-2TPLJT\").",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "iocType",
            "in": "query",
            "schema": {
              "enum": [
                "IOC_TYPE_UNSPECIFIED",
                "IOC_TYPE_FILE",
                "IOC_TYPE_HOSTNAME",
                "IOC_TYPE_IP"
              ],
              "type": "string",
              "format": "enum"
            }
          },
          {
            "name": "iocValue",
            "in": "query",
            "description": "The indicator in natural form.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "exact",
            "in": "query",
            "description": "Hostnames match subdomains by default (\"foo.com\" also matches\n \"www.foo.com\", never \"foobar.com\"). exact=true restricts to the exact\n value. Ignored for FILE/IP (always exact).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Page size (default 10, max 100).",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "pageToken",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IocMatchList"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "IocMatch": {
        "type": "object",
        "properties": {
          "investigationId": {
            "type": "string"
          },
          "environmentId": {
            "type": "string",
            "description": "The environment the investigation belongs to."
          },
          "iocValue": {
            "type": "string",
            "description": "The matched value in natural form."
          },
          "disposition": {
            "enum": [
              "IOC_DISPOSITION_UNSPECIFIED",
              "IOC_DISPOSITION_BLOCK",
              "IOC_DISPOSITION_MONITOR",
              "IOC_DISPOSITION_IGNORE",
              "IOC_DISPOSITION_PENDING"
            ],
            "type": "string",
            "format": "enum"
          },
          "adjudicatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "description": "IocMatch is one (investigation, matched ioc) pair with its current\n disposition."
      },
      "IocMatchList": {
        "type": "object",
        "properties": {
          "hits": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IocMatch"
            }
          },
          "nextPageToken": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "AuthToken": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "AuthToken": []
    }
  ],
  "tags": [
    {
      "name": "Backstory"
    }
  ]
}
```

# Sibling pages

* [Submit](https://docs.stairwell.com/reference/backstory_submit.md)
* [GetJob](https://docs.stairwell.com/reference/backstory_getjob.md)
* [GetResult](https://docs.stairwell.com/reference/backstory_getresult.md)
* [GetRecommendations](https://docs.stairwell.com/reference/backstory_getrecommendations.md)
* [GetGraphState](https://docs.stairwell.com/reference/backstory_getgraphstate.md)
* [ListInvestigations](https://docs.stairwell.com/reference/backstory_listinvestigations.md)
* [Cancel](https://docs.stairwell.com/reference/backstory_cancel.md)
* [Pause](https://docs.stairwell.com/reference/backstory_pause.md)
* [Resume](https://docs.stairwell.com/reference/backstory_resume.md)