NudgeLink Scout API
The scout API from NudgeLink — 11 operation(s) for scout.
The scout API from NudgeLink — 11 operation(s) for scout.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nudgelink-co:nudgelink-co-scout-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: NudgeLink Scout API
version: 0.1.0
tags:
- name: scout
paths:
/api/v1/scout/entities:
get:
tags:
- scout
summary: List Entities
description: 'Review list. ``run_id`` narrows it to what one run found (the page''s
default — before 2026-09-23 every tab mixed every campaign''s results).'
operationId: list_entities_api_v1_scout_entities_get
security:
- HTTPBearer: []
parameters:
- name: view
in: query
required: false
schema:
type: string
pattern: ^(companies|people|needs_verification)$
default: companies
title: View
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
- name: run_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Run Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScoutEntityList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/scout/accept:
post:
tags:
- scout
summary: Accept Entities
description: 'Bulk-accept resolved people into Leads. Excludes anything not campaign-ready
and reports why, so the UI can state "N skipped". Companies are never accepted.'
operationId: accept_entities_api_v1_scout_accept_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/scout/entities/dismiss:
post:
tags:
- scout
summary: Dismiss Entities
description: 'Hide wrong finds (or bring them back with ``undo``). A dismissed entity
stays hidden when a later run finds it again: ``suppressed`` lives on the
tenant-level entity, which re-discovery reuses.'
operationId: dismiss_entities_api_v1_scout_entities_dismiss_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DismissRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Dismiss Entities Api V1 Scout Entities Dismiss Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/scout/entities/{entity_id}/resolve:
post:
tags:
- scout
summary: Resolve Entity
description: '"Add with this LinkedIn URL" from Check by hand. Free: the customer did
the matching (manual lead adds are free too); Scout charges only for people
it matched itself.'
operationId: resolve_entity_api_v1_scout_entities__entity_id__resolve_post
security:
- HTTPBearer: []
parameters:
- name: entity_id
in: path
required: true
schema:
type: string
format: uuid
title: Entity Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ManualResolveRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ManualResolveResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/scout/runs/preview:
post:
tags:
- scout
summary: Preview Web Run
description: 'What a run with this campaign + brief would search for, and what it
would reserve. No spend, no run row, no provider call.'
operationId: preview_web_run_api_v1_scout_runs_preview_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScoutRunRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScoutPreviewResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/scout/brief/draft:
post:
tags:
- scout
summary: Draft Brief
description: '"Describe it in words": a sentence -> a brief the page shows for review.
Never starts a run. Free for the customer; one small Haiku call.'
operationId: draft_brief_api_v1_scout_brief_draft_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BriefDraftRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScoutBrief'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/scout/capabilities:
get:
tags:
- scout
summary: Capabilities
operationId: capabilities_api_v1_scout_capabilities_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Capabilities Api V1 Scout Capabilities Get
security:
- HTTPBearer: []
/api/v1/scout/runs:
post:
tags:
- scout
summary: Start Web Run
operationId: start_web_run_api_v1_scout_runs_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScoutRunRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StartWebRunResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/scout/runs/latest:
get:
tags:
- scout
summary: Latest Web Run
description: 'The newest Scout run with its stage stats, plus the tab counts.
2026-09-23: the page had no way to show a run at all — a run that found
nobody ended as "Nothing here yet." with no hint whether the search
returned nothing, pages were unreadable, or people were found but never
matched to LinkedIn. This is what the page''s run panel reads.'
operationId: latest_web_run_api_v1_scout_runs_latest_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScoutRunStatus'
security:
- HTTPBearer: []
/api/v1/scout/runs/{run_id}/retry:
post:
tags:
- scout
summary: Retry Web Run
operationId: retry_web_run_api_v1_scout_runs__run_id__retry_post
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
format: uuid
title: Run Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StartWebRunResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/scout/runs/{run_id}/cancel:
post:
tags:
- scout
summary: Cancel Web Run
operationId: cancel_web_run_api_v1_scout_runs__run_id__cancel_post
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
format: uuid
title: Run Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Cancel Web Run Api V1 Scout Runs Run Id Cancel Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
DismissRequest:
properties:
entity_ids:
items:
type: string
format: uuid
type: array
maxItems: 200
title: Entity Ids
undo:
type: boolean
title: Undo
default: false
type: object
required:
- entity_ids
title: DismissRequest
ScoutPreviewResponse:
properties:
brief:
$ref: '#/components/schemas/ScoutBrief'
people_queries:
items:
type: string
type: array
title: People Queries
company_queries:
items:
type: string
type: array
title: Company Queries
reserved_credits:
type: integer
title: Reserved Credits
max_people:
type: integer
title: Max People
warnings:
items:
$ref: '#/components/schemas/PreviewWarning'
type: array
title: Warnings
people_after_companies:
type: boolean
title: People After Companies
default: false
type: object
required:
- brief
- people_queries
- company_queries
- reserved_credits
- max_people
- warnings
title: ScoutPreviewResponse
ScoutRunStatus:
properties:
run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Run Id
status:
anyOf:
- type: string
- type: 'null'
title: Status
stage:
anyOf:
- type: string
- type: 'null'
title: Stage
failure_reason:
anyOf:
- type: string
- type: 'null'
title: Failure Reason
can_run_again:
type: boolean
title: Can Run Again
default: false
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
completed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Completed At
credits_used:
type: integer
title: Credits Used
default: 0
stats:
additionalProperties: true
type: object
title: Stats
default: {}
counts:
additionalProperties:
type: integer
type: object
title: Counts
default: {}
type: object
title: ScoutRunStatus
ManualResolveResponse:
properties:
lead_id:
type: string
format: uuid
title: Lead Id
linkedin_url:
type: string
title: Linkedin Url
type: object
required:
- lead_id
- linkedin_url
title: ManualResolveResponse
SearchFilters:
properties:
location:
items:
type: string
type: array
maxItems: 20
title: Location
company:
items:
type: string
type: array
maxItems: 20
title: Company
past_company:
items:
type: string
type: array
maxItems: 20
title: Past Company
school:
items:
type: string
type: array
maxItems: 20
title: School
industry:
items:
type: string
type: array
maxItems: 20
title: Industry
skills:
items:
type: string
type: array
maxItems: 20
title: Skills
type: object
title: SearchFilters
description: 'Structured LinkedIn people-search filters (Discovery v2, basket 1).
Every facet field carries LinkedIn *IDs* (not free text), resolved
client-side via the typeahead endpoint
(``GET /api/v1/leads/discover/search-parameters``), which proxies Unipile''s
``/linkedin/search/parameters``. Sending the wrong shape (free text where an
ID is expected) is exactly what made classic search return nothing before, so
the model only carries IDs and the adapter drops anything it can''t map.
Form-supplied filters take priority over the ICP (the ICP only fills a facet
the form left blank — see ``lead_finder._assemble_structured_filters``).
This model is search-time facets only. Free-text "work keywords" + AND/OR and
the company-size buckets are post-fetch SOFT signals and live as separate
``DiscoverRequest`` fields, not here (ТЗ v2 §B6/§B4).
``network_distance`` is deliberately absent: discovery is pinned to 2nd + 3rd
degree (1st-degree is excluded — those are usually already in conversation —
while 3rd-degree strangers are the target of cold outreach). ``to_filter_dict``
injects ``[2, 3]`` unconditionally so the rule is enforced server-side
regardless of the client. Safe even if LinkedIn rejects degree 3 on a free
seat: classic search then degrades to keywords-only (see
``unipile.search_profiles``). Confirm free-seat acceptance with
``backend/scripts/discovery_v2_spike.py`` (§E.2).'
ScoutEntityList:
properties:
entities:
items:
$ref: '#/components/schemas/ScoutEntityOut'
type: array
title: Entities
type: object
required:
- entities
title: ScoutEntityList
AcceptRequest:
properties:
entity_ids:
items:
type: string
format: uuid
type: array
title: Entity Ids
run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Run Id
type: object
required:
- entity_ids
title: AcceptRequest
StartWebRunResponse:
properties:
run_id:
type: string
format: uuid
title: Run Id
reserved_credits:
type: integer
title: Reserved Credits
status:
type: string
title: Status
type: object
required:
- run_id
- reserved_credits
- status
title: StartWebRunResponse
PreviewWarning:
properties:
code:
type: string
title: Code
terms:
items:
type: string
type: array
title: Terms
default: []
type: object
required:
- code
title: PreviewWarning
BriefDraftRequest:
properties:
text:
type: string
maxLength: 1000
minLength: 3
title: Text
type: object
required:
- text
title: BriefDraftRequest
ScoutRunRequest:
properties:
target_limit:
type: integer
maximum: 100.0
minimum: 1.0
title: Target Limit
default: 5
score_threshold:
type: integer
maximum: 100.0
minimum: 0.0
title: Score Threshold
default: 60
extra_keywords:
anyOf:
- items:
type: string
type: array
maxItems: 10
- type: 'null'
title: Extra Keywords
deep_search:
type: boolean
title: Deep Search
default: false
filters:
anyOf:
- $ref: '#/components/schemas/SearchFilters'
- type: 'null'
work_keywords:
items:
type: string
type: array
maxItems: 20
title: Work Keywords
work_keywords_mode:
type: string
enum:
- and
- or
title: Work Keywords Mode
default: or
company_sizes:
items:
type: string
enum:
- 1-10
- 11-50
- 51-200
- 201-500
- 501-1000
- 1001+
type: array
maxItems: 6
title: Company Sizes
filter_labels:
additionalProperties:
items:
type: string
type: array
type: object
title: Filter Labels
campaign_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Campaign Id
post_url:
anyOf:
- type: string
maxLength: 512
- type: 'null'
title: Post Url
brief:
anyOf:
- $ref: '#/components/schemas/ScoutBrief'
- type: 'null'
find_more:
type: boolean
title: Find More
default: false
type: object
title: ScoutRunRequest
ScoutBrief:
properties:
mode:
anyOf:
- type: string
enum:
- titles
- companies
- lookalike
- type: 'null'
title: Mode
target_companies:
anyOf:
- items:
type: string
type: array
maxItems: 25
- type: 'null'
title: Target Companies
seed_companies:
anyOf:
- items:
type: string
type: array
maxItems: 5
- type: 'null'
title: Seed Companies
titles:
anyOf:
- items:
type: string
type: array
maxItems: 10
- type: 'null'
title: Titles
industries:
anyOf:
- items:
type: string
type: array
maxItems: 5
- type: 'null'
title: Industries
locations:
anyOf:
- items:
type: string
type: array
maxItems: 5
- type: 'null'
title: Locations
exclude_titles:
anyOf:
- items:
type: string
type: array
maxItems: 25
- type: 'null'
title: Exclude Titles
exclude_companies:
anyOf:
- items:
type: string
type: array
maxItems: 50
- type: 'null'
title: Exclude Companies
type: object
title: ScoutBrief
description: 'None = keep the campaign''s value; a list (even empty) replaces it.
``mode``: titles (a role in a market), companies (those roles at the
``target_companies`` listed), lookalike (companies like ``seed_companies``,
then the roles at the companies found).'
AcceptResponse:
properties:
accepted:
type: integer
title: Accepted
skipped:
type: integer
title: Skipped
skipped_reasons:
additionalProperties:
type: string
type: object
title: Skipped Reasons
default: {}
type: object
required:
- accepted
- skipped
title: AcceptResponse
ScoutEntityOut:
properties:
id:
type: string
format: uuid
title: Id
entity_type:
type: string
title: Entity Type
display_name:
type: string
title: Display Name
canonical_domain:
anyOf:
- type: string
- type: 'null'
title: Canonical Domain
resolution_state:
type: string
title: Resolution State
linkedin_url:
anyOf:
- type: string
- type: 'null'
title: Linkedin Url
parent_entity_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Parent Entity Id
campaign_ready:
type: boolean
title: Campaign Ready
fields:
additionalProperties:
$ref: '#/components/schemas/EvidenceField'
type: object
title: Fields
default: {}
source_urls:
items:
type: string
type: array
title: Source Urls
default: []
title:
anyOf:
- type: string
- type: 'null'
title: Title
company:
anyOf:
- type: string
- type: 'null'
title: Company
location:
anyOf:
- type: string
- type: 'null'
title: Location
matches:
items:
type: string
type: array
title: Matches
default: []
already_lead:
type: boolean
title: Already Lead
default: false
add_cost:
type: integer
title: Add Cost
default: 0
fit_score:
anyOf:
- type: integer
- type: 'null'
title: Fit Score
fit_company_match:
anyOf:
- type: string
- type: 'null'
title: Fit Company Match
fit_reason:
anyOf:
- type: string
- type: 'null'
title: Fit Reason
type: object
required:
- id
- entity_type
- display_name
- resolution_state
- campaign_ready
title: ScoutEntityOut
ManualResolveRequest:
properties:
linkedin_url:
type: string
maxLength: 512
minLength: 1
title: Linkedin Url
run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Run Id
type: object
required:
- linkedin_url
title: ManualResolveRequest
EvidenceField:
properties:
value:
anyOf:
- type: string
- type: 'null'
title: Value
state:
type: string
title: State
excerpt:
type: string
title: Excerpt
default: ''
source_url:
type: string
title: Source Url
default: ''
type: object
required:
- state
title: EvidenceField
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer