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