openapi: 3.0.3
info:
  title: Local News AggregationCount Entities API
  description: 'The Local News API provides access to local news articles with location-specific filtering capabilities.


    ## Standard endpoints


    - `/search`: Search articles by keywords with simple location filtering ("City, State" format).

    - `/latest_headlines`: Retrieve recent articles for specified locations and time periods.

    - `/search_by`: Retrieve articles by URL, ID, or RSS GUID.

    - `/sources`: List available news sources.


    ## Advanced endpoints


    - `/search/advanced`: Search with structured GeoNames filtering.

    - `/latest_headlines/advanced`: Latest headlines with structured GeoNames filtering.


    ## Features


    - Multiple location detection methods including dedicated sources, proximity analysis, and AI extraction

    - Natural language processing for sentiment analysis and entity recognition on original content and English translations

    - Article clustering for topic analysis

    - English translations for non-English content

    '
  termsOfService: https://newscatcherapi.com/terms-of-service
  contact:
    name: Maksym Sugonyaka
    email: maksym@newscatcherapi.com
    url: https://www.newscatcherapi.com/book-a-demo
  version: 1.2.0
servers:
- url: https://local-news.newscatcherapi.com
  description: Local News API production server
security:
- ApiKeyAuth: []
tags:
- name: Entities
  description: 'Operations to create, update, and delete company entities.


    Entities are the building blocks of Company Watchlist. Each entity represents

    a company (or person) you want to track. Add identifying information such as

    domain, alternative names, and key persons to improve matching quality.

    '
  externalDocs:
    description: Learn about Company Watchlist and entities
    url: https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/company-search
paths:
  /catchAll/entities:
    get:
      tags:
      - Entities
      summary: List entities
      description: 'Returns a paginated list of entities belonging to the authenticated organization. Supports filtering by status and entity type, and sorting by name, status, or creation date.

        '
      operationId: listEntities
      parameters:
      - $ref: '#/components/parameters/Page'
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          default: 100
          minimum: 1
          maximum: 500
        description: Number of entities per page.
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Filter entities by name (case-insensitive substring match).
        example: NewsCatcher
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/EntityStatus'
      - name: entity_type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/EntityType'
      - name: sort_by
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/EntitySortBy'
      - name: sort_order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
      responses:
        '200':
          $ref: '#/components/responses/EntityListResponse'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    post:
      tags:
      - Entities
      summary: Create entity
      description: 'Creates a new company entity and begins background enrichment.


        The entity status starts as `pending` and transitions to `ready` once

        enrichment completes. Provide as much identifying information as

        possible — `domain` is the highest-signal field because it is

        unambiguous.

        '
      operationId: createEntity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntityRequest'
            example:
              name: NewsCatcher
              entity_type: company
              description: AI-powered news data provider
              additional_attributes:
                company_attributes:
                  domain: newscatcherapi.com
                  alternative_names:
                  - NC
                  - NewsCatcher API
                  key_persons:
                  - Artem Bugara
                  - Maksym Sugonyaka
      responses:
        '200':
          $ref: '#/components/responses/CreateEntityResponse'
        '400':
          $ref: '#/components/responses/EntityBadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /catchAll/entities/batch:
    post:
      tags:
      - Entities
      summary: Create entities in batch
      description: 'Creates multiple entities in a single request. Each entity is processed independently — a failure in one does not affect others.


        Returns an array of `{id, status}` objects in the same order as the input array.

        '
      operationId: createEntitiesBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntitiesBatchRequest'
            example:
              entities:
              - name: OpenAI
                entity_type: company
                description: Artificial intelligence research company
                additional_attributes:
                  company_attributes:
                    domain: openai.com
                    alternative_names:
                    - Open AI
                    key_persons:
                    - Sam Altman
              - name: Stripe
                entity_type: company
                description: Online payment processing platform
                additional_attributes:
                  company_attributes:
                    domain: stripe.com
                    key_persons:
                    - Patrick Collison
                    - John Collison
      responses:
        '200':
          $ref: '#/components/responses/CreateEntitiesBatchResponse'
        '400':
          $ref: '#/components/responses/EntityBadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /catchAll/entities/{entity_id}:
    get:
      tags:
      - Entities
      summary: Get entity
      description: Returns a single entity by ID with all attributes and current status.
      operationId: getEntity
      parameters:
      - $ref: '#/components/parameters/EntityId'
      responses:
        '200':
          $ref: '#/components/responses/EntityResponse'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      tags:
      - Entities
      summary: Update entity
      description: 'Updates one or more fields of an existing entity.

        '
      operationId: updateEntity
      parameters:
      - $ref: '#/components/parameters/EntityId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntityRequest'
            example:
              description: Updated description
              additional_attributes:
                company_attributes:
                  alternative_names:
                  - NC
                  - NewsCatcher API
                  - NCA
      responses:
        '200':
          $ref: '#/components/responses/EntityResponse'
        '400':
          $ref: '#/components/responses/EntityBadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      tags:
      - Entities
      summary: Delete entity
      description: 'Permanently deletes an entity. The entity is removed from all

        datasets and the search index. This operation cannot be undone.

        '
      operationId: deleteEntity
      parameters:
      - $ref: '#/components/parameters/EntityId'
      responses:
        '204':
          description: Entity deleted successfully. No response body.
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  responses:
    EntityBadRequestError:
      description: 'Validation error in entity field values.


        Returned when required fields are missing or field values are invalid

        (for example, an unrecognised `entity_type` value). The response body

        uses a `message`/`status`/`status_code` structure, distinct from the

        standard `detail`-based error format used elsewhere in the API.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EntityValidationErrorBody'
          examples:
            missing_name:
              summary: Required field missing
              value:
                message: 'Validation Error with the following fields: [{''field'': ''body.name'', ''message'': ''field required'', ''type'': ''value_error.missing''}]'
                status: Bad Request
                status_code: 400
            invalid_entity_type:
              summary: Invalid enum value
              value:
                message: 'Validation Error with the following fields: [{''field'': ''body.entity_type'', ''message'': "entity_type must be one of (''company'', ''person'')", ''type'': ''value_error''}]'
                status: Bad Request
                status_code: 400
    NotFoundError:
      description: Job/monitor not found or results not available
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    EntityListResponse:
      description: Paginated list of entities.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EntityListResponse'
    ForbiddenError:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    EntityResponse:
      description: Full entity object with all attributes and metadata.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EntityResponse'
          example:
            id: 854198fa-f702-49db-a381-0427fa87f173
            entity_type: company
            organization_id: e5d9e9b0-e415-4941-8ef0-916c5ee56207
            name: NewsCatcher
            description: AI-powered news data provider
            additional_attributes:
              company_attributes:
                domain: newscatcherapi.com
                description: Provider of news and web search APIs for developers
                key_persons:
                - Artem Bugara
                - Maksym Sugonyaka
                alternative_names:
                - NC
                - NewsCatcher API
            status: ready
            created_by_user_id: 870e258e-12ec-4a47-8656-e7a43b0265b3
            created_at: '2026-04-08T15:21:17.272139'
            updated_at: '2026-04-08T15:21:18.248316'
    CreateEntitiesBatchResponse:
      description: Batch of entities created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateEntitiesBatchResponse'
          example:
            entities:
            - id: 88430468-d784-485d-84d5-6964a29ccd1e
              status: pending
            - id: ad4908fe-6db5-4237-a137-68dd8fc9fedc
              status: pending
            count: 2
    CreateEntityResponse:
      description: Entity created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateEntityResponse'
          example:
            id: 854198fa-f702-49db-a381-0427fa87f173
            status: pending
  schemas:
    UpdateEntityRequest:
      type: object
      description: 'Request body for updating an entity. All fields are optional — only fields included in the request are updated. Fields not included are left unchanged.


        **Note**: When updating `additional_attributes.company_attributes`, the provided object replaces the existing company attributes in full. Include all attribute fields you want to retain.

        '
      properties:
        name:
          type: string
          description: Updated entity name.
          example: NewsCatcher Inc.
        description:
          type: string
          description: Updated description.
          example: Updated description
        additional_attributes:
          $ref: '#/components/schemas/AdditionalAttributes'
    AdditionalAttributes:
      type: object
      description: Additional attributes for the entity, keyed by entity type.
      properties:
        company_attributes:
          $ref: '#/components/schemas/CompanyAttributes'
    CreateEntityResponse:
      type: object
      required:
      - id
      - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the created entity.
          example: 854198fa-f702-49db-a381-0427fa87f173
        status:
          type: string
          description: 'Initial status of the entity. Always `pending` immediately after creation — enrichment happens asynchronously.

            '
          example: pending
    CreateEntitiesBatchResponse:
      type: object
      required:
      - entities
      - count
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/CreateEntityResponse'
          description: 'Array of created entity stubs in the same order as the input.

            '
        count:
          type: integer
          description: Total number of entities created.
          example: 3
    CreateEntitiesBatchRequest:
      type: object
      required:
      - entities
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/CreateEntityRequest'
          description: 'Array of entities to create. Each item follows the same schema

            as single entity creation.

            '
          minItems: 1
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message.
          example: Invalid API key
    CreateEntityRequest:
      type: object
      required:
      - name
      description: 'Request body for creating a single entity. Only `name` is required.

        The more fields you provide, the better the matching quality.

        '
      properties:
        name:
          type: string
          minLength: 1
          description: The company or person name. Required and must be non-empty.
          example: NewsCatcher
        entity_type:
          $ref: '#/components/schemas/EntityType'
        description:
          type: string
          description: 'Free-text description of the entity used for disambiguation when similar names exist.

            '
          example: AI-powered news data provider
        additional_attributes:
          $ref: '#/components/schemas/AdditionalAttributes'
    EntityResponse:
      type: object
      required:
      - id
      - entity_type
      - organization_id
      - name
      - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the entity.
          example: 854198fa-f702-49db-a381-0427fa87f173
        entity_type:
          $ref: '#/components/schemas/EntityType'
        organization_id:
          type: string
          format: uuid
          description: Organization that owns this entity.
          example: e5d9e9b0-e415-4941-8ef0-916c5ee56207
        name:
          type: string
          description: Entity name.
          example: NewsCatcher
        description:
          type:
          - string
          - 'null'
          description: Free-text description.
          example: AI-powered news data provider
        additional_attributes:
          $ref: '#/components/schemas/AdditionalAttributes'
        status:
          $ref: '#/components/schemas/EntityStatus'
        created_by_user_id:
          type: string
          format: uuid
          description: ID of the user who created this entity.
          example: 870e258e-12ec-4a47-8656-e7a43b0265b3
        created_at:
          type: string
          format: date-time
          description: 'ISO 8601 timestamp of when the entity was created. Returned without timezone offset (server-local time).

            '
          example: '2026-04-08T15:21:17.272139'
        updated_at:
          type: string
          format: date-time
          description: 'ISO 8601 timestamp of when the entity was last updated. Returned without timezone offset (server-local time).

            '
          example: '2026-04-08T15:21:18.248316'
    EntityValidationErrorBody:
      type: object
      required:
      - message
      - status
      - status_code
      description: 'Error body returned by entity endpoints for field-level validation

        failures. Uses a different structure from the standard `Error` schema

        (`{"detail": "..."}`) used elsewhere in the API.

        '
      properties:
        message:
          type: string
          description: 'Human-readable description of all validation errors, including

            field path, failure message, and error type.

            '
          example: 'Validation Error with the following fields: [{''field'': ''body.entity_type'', ''message'': "entity_type must be one of (''company'', ''person'')", ''type'': ''value_error''}]'
        status:
          type: string
          description: HTTP status text.
          example: Bad Request
        status_code:
          type: integer
          description: HTTP status code.
          example: 400
    EntityType:
      type: string
      enum:
      - company
      - person
      description: 'The type of entity.


        - `company`: A company or organization (default).

        - `person`: An individual person.

        '
      default: company
    EntitySortBy:
      type: string
      enum:
      - created_at
      - name
      - status
      description: Fields available for sorting entity list results.
      default: created_at
    EntityListResponse:
      type: object
      required:
      - entities
      - total
      - page
      - page_size
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
          description: Array of entity objects for this page.
        total:
          type: integer
          description: Total number of entities matching the filter criteria.
          example: 17
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of entities per page.
          example: 100
    EntityStatus:
      type: string
      enum:
      - pending
      - enriching
      - ready
      - failed
      description: 'Processing status of an entity.


        - `pending`: Entity has been created and is queued for enrichment.

        - `enriching`: Enrichment is in progress.

        - `ready`: Enrichment complete — entity is indexed and ready for use in jobs.

        - `failed`: Enrichment failed. The entity may still be used but matching quality may be reduced.

        '
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      description: 'Sort direction for list results.


        - `asc`: ascending (oldest or smallest first)

        - `desc`: descending (newest or largest first)

        '
      default: desc
    CompanyAttributes:
      type: object
      description: 'Identifying attributes for a company entity. All fields are optional but improve matching quality.

        '
      properties:
        domain:
          type:
          - string
          - 'null'
          description: 'Company website domain without protocol or trailing slash.


            The most reliable identifier — strongly recommended when available.

            '
          example: newscatcherapi.com
        description:
          type:
          - string
          - 'null'
          description: Detailed description of the company used for matching.
          example: Provider of news and web search APIs for developers
        key_persons:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'Names of key people associated with the company (founders, executives, etc.). Improves matching for articles that mention people rather than the company name.

            '
          example:
          - Artem Bugara
          - Maksym Sugonyaka
        alternative_names:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'Alternative names, abbreviations, or aliases. Helps resolve common variations of the company name.

            '
          example:
          - NC
          - NewsCatcher API
  parameters:
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      description: 'Page number to retrieve.

        '
    EntityId:
      name: entity_id
      in: path
      required: true
      description: Unique entity identifier.
      schema:
        type: string
        format: uuid
      example: 854198fa-f702-49db-a381-0427fa87f173
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-token
      description: "API Key to authenticate requests.\n\nTo access the API, include your API key in the `x-api-token` header. \nTo obtain your API key, complete the [form](https://www.newscatcherapi.com/book-a-demo) or contact us directly.\n"
externalDocs:
  description: Find out more about Local News API
  url: https://www.newscatcherapi.com/docs/local-news-api/get-started/introduction