Skip to content
Furl Docs

List scopes

GET
/v1/scopes
Code sample: cURL
curl --request GET \
  --url 'https://api.furl.ai/v1/scopes' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Returns a paginated list of remediation scopes in the organization.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 50 >= 1 <= 100

Maximum number of scopes to return.

offset
integer
0

Number of scopes to skip for pagination.

status
string
Allowed values: active paused archived

Filter by scope status.

Responses

Section titled “Responses”

200

Section titled “200”

Paginated list of scopes.

Media typeapplication/json
object
data
required
Data

The list of scopes.

Array<object>
Scope

A remediation scope that defines what gets remediated, on which endpoints, and under what conditions.

object
id
required
ID

Unique identifier for the scope.

string format: uuid
name
required
Name

Human-readable name of the scope.

string
description
required
Description

Detailed description of the scope’s purpose.

string
nullable
status
required
Status

Current status of the scope.

string
Allowed values: active paused archived
subject_filter
required
Subject Filter

Filter criteria for what remediation subjects are in scope.

object
subject_ids
Subject IDs

Subjects to include, by permanent subject_id.

Array<string>
vendor_keys
Vendor Keys

Vendors to include, as lowercased vendor alias values from the subject registry. A target matches when its bound subject carries a vendor alias equal to a key. Unbound targets never match.

Array<string>
subject_types
Subject Types

Types of subjects to include, compared against the target’s own type folded onto the subject-type vocabulary. Managed packages and OS patches read as software.

Array<string>
Allowed values: software service configuration dependency
cpe_patterns
CPE Patterns

CPE pattern strings for matching subjects.

Array<string>
endpoint_filter
required
Endpoint Filter

Filter criteria for which endpoints are in scope.

object
os_families
OS Families

Operating system families to include.

Array<string>
Allowed values: macos windows linux
endpoint_ids
Endpoint IDs

Specific endpoint IDs to include.

Array<string>
has_agent
Has Agent

Filter by whether the endpoint has an enrolled agent.

boolean
tags
Tags

Endpoint tags to include.

Array<string>
managed_by
Managed By

Normalized integration resource ids (e.g. aws, crowdstrike). Keeps only endpoints managed by at least one of these integrations.

Array<string>
not_managed_by
Not Managed By

Normalized integration resource ids (e.g. aws, crowdstrike). Excludes endpoints managed by any of these integrations.

Array<string>
last_seen_within_days
Last Seen Within Days

Keeps only endpoints last seen within this many days, by their agent or by any source. An endpoint no agent or source reports a last-seen time for stays in scope. Targets leave the scope when their endpoint goes quiet and return when it reports again.

integer
>= 1 <= 365
finding_filter
required
Finding Filter

Filter criteria a target’s open findings must meet for the target to be in scope.

object
finding_types
Finding Types

Types of findings to include.

Array<string>
Allowed values: vulnerability deprecation compliance licensing standardization
min_severity
Minimum Severity

Minimum severity level for findings to be in scope.

string
Allowed values: critical high medium low info
min_cvss_score
Minimum CVSS Score

Minimum CVSS score for findings to be in scope (0-10).

number format: double
<= 10
min_epss_score
Minimum EPSS Score

Minimum EPSS score for findings to be in scope. EPSS is the probability that a CVE is exploited in the wild, carried as the published 0-1 value. A finding whose CVE has no published score never satisfies this bound.

number format: double
<= 1
min_epss_percentile
Minimum EPSS Percentile

Minimum EPSS percentile for findings to be in scope. The percentile ranks a CVE against the rest of the scored corpus rather than estimating a probability, so a bound here keeps its meaning as the model is retrained while a score bound does not. A finding whose CVE has no published percentile never satisfies this bound. When set alongside other criteria, one open finding must satisfy all of them together.

number format: double
<= 1
kev_only
KEV Only

Only include findings in the CISA Known Exploited Vulnerabilities catalog.

boolean
created_at
required
Created At

When the scope was created.

string format: date-time
updated_at
required
Updated At

When the scope was last updated.

string format: date-time
total
required
Total

Total number of scopes matching the filters.

integer
limit
required
Limit

Page size used.

integer
offset
required
Offset

Offset used.

integer
Example
{
  "data": [
    {
      "status": "active",
      "subject_filter": {
        "subject_types": [
          "software"
        ]
      },
      "endpoint_filter": {
        "os_families": [
          "macos"
        ]
      },
      "finding_filter": {
        "finding_types": [
          "vulnerability"
        ],
        "min_severity": "critical"
      }
    }
  ]
}

401

Section titled “401”

Missing or invalid API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
Examplegenerated
{
  "error": "example"
}

500

Section titled “500”

Internal server error.

Media typeapplication/json
object
error
required

Human-readable error message.

string
Examplegenerated
{
  "error": "example"
}