NudgeLink Scout API

The scout API from NudgeLink — 11 operation(s) for scout.

GitHub OpenAPI

Operations 11

GET /api/v1/scout/entities List Entities #
POST /api/v1/scout/accept Accept Entities #
POST /api/v1/scout/entities/dismiss Dismiss Entities #
POST /api/v1/scout/entities/{entity_id}/resolve Resolve Entity #
POST /api/v1/scout/runs/preview Preview Web Run #
POST /api/v1/scout/brief/draft Draft Brief #
GET /api/v1/scout/capabilities Capabilities #
POST /api/v1/scout/runs Start Web Run #
GET /api/v1/scout/runs/latest Latest Web Run #
POST /api/v1/scout/runs/{run_id}/retry Retry Web Run #
POST /api/v1/scout/runs/{run_id}/cancel Cancel Web Run #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nudgelink-co:nudgelink-co-scout-api"
All apis
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.

Get an API 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 Specification

nudgelink-co-scout-api-openapi.yml Raw ↑
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