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.
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