Perigon

Perigon Source Groups API

Manage custom source groups for organizing and filtering news sources. Source groups allow grouping domains together for use in search queries and monitors.

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/sourceGroups List source groups · List source groups #
Ask an LLM
“Which source groups can I use, including public ones?”
“Can I find source groups that contain a particular domain?”
Tell an agent
List my source groups sorted by {sortBy} {sortOrder}.
Show source groups that include domain {domain}, sorted by {sortBy} {sortOrder}.
POST /v1/api/sourceGroups Create a source group of domains · Create source group #
Ask an LLM
“How do I bundle a set of news domains into my own source group?”
“Can I give a custom source group a display name and description?”
Tell an agent
Create a source group named {name} with domains {domains}.
Make a new source group {name} described as {description} covering {domains}.
GET /v1/api/sourceGroups/resolve Resolve source group names · Resolve source groups #
Ask an LLM
“If my private source group shares a name with a public one, which does a name lookup return?”
“Can I turn source group names into their full definitions in one call?”
Tell an agent
Resolve the source group names {name}.
Look up which source group the name {name} maps to for my organization.
GET /v1/api/sourceGroups/{id} Get a source group by ID · Get source group #
Ask an LLM
“What domains are in one of my source groups?”
“Can I fetch a single source group using its ID?”
Tell an agent
Show source group {id}.
List the domains inside source group {id}.
DELETE /v1/api/sourceGroups/{id} Delete a source group · Delete source group #
Ask an LLM
“How do I remove a source group my organization owns?”
“Can I delete a custom source group I no longer use?”
Tell an agent destructive · confirm first
Delete source group {id}.
Remove my source group {id} permanently.
PATCH /v1/api/sourceGroups/{id} Update a source group · Update source group #
Ask an LLM
“Can I add or change the domains in an existing source group?”
“Is it possible to rename a source group I already created?”
Tell an agent
Replace the domains in source group {id} with {domains}.
Rename source group {id} to {displayName}.

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-source-groups-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-source-groups-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-source-groups-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Perigon Source Groups 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: Source Groups
  description: Manage custom source groups for organizing and filtering news sources. Source groups allow grouping domains together for use in search queries and monitors.
paths:
  /v1/api/sourceGroups:
    get:
      tags:
      - Source Groups
      summary: List source groups
      description: List source groups owned by the organization associated with the API key, as well as publicly visible source groups. Supports filtering by name and domain.
      operationId: list-source-groups
      parameters:
      - name: name
        in: query
        required: false
        schema:
          type: string
      - name: domain
        in: query
        required: false
        schema:
          type: string
      - name: sortBy
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/SourceGroupSortBy'
      - 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
        '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/SourceGroupListResult'
        '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:
      - Source Groups
      summary: Create source group
      description: Create a new source group under the organization associated with the API key.
      operationId: create-source-group
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSourceGroupParams'
        required: true
      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
        '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
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceGroupResult'
        '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/sourceGroups/resolve:
    get:
      tags:
      - Source Groups
      summary: Resolve source groups
      description: Resolve source groups by name. For each name, returns the organization's private source group if one exists, otherwise falls back to the matching public source group.
      operationId: resolve-source-groups
      parameters:
      - name: name
        in: query
        description: Source group 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
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceGroupResolveResult'
        '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/sourceGroups/{id}:
    get:
      tags:
      - Source Groups
      summary: Get source group
      description: Retrieve a source group by ID. Only returns source groups owned by the organization associated with the API key.
      operationId: get-source-group
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      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
        '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
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceGroupResult'
        '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:
      - Source Groups
      summary: Delete source group
      description: Delete a source group owned by the organization associated with the API key.
      operationId: delete-source-group
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      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
        '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
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceGroupResult'
        '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:
      - Source Groups
      summary: Update source group
      description: Partially update a source group owned by the organization associated with the API key. Only provided fields will be updated.
      operationId: update-source-group
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSourceGroupParams'
        required: true
      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
        '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
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceGroupResult'
        '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:
    ErrorResponse:
      type: object
      properties:
        status:
          type:
          - integer
          - 'null'
          format: int32
        message:
          type:
          - string
          - 'null'
        timestamp:
          type:
          - integer
          - 'null'
          format: int64
    SourceGroupResult:
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SourceGroupDto'
      description: Single source group response.
      example:
        data:
          id: 17
          createdAt: '2025-05-10T08:00:00.000Z'
          updatedAt: '2025-07-20T12:45:00.000Z'
          name: tier-1-tech
          displayName: Tier 1 Tech
          description: Major technology news outlets.
          domains:
          - reuters.com
          - apnews.com
          - bbc.com
          - cnn.com
          organizationId: 1001
          visible: true
    PatchSourceGroupParams:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Unique name for the source group within the organization
        displayName:
          type:
          - string
          - 'null'
          description: Display name for the source group
        description:
          maxLength: 512
          minLength: 0
          type:
          - string
          - 'null'
          description: Description of the source group
        domains:
          maxItems: 5000
          minItems: 1
          type:
          - array
          - 'null'
          description: List of domains included in the source group
          items:
            type: string
            description: List of domains included in the source group
    CreateSourceGroupParams:
      required:
      - domains
      - name
      type: object
      properties:
        name:
          type: string
        displayName:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        domains:
          maxItems: 5000
          minItems: 1
          type: array
          items:
            type: string
    SourceGroupSortBy:
      type: string
      enum:
      - id
      - createdAt
      - updatedAt
      - name
    SourceGroupResolveResult:
      required:
      - data
      type: object
      properties:
        data:
          type: array
          description: Resolved source groups.
          items:
            $ref: '#/components/schemas/SourceGroupDto'
      description: Resolved source groups response.
      example:
        data:
        - id: 17
          createdAt: '2025-05-10T08:00:00.000Z'
          updatedAt: '2025-07-20T12:45:00.000Z'
          name: tier-1-tech
          displayName: Tier 1 Tech
          description: Major technology news outlets.
          domains:
          - reuters.com
          - apnews.com
          - bbc.com
          - cnn.com
          organizationId: 1001
          visible: true
    SourceGroupDto:
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
          description: Numeric identifier for the source group.
          format: int32
        createdAt:
          type:
          - string
          - 'null'
          description: Date and time the source group was created, in ISO 8601 format.
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          description: Date and time the source group was last updated, in ISO 8601 format.
          format: date-time
        name:
          type:
          - string
          - 'null'
          description: Unique slug name for the source group.
        displayName:
          type:
          - string
          - 'null'
          description: Human-readable display name.
        description:
          type:
          - string
          - 'null'
          description: Optional description of the source group.
        domains:
          type:
          - array
          - 'null'
          description: Publisher domains included in the group.
          items:
            type: string
            description: Publisher domains included in the group.
        organizationId:
          type:
          - integer
          - 'null'
          description: Owning organization ID when the source group is private.
          format: int32
        visible:
          type:
          - boolean
          - 'null'
          description: Whether the source group is publicly visible.
      description: Named group of news source domains for filtering search and monitors.
    SourceGroupListResult:
      required:
      - data
      - total
      type: object
      properties:
        total:
          type: integer
          description: Total number of matching source groups across all pages.
          format: int64
        data:
          type: array
          description: Source groups returned for the requested page.
          items:
            $ref: '#/components/schemas/SourceGroupDto'
      description: Paginated list of source groups.
      example:
        total: 1
        data:
        - id: 17
          createdAt: '2025-05-10T08:00:00.000Z'
          updatedAt: '2025-07-20T12:45:00.000Z'
          name: tier-1-tech
          displayName: Tier 1 Tech
          description: Major technology news outlets.
          domains:
          - reuters.com
          - apnews.com
          - bbc.com
          - cnn.com
          organizationId: 1001
          visible: true
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer