Perigon

Perigon Watchlists API

Manage watchlists of people and companies for use with monitors. Watchlists can contain up to 100 combined entities and are used to track mentions across news content.

GitHub OpenAPI

Operations 6

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /v1/api/watchlists List watchlists · List watchlists #
Ask an LLM
“Which watchlists of people and companies can I use?”
“Can I filter my watchlists by name?”
Tell an agent
List my watchlists sorted by {sortBy} {sortOrder}.
Show watchlists matching {name}, ordered by {sortBy} {sortOrder}.
POST /v1/api/watchlists Create a watchlist of people and companies · Create watchlist #
Ask an LLM
“How do I build a watchlist of executives and companies to track?”
“How many people and companies can a single watchlist hold?”
Tell an agent
Create a watchlist named {name} with people {people} and companies {companies}.
Make a private watchlist {name} tracking {companies} and {people}, visibility {visible}.
GET /v1/api/watchlists/resolve Resolve watchlist names · Resolve watchlists #
Ask an LLM
“If a private watchlist and a public one share a name, which does a lookup by name return?”
“Can I resolve several watchlist names at once?”
Tell an agent
Resolve the watchlist names {name}.
Work out which watchlist the name {name} refers to for my organization.
GET /v1/api/watchlists/{id} Get a watchlist by ID · Get watchlist #
Ask an LLM
“Who is on a particular watchlist?”
“Can I fetch one watchlist by its ID?”
Tell an agent
Show watchlist {id}.
List the people and companies on watchlist {id}.
DELETE /v1/api/watchlists/{id} Delete a watchlist · Delete watchlist #
Ask an LLM
“Why can't I delete a watchlist that active monitors use?”
“How do I remove a watchlist I own?”
Tell an agent destructive · confirm first
Delete watchlist {id}.
Remove watchlist {id} from my organization.
PATCH /v1/api/watchlists/{id} Update a watchlist · Update watchlist #
Ask an LLM
“Can I add companies to a watchlist I already made?”
“Is it possible to make an existing watchlist public or private?”
Tell an agent
Set the companies on watchlist {id} to {companies}.
Change watchlist {id} visibility to {visible}.

Documentation

📖
Documentation
https://perigon.io/docs/api/intro
📖
APIReference
https://perigon.io/reference
📖
GettingStarted
https://perigon.io/docs/api/getting-started

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/perigon/refs/heads/main/openapi/perigon-watchlists-api-openapi.yml

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/perigon:perigon-watchlists-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

perigon-watchlists-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Perigon Watchlists API
  description: The Perigon API provides access to comprehensive news and web content data. To use the API, simply sign up for a Perigon Business Solutions account to obtain your API key. Your available features may vary based on your plan. See the Authentication section for details on how to use your API key.
  contact:
    name: Perigon Support
    url: https://docs.perigon.io/
    email: data@perigon.io
  version: 1.0.0
servers:
- url: https://api.perigon.io
  description: Generated server url
security:
- apiKeyAuth: []
tags:
- name: Watchlists
  description: Manage watchlists of people and companies for use with monitors. Watchlists can contain up to 100 combined entities and are used to track mentions across news content.
paths:
  /v1/api/watchlists:
    get:
      tags:
      - Watchlists
      summary: List watchlists
      description: List watchlists owned by the organization associated with the API key, as well as publicly visible watchlists. Supports filtering by name.
      operationId: list-watchlists
      parameters:
      - name: name
        in: query
        description: Filter watchlists by name (case-insensitive, partial match)
        required: false
        schema:
          type: string
      - name: sortBy
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/WatchlistSortBy'
      - name: page
        in: query
        description: Zero-based page number to retrieve. Defaults to 0.
        required: false
        schema:
          minimum: 0
          type: integer
          description: Zero-based page number to retrieve. Defaults to 0.
          format: int32
          default: 0
      - name: size
        in: query
        description: Number of results per page. Must be between 1 and 100; defaults to 10.
        required: false
        schema:
          maximum: 100
          minimum: 1
          type: integer
          description: Number of results per page. Must be between 1 and 100; defaults to 10.
          format: int32
          default: 10
      - name: sortOrder
        in: query
        description: Required direction used to sort results. Accepts asc or desc.
        required: true
        schema:
          type: string
          description: Required direction used to sort results. Accepts asc or desc.
          enum:
          - asc
          - desc
      - name: nulls
        in: query
        description: Placement of null values in sorted results. Accepts first or last.
        required: false
        schema:
          type: string
          description: Placement of null values in sorted results. Accepts first or last.
          enum:
          - first
          - last
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistListResult'
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
    post:
      tags:
      - Watchlists
      summary: Create watchlist
      description: Create a new watchlist under the organization associated with the API key. A watchlist can contain up to 100 combined people and companies.
      operationId: create-watchlist
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWatchlistParams'
        required: true
      responses:
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResult'
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/api/watchlists/resolve:
    get:
      tags:
      - Watchlists
      summary: Resolve watchlists
      description: Resolve watchlists by name. For each name, returns the organization's private watchlist if one exists, otherwise falls back to the matching public watchlist.
      operationId: resolve-watchlists
      parameters:
      - name: name
        in: query
        description: Watchlist names to resolve (max 100)
        required: false
        schema:
          maxItems: 100
          minItems: 0
          type: array
          items:
            type: string
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResolveResult'
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/api/watchlists/{id}:
    get:
      tags:
      - Watchlists
      summary: Get watchlist
      description: Retrieve a watchlist by ID. Only returns watchlists owned by the organization associated with the API key.
      operationId: get-watchlist
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResult'
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
    delete:
      tags:
      - Watchlists
      summary: Delete watchlist
      description: Delete a watchlist owned by the organization associated with the API key. A watchlist cannot be deleted if it is attached to active monitors.
      operationId: delete-watchlist
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResult'
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
    patch:
      tags:
      - Watchlists
      summary: Update watchlist
      description: Partially update a watchlist owned by the organization associated with the API key. Only provided fields will be updated.
      operationId: update-watchlist
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWatchlistParams'
        required: true
      responses:
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResult'
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
components:
  schemas:
    WatchlistPerson:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        aliases:
          type:
          - array
          - 'null'
          items:
            type: string
        wikidataId:
          type:
          - string
          - 'null'
        query:
          type:
          - string
          - 'null'
      description: Updated list of people to include in the watchlist
    WatchlistListResult:
      required:
      - data
      - total
      type: object
      properties:
        total:
          type: integer
          description: Total number of matching watchlists across all pages.
          format: int64
        data:
          type: array
          description: Watchlists returned for the requested page.
          items:
            $ref: '#/components/schemas/WatchlistDto'
      description: Paginated list of watchlists.
      example:
        total: 1
        data:
        - id: 42
          createdAt: '2025-06-01T09:00:00.000Z'
          updatedAt: '2025-08-01T16:30:00.000Z'
          name: ai-executives
          displayName: AI Executives
          description: Leadership at major AI companies.
          people: []
          companies: []
          organizationId: 1001
          visible: true
    ErrorResponse:
      type: object
      properties:
        status:
          type:
          - integer
          - 'null'
          format: int32
        message:
          type:
          - string
          - 'null'
        timestamp:
          type:
          - integer
          - 'null'
          format: int64
    WatchlistDto:
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
          description: Numeric identifier for the watchlist.
          format: int32
        createdAt:
          type:
          - string
          - 'null'
          description: Date and time the watchlist was created, in ISO 8601 format.
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          description: Date and time the watchlist was last updated, in ISO 8601 format.
          format: date-time
        name:
          type:
          - string
          - 'null'
          description: Unique slug name for the watchlist.
        displayName:
          type:
          - string
          - 'null'
          description: Human-readable display name.
        description:
          type:
          - string
          - 'null'
          description: Optional description of the watchlist.
        people:
          type:
          - array
          - 'null'
          description: People included in the watchlist.
          items:
            $ref: '#/components/schemas/WatchlistPersonDto'
        companies:
          type:
          - array
          - 'null'
          description: Companies included in the watchlist.
          items:
            $ref: '#/components/schemas/WatchlistCompanyDto'
        organizationId:
          type:
          - integer
          - 'null'
          description: Owning organization ID when the watchlist is private.
          format: int32
        visible:
          type:
          - boolean
          - 'null'
          description: Whether the watchlist is publicly visible.
      description: Watchlist of people and companies for use with monitors.
    CreateWatchlistParams:
      required:
      - companies
      - name
      - people
      type: object
      properties:
        name:
          type: string
          description: Unique name for the watchlist within the organization
        displayName:
          type:
          - string
          - 'null'
          description: Display name for the watchlist
        description:
          type:
          - string
          - 'null'
          description: Description of the watchlist
        people:
          maxItems: 100
          minItems: 0
          type: array
          description: List of people to include in the watchlist
          items:
            $ref: '#/components/schemas/WatchlistPerson'
        companies:
          maxItems: 100
          minItems: 0
          type: array
          description: List of companies to include in the watchlist
          items:
            $ref: '#/components/schemas/WatchlistCompany'
        visible:
          type:
          - boolean
          - 'null'
          description: Whether the watchlist is visible in the UI
          default: true
    WatchlistCompany:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        id:
          type:
          - string
          - 'null'
        domain:
          type:
          - string
          - 'null'
        aliases:
          type:
          - array
          - 'null'
          items:
            type: string
        query:
          type:
          - string
          - 'null'
      description: Updated list of companies to include in the watchlist
    WatchlistPersonDto:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        wikidataId:
          type:
          - string
          - 'null'
        aliases:
          type:
          - array
          - 'null'
          items:
            type: string
        query:
          type:
          - string
          - 'null'
      description: People included in the watchlist.
    WatchlistResolveResult:
      required:
      - data
      type: object
      properties:
        data:
          type: array
          description: Resolved watchlists.
          items:
            $ref: '#/components/schemas/WatchlistDto'
      description: Resolved watchlists response.
      example:
        data:
        - id: 42
          createdAt: '2025-06-01T09:00:00.000Z'
          updatedAt: '2025-08-01T16:30:00.000Z'
          name: ai-executives
          displayName: AI Executives
          description: Leadership at major AI companies.
          people: []
          companies: []
          organizationId: 1001
          visible: true
    WatchlistResult:
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WatchlistDto'
      description: Single watchlist response.
      example:
        data:
          id: 42
          createdAt: '2025-06-01T09:00:00.000Z'
          updatedAt: '2025-08-01T16:30:00.000Z'
          name: ai-executives
          displayName: AI Executives
          description: Leadership at major AI companies.
          people:
          - name: Sam Altman
            description: CEO of OpenAI
            wikidataId: Q7411063
            aliases: []
          companies:
          - name: OpenAI
            description: AI research company
            id: openai
            domain: openai.com
            aliases: []
          organizationId: 1001
          visible: true
    WatchlistSortBy:
      type: string
      enum:
      - id
      - createdAt
      - updatedAt
      - name
    WatchlistCompanyDto:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        id:
          type:
          - string
          - 'null'
        domain:
          type:
          - string
          - 'null'
        aliases:
          type:
          - array
          - 'null'
          items:
            type: string
        query:
          type:
          - string
          - 'null'
      description: Companies included in the watchlist.
    UpdateWatchlistParams:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: New name for the watchlist
        displayName:
          type:
          - string
          - 'null'
          description: New display name for the watchlist
        description:
          type:
          - string
          - 'null'
          description: New description for the watchlist
        people:
          type:
          - array
          - 'null'
          description: Updated list of people to include in the watchlist
          items:
            $ref: '#/components/schemas/WatchlistPerson'
        companies:
          type:
          - array
          - 'null'
          description: Updated list of companies to include in the watchlist
          items:
            $ref: '#/components/schemas/WatchlistCompany'
        visible:
          type:
          - boolean
          - 'null'
          description: Whether the watchlist is visible in the UI
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer