Operations to create and manage datasets of entities. A dataset is a named collection of entities — think of it as a watchlist or portfolio. Connect a dataset to a job via `connected_dataset_ids` to activate Company Watchlist. Datasets can be reused across multiple jobs and monitors.
openapi: 3.0.3
info:
title: Local News AggregationCount Datasets 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: Datasets
description: 'Operations to create and manage datasets of entities.
A dataset is a named collection of entities — think of it as a watchlist or
portfolio. Connect a dataset to a job via `connected_dataset_ids` to activate
Company Watchlist. Datasets can be reused across multiple jobs and monitors.
'
externalDocs:
description: Learn about datasets and Company Watchlist
url: https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/company-search
paths:
/catchAll/datasets:
get:
tags:
- Datasets
summary: List datasets
description: 'Returns a paginated list of datasets belonging to the authenticated organization. Supports filtering by status and sorting by name, status, or creation date.
'
operationId: listDatasets
parameters:
- $ref: '#/components/parameters/Page'
- name: page_size
in: query
required: false
schema:
type: integer
default: 100
minimum: 1
maximum: 500
description: Number of datasets per page.
- name: search
in: query
required: false
schema:
type: string
description: Filter datasets by name (case-insensitive substring match).
example: Portfolio
- name: latest_status
in: query
required: false
schema:
$ref: '#/components/schemas/DatasetStatus'
description: 'Filter by dataset status.
'
- name: sort_by
in: query
required: false
schema:
$ref: '#/components/schemas/DatasetSortBy'
- name: sort_order
in: query
required: false
schema:
$ref: '#/components/schemas/SortOrder'
- $ref: '#/components/parameters/Ownership'
- $ref: '#/components/parameters/ProjectIdQuery'
responses:
'200':
$ref: '#/components/responses/DatasetListResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
post:
tags:
- Datasets
summary: Create dataset
description: 'Creates a new dataset from a list of existing entity IDs.
If any of the provided entity IDs do not exist or do not belong to
your organization, the request fails with `400`. All entity IDs must
be valid before the dataset is created.
To create a dataset and entities in one step, use the [`Create dataset from CSV`](https://www.newscatcherapi.com/docs/web-search-api/api-reference/datasets/create-dataset-from-csv)
endpoint instead.
'
operationId: createDataset
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetRequest'
example:
name: My Portfolio
description: Companies in our investment portfolio
entity_ids:
- 854198fa-f702-49db-a381-0427fa87f173
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
responses:
'200':
$ref: '#/components/responses/DatasetResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/datasets/upload:
post:
tags:
- Datasets
summary: Create dataset from CSV
description: "Creates a new dataset by uploading a CSV file. Each row in the CSV becomes an entity. The `name` and `domain`columns are required; all other columns are optional.\n\n**CSV format:**\n```csv\nname,description,domain,alternative_names,key_persons\nNewsCatcher,\"AI-powered news data provider\",newscatcherapi.com,\"NC;NewsCatcher API\",\"Artem Bugara;Maksym Sugonyaka\"\nOpenAI,\"Artificial intelligence research company\",openai.com,\"Open AI\",\"Sam Altman\"\n```\n\nUse semicolons (`;`) to separate multiple values in `alternative_names` and `key_persons`. Rows with empty `name` are skipped and reported in `validation_report`. \n\n**Note**: The response shape differs from the JSON dataset creation endpoint: it returns `dataset_id` (not `id`) and includes a `validation_report` with details on skipped rows.\n"
operationId: createDatasetFromCsv
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- name
properties:
file:
type: string
format: binary
description: The CSV file to upload.
name:
type: string
description: Name for the new dataset.
example: My Portfolio
description:
type: string
description: Optional description for the dataset.
example: Companies from Q1 2026 watchlist
responses:
'200':
$ref: '#/components/responses/CreateDatasetCsvResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/datasets/{dataset_id}:
get:
tags:
- Datasets
summary: Get dataset
description: Returns a single dataset by ID including entity count and current status.
operationId: getDataset
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
$ref: '#/components/responses/DatasetResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
patch:
tags:
- Datasets
summary: Update dataset
description: 'Updates the name or description of a dataset.
'
operationId: updateDataset
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDatasetRequest'
example:
name: My Portfolio (updated)
description: Updated Q1 2026 watchlist
responses:
'200':
$ref: '#/components/responses/DatasetResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
delete:
tags:
- Datasets
summary: Delete dataset
description: 'Permanently deletes a dataset. The entities within the dataset are
not deleted — only the dataset itself. This operation cannot be
undone.
'
operationId: deleteDataset
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'204':
description: Dataset deleted successfully. No response body.
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
/catchAll/datasets/{dataset_id}/entities:
post:
tags:
- Datasets
summary: Add entities to dataset
description: 'Adds one or more existing entities to a dataset. Returns the number of entities added.
'
operationId: addEntitiesToDataset
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetEntityIdsRequest'
example:
entity_ids:
- 854198fa-f702-49db-a381-0427fa87f173
responses:
'200':
$ref: '#/components/responses/ManageEntitiesResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
delete:
tags:
- Datasets
summary: Remove entities from dataset
description: 'Removes one or more entities from a dataset. The entities themselves are not deleted — they are only removed from this dataset. Returns the number of entities removed.
'
operationId: removeEntitiesFromDataset
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetEntityIdsRequest'
example:
entity_ids:
- 854198fa-f702-49db-a381-0427fa87f173
responses:
'200':
$ref: '#/components/responses/ManageEntitiesResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/datasets/{dataset_id}/entities/list:
post:
tags:
- Datasets
summary: List entities in dataset
description: 'Returns a paginated list of entities in a dataset. Supports filtering by status, entity type, and name search.
'
operationId: listEntitiesInDataset
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListDatasetEntitiesRequest'
example:
page: 1
page_size: 100
search: OpenAI
status: ready
entity_type: company
sort_by: created_at
sort_order: desc
responses:
'200':
$ref: '#/components/responses/DatasetEntityListResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/datasets/{dataset_id}/status:
get:
tags:
- Datasets
summary: Get dataset status history
description: 'Returns the full status change history for a dataset, ordered chronologically from oldest to newest.
'
operationId: getDatasetStatusHistory
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
$ref: '#/components/responses/DatasetStatusHistoryResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
/catchAll/datasets/{dataset_id}/upload:
post:
tags:
- Datasets
summary: Add companies to dataset via CSV
description: 'Appends new companies to an existing dataset by uploading a CSV file. Uses the same CSV format as the dataset creation endpoint.
The response omits `dataset_name` compared to the create-from-CSV endpoint since the dataset already exists.
'
operationId: uploadCSVToDataset
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: The CSV file to upload.
responses:
'200':
$ref: '#/components/responses/UploadCsvToDatasetResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
components:
responses:
DatasetEntityListResponse:
description: Paginated list of entities in a dataset.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetEntityListResponse'
NotFoundError:
description: Job/monitor not found or results not available
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
DatasetStatusHistoryResponse:
description: Dataset status change history.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetStatusHistoryResponse'
example:
dataset_id: ccabb755-afc2-4047-b84c-78d1f23d49b2
history:
- status: pending
additional_information: null
created_at: '2026-04-08T15:21:36.066271'
- status: enriching
additional_information: null
created_at: '2026-04-08T15:21:36.500000'
- status: ready
additional_information: null
created_at: '2026-04-08T15:21:55.000000'
ForbiddenError:
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
CreateDatasetCsvResponse:
description: Dataset created from CSV successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetCsvResponse'
example:
dataset_id: ccabb755-afc2-4047-b84c-78d1f23d49b2
dataset_name: My Portfolio
entities_created: 3
validation_report:
total_rows: 4
valid_rows: 3
skipped_count: 1
skipped_rows:
- row: 3
reason: 'missing required field: name'
DatasetListResponse:
description: Paginated list of datasets.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetListResponse'
ManageEntitiesResponse:
description: Entities added or removed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ManageEntitiesResponse'
example:
dataset_id: ccabb755-afc2-4047-b84c-78d1f23d49b2
affected_count: 1
UploadCsvToDatasetResponse:
description: Companies added to dataset from CSV successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadCsvToDatasetResponse'
example:
dataset_id: ccabb755-afc2-4047-b84c-78d1f23d49b2
entities_created: 3
validation_report:
total_rows: 3
valid_rows: 3
skipped_count: 0
skipped_rows: []
DatasetResponse:
description: Full dataset object with metadata and current status.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetResponse'
example:
id: ccabb755-afc2-4047-b84c-78d1f23d49b2
organization_id: e5d9e9b0-e415-4941-8ef0-916c5ee56207
name: My Portfolio
description: Companies in our investment portfolio
entity_count: 4
latest_status: ready
created_by_user_id: 870e258e-12ec-4a47-8656-e7a43b0265b3
created_at: '2026-04-08T15:21:36.026993'
updated_at: '2026-04-08T15:21:36.027001'
BadRequestError:
description: 'Bad request - invalid parameters or constraint violations.
Common causes: date ranges outside plan limits, invalid job state for continuation.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
date_validation:
summary: Date outside plan limit
value:
detail: start_date must be >= 2025-02-05, your plan limited to lookback 365 days.
invalid_continuation:
summary: Invalid job continuation
value:
detail: New limit must be greater than the previous limit for this job.
ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
schemas:
ManageEntitiesResponse:
type: object
required:
- dataset_id
- affected_count
properties:
dataset_id:
type: string
format: uuid
description: ID of the dataset that was modified.
example: ccabb755-afc2-4047-b84c-78d1f23d49b2
affected_count:
type: integer
description: Number of entities that were added or removed.
example: 1
DatasetStatus:
type: string
enum:
- pending
- enriching
- ready
- failed
description: 'Processing status of a dataset.
- `pending`: Dataset created, entities queued for enrichment.
- `enriching`: Entities are being enriched.
- `ready`: All entities enriched and indexed — ready for use in jobs.
- `failed`: One or more entity enrichments failed.
'
DatasetListResponse:
type: object
required:
- datasets
- total
- page
- page_size
properties:
datasets:
type: array
items:
$ref: '#/components/schemas/DatasetResponse'
description: Array of dataset objects for this page.
total:
type: integer
description: Total number of datasets matching the filter criteria.
example: 5
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of datasets per page.
example: 100
UpdateDatasetRequest:
type: object
description: 'Updates dataset name or description. At least one field should be
provided.
'
properties:
name:
type: string
description: Updated dataset name.
example: My Portfolio (updated)
description:
type: string
description: Updated description.
example: Updated description
DatasetSortBy:
type: string
enum:
- name
- created_at
- status
description: Fields available for sorting dataset list results.
default: created_at
ValidationErrorDetail:
type: object
properties:
loc:
type: array
items:
oneOf:
- type: string
- type: integer
description: Location of the validation error
msg:
type: string
description: Error message
type:
type: string
description: Error type
CreateDatasetCsvResponse:
type: object
required:
- dataset_id
- dataset_name
- entities_created
- validation_report
properties:
dataset_id:
type: string
format: uuid
description: Unique identifier of the created dataset.
example: ccabb755-afc2-4047-b84c-78d1f23d49b2
dataset_name:
type: string
description: Name of the created dataset.
example: My Portfolio
entities_created:
type: integer
description: Number of entities successfully created from the CSV.
example: 3
validation_report:
$ref: '#/components/schemas/ValidationReport'
DatasetResponse:
type: object
required:
- id
- organization_id
- name
properties:
id:
type: string
format: uuid
description: Unique identifier of the dataset.
example: ccabb755-afc2-4047-b84c-78d1f23d49b2
organization_id:
type: string
format: uuid
description: Organization that owns this dataset.
example: e5d9e9b0-e415-4941-8ef0-916c5ee56207
name:
type: string
description: Dataset name.
example: My Portfolio
description:
type:
- string
- 'null'
description: Optional description.
example: Companies in our investment portfolio
entity_count:
type: integer
description: Total number of entities in this dataset.
default: 0
example: 4
latest_status:
$ref: '#/components/schemas/DatasetStatus'
created_by_user_id:
type: string
format: uuid
description: ID of the user who created this dataset.
example: 870e258e-12ec-4a47-8656-e7a43b0265b3
created_at:
type: string
format: date-time
description: 'ISO 8601 timestamp of when the dataset was created. Returned without timezone offset (server-local time).
'
example: '2026-04-08T15:21:36.026993'
updated_at:
type: string
format: date-time
description: 'ISO 8601 timestamp of when the dataset was last updated. Returned without timezone offset (server-local time).
'
example: '2026-04-08T15:21:38.401148'
DatasetEntityIdsRequest:
type: object
required:
- entity_ids
properties:
entity_ids:
type: array
items:
type: string
format: uuid
description: List of entity IDs to add or remove.
minItems: 1
example:
- 854198fa-f702-49db-a381-0427fa87f173
ValidationErrorResponse:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/ValidationErrorDetail'
OwnershipFilter:
type: string
enum:
- all
- own
- shared
default: all
description: "Controls which resources are returned based on ownership.\n\n- `all`: Returns resources owned by the user and resources shared\n with them (default, backward compatible).\n- `own`: Returns only resources created by the authenticated user.\n- `shared`: Returns only resources shared with the user by others.\n"
DatasetEntityListResponse:
type: object
required:
- entities
- total
- page
- page_size
properties:
entities:
type: array
items:
$ref: '#/components/schemas/EntitySummary'
description: Array of entity summary objects for this page.
total:
type: integer
description: Total number of entities in the dataset.
example: 4
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of entities per page.
example: 100
Error:
type: object
properties:
detail:
type: string
description: Error message.
example: Invalid API key
DatasetStatusHistoryResponse:
type: object
required:
- dataset_id
- history
properties:
dataset_id:
type: string
format: uuid
description: ID of the dataset.
example: ccabb755-afc2-4047-b84c-78d1f23d49b2
history:
type: array
items:
$ref: '#/components/schemas/DatasetStatusEntry'
description: Status change entries, ordered oldest to newest.
DatasetStatusEntry:
type: object
required:
- status
description: A single status change event in a dataset's history.
properties:
status:
$ref: '#/components/schemas/DatasetStatus'
additional_information:
type:
- object
- 'null'
description: Additional context about the status change, if available.
example: null
created_at:
type: string
format: date-time
description: 'ISO 8601 timestamp of when this status was set. Returned without timezone offset (server-local time).
'
example: '2026-04-08T15:21:36.066271'
EntitySummary:
type: object
required:
- id
- name
- entity_type
- status
description: 'Abbreviated entity object returned when listing entities within a
dataset. Uses a flat `attributes` key rather than the nested
`additional_attributes.company_attributes` structure used in
standalone entity endpoints.
'
properties:
id:
type: string
format: uuid
description: Unique identifier of the entity.
example: 854198fa-f702-49db-a381-0427fa87f173
name:
type: string
description: Entity name.
example: NewsCatcher
entity_type:
$ref: '#/components/schemas/EntityType'
status:
$ref: '#/components/schemas/EntityStatus'
description:
type:
- string
- 'null'
description: Free-text description.
example: AI-powered news data provider
attributes:
$ref: '#/components/schemas/CompanyAttributes'
ValidationReport:
type: object
required:
- total_rows
- valid_rows
- skipped_count
- skipped_rows
description: Summary of CSV processing results.
properties:
total_rows:
type: integer
description: 'Total number of data rows in the uploaded CSV (excluding the
header row).
'
example: 4
valid_rows:
type: integer
description: Number of rows successfully processed into entities.
example: 3
skipped_count:
type: integer
description: Number of rows skipped due to validation errors.
example: 1
skipped_rows:
type: array
items:
$ref: '#/components/schemas/SkippedRow'
description: Details for each skipped row.
EntitySortBy:
type: string
enum:
- created_at
- name
- status
description: Fields available for sorting entity list results.
default: created_at
EntityType:
type: string
enum:
- company
- person
description: 'The type of entity.
- `company`: A company or organization (default).
- `person`: An individual person.
'
default: company
CreateDatasetRequest:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
description: Name for the dataset.
example: My Portfolio
description:
type: string
description: Optional description.
example: Companies in our investment portfolio
entity_ids:
type: array
items:
type: string
format: uuid
description: 'IDs of existing entities to include in the dataset. All IDs must belong to the authenticated organization. If any ID is invalid or not found, the request fails with `400`.
'
example:
- 854198fa-f702-49db-a381-0427fa87f173
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
SkippedRow:
type: object
required:
- row
- reason
description: Details about a CSV row that was skipped during processing.
properties:
row:
type: integer
description: '1-based row number in the CSV file (including the header row).
A value of `3` means the third line of the file (second data row).
'
example: 3
reason:
type: string
description: Human-readable explanation of why the row was skipped.
example: 'missing required field: name'
ListDatasetEntitiesRequest:
type: object
properties:
page:
type: integer
minimum: 1
default: 1
description: The page number to retrieve.
example: 1
page_size:
type: integer
minimum: 1
maximum: 500
default: 100
description: The number of entities per page.
example: 100
search:
type: string
description: Filters entities by name using a case-insensitive substring match.
example: OpenAI
status:
$ref: '#/components/schemas/EntityStatus'
entity_type:
$ref: '#/components/schemas/EntityType'
sort_by:
$ref: '#/components/schemas/EntitySortBy'
sort_order:
$ref: '#/components/schemas/SortOrder'
UploadCsvToDatasetResponse:
type: object
required:
- dataset_id
- entities_created
- validation_report
properties:
dataset_id:
type: string
format: uuid
description: ID of the dataset that was updated.
example: ccabb755-afc2-4047-b84c-78d1f23d49b2
entities_created:
type: integer
description: Number of new entities created from the CSV.
example: 3
validation_report:
$ref: '#/components/schemas/ValidationReport'
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 asso
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newscatcher/refs/heads/main/openapi/newscatcher-datasets-api-openapi.yml