Operations to create, organize, and manage projects. A project is a named container for jobs, monitors, and datasets. Group related resources by use case, team, or client, and share them with teammates. Resources can be assigned at creation time or post-hoc.
openapi: 3.0.3
info:
title: Local News AggregationCount Projects 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: Projects
description: 'Operations to create, organize, and manage projects.
A project is a named container for jobs, monitors, and datasets. Group
related resources by use case, team, or client, and share them with
teammates. Resources can be assigned at creation time or post-hoc.
'
externalDocs:
description: Learn about projects and resource organization
url: https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/projects
paths:
/catchAll/projects:
post:
tags:
- Projects
summary: Create project
description: Creates a new project.
operationId: createProject
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProjectRequestDto'
example:
name: AI M&A Tracking
description: Tracks AI-related M&A activity for our investment team.
responses:
'201':
$ref: '#/components/responses/CreateProjectResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/ValidationError'
get:
tags:
- Projects
summary: List projects
description: Returns all projects visible to the authenticated user.
operationId: listProjects
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
- name: search
in: query
required: false
schema:
type: string
description: Filter by project name (case-insensitive substring match).
example: M&A
- $ref: '#/components/parameters/Ownership'
responses:
'200':
$ref: '#/components/responses/ListProjectsResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/projects/{project_id}:
get:
tags:
- Projects
summary: Get project
description: Returns a single project by ID.
operationId: getProject
parameters:
- $ref: '#/components/parameters/ProjectId'
responses:
'200':
$ref: '#/components/responses/ProjectResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
patch:
tags:
- Projects
summary: Update project
description: Updates the name or description of an existing project.
operationId: updateProject
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProjectRequestDto'
example:
name: AI M&A Tracking (Q2 2026)
responses:
'200':
$ref: '#/components/responses/UpdateProjectResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
delete:
tags:
- Projects
summary: Delete project
description: "Deletes a project. By default, assigned resources are unassigned but not deleted. \n"
operationId: deleteProject
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/DeleteResources'
responses:
'204':
description: Project deleted successfully. No response body.
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
/catchAll/projects/{project_id}/overview:
get:
tags:
- Projects
summary: Get project overview
description: 'Returns resource counts for a project, grouped by type and status.
For `jobs` and `monitors`, counts are broken down by status (for example, `completed`, `failed`). For `datasets` and `monitor_groups`, only a `total` count is returned.
'
operationId: getProjectOverview
parameters:
- $ref: '#/components/parameters/ProjectId'
responses:
'200':
$ref: '#/components/responses/ProjectOverviewResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
/catchAll/projects/{project_id}/resources:
post:
tags:
- Projects
summary: Add resources to project
description: 'Assigns one or more existing resources to a project in a single request.
'
operationId: addResourceToProject
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddResourceRequestDto'
example:
resources:
- resource_type: job
resource_id: 48421e16-1f50-4048-b62c-d3bc0789d30d
responses:
'200':
$ref: '#/components/responses/AddResourceResponse'
'201':
$ref: '#/components/responses/AddResourceResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
get:
tags:
- Projects
summary: List project resources
description: Returns all resources assigned to a project, with optional filtering by type.
operationId: listProjectResources
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: resource_type
in: query
required: false
schema:
$ref: '#/components/schemas/ProjectResourceType'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
$ref: '#/components/responses/ListProjectResourcesResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/projects/{project_id}/resources/{resource_type}/{resource_id}:
delete:
tags:
- Projects
summary: Remove resource from project
description: 'Removes a resource from a project. The resource itself is not
deleted — it becomes unassigned and continues to exist.
'
operationId: removeResourceFromProject
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: resource_type
in: path
required: true
schema:
$ref: '#/components/schemas/ProjectResourceType'
- name: resource_id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the resource to remove.
example: 48421e16-1f50-4048-b62c-d3bc0789d30d
responses:
'200':
$ref: '#/components/responses/RemoveResourceResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
components:
responses:
NotFoundError:
description: Job/monitor not found or results not available
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ProjectOverviewResponse:
description: Resource counts for the project, grouped by type and status.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectOverviewResponseDto'
example:
project_id: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
overview:
jobs: {}
monitors: {}
datasets:
total: 2
monitor_groups:
total: 0
CreateProjectResponse:
description: Project created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProjectResponseDto'
example:
success: true
message: Project created successfully.
project_id: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
name: AI M&A Tracking
ForbiddenError:
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RemoveResourceResponse:
description: Resource removed from the project.
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveResourceResponseDto'
example:
success: true
message: Resource removed from project.
ListProjectResourcesResponse:
description: Paginated list of resources assigned to the project.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectResourceListResponseDto'
example:
total: 1
page: 1
page_size: 100
total_pages: 1
resources:
- resource_type: job
resource_id: 48421e16-1f50-4048-b62c-d3bc0789d30d
name: Series B fintech funding rounds
created_at: '2026-05-20T14:31:37Z'
metadata: {}
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'
UpdateProjectResponse:
description: Project updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProjectResponseDto'
example:
success: true
message: Project updated successfully.
project_id: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
ProjectResponse:
description: Project details.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectResponseDto'
example:
success: true
message: OK
project_id: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
name: AI M&A Tracking
description: Tracks AI-related M&A activity for our investment team.
resources_count: 4
created_at: '2026-05-20T14:31:35Z'
updated_at: '2026-05-20T14:31:35Z'
ListProjectsResponse:
description: Paginated list of projects.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectListResponseDto'
example:
total: 2
page: 1
page_size: 100
total_pages: 1
projects:
- project_id: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
name: AI M&A Tracking
description: Tracks AI-related M&A activity.
resources_count: 4
created_at: '2026-05-20T14:31:35Z'
updated_at: '2026-05-20T14:31:35Z'
AddResourceResponse:
description: 'One or more resources added to the project (`201`), or all were already present (`200`).
'
content:
application/json:
schema:
$ref: '#/components/schemas/AddResourceResponseDto'
example:
success: true
message: Resources added to project.
results:
- resource_type: job
resource_id: 48421e16-1f50-4048-b62c-d3bc0789d30d
success: true
message: Resource added to project.
already_exists: false
schemas:
ProjectOverviewResponseDto:
type: object
required:
- project_id
- overview
properties:
project_id:
type: string
format: uuid
description: Project identifier.
example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
overview:
type: object
description: Resource counts grouped by type.
required:
- jobs
- monitors
- datasets
- monitor_groups
properties:
jobs:
$ref: '#/components/schemas/ProjectOverviewCountsDto'
monitors:
$ref: '#/components/schemas/ProjectOverviewCountsDto'
datasets:
$ref: '#/components/schemas/ProjectOverviewCountsDto'
monitor_groups:
$ref: '#/components/schemas/ProjectOverviewCountsDto'
RemoveResourceResponseDto:
type: object
required:
- success
- message
properties:
success:
type: boolean
description: True if the operation succeeded; false otherwise.
example: true
message:
type: string
description: Human-readable result message.
example: Resource removed from project.
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
ProjectResponseDto:
type: object
required:
- success
- message
- project_id
- name
properties:
success:
type: boolean
description: True if the operation succeeded; false otherwise.
example: true
message:
type: string
description: Human-readable result message.
example: OK
project_id:
type: string
format: uuid
description: Project identifier.
example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
name:
type: string
description: Project name.
example: AI M&A Tracking
description:
type:
- string
- 'null'
description: Project description.
example: Tracks AI-related M&A activity for our investment team.
resources_count:
type: integer
description: Number of resources assigned to this project.
example: 4
default: 0
created_at:
type: string
format: date-time
description: Project creation timestamp.
example: '2026-05-20T14:31:35Z'
updated_at:
type: string
format: date-time
description: Timestamp of the last update.
example: '2026-05-20T14:31:35Z'
ResourceResultDto:
type: object
required:
- resource_type
- resource_id
- success
- message
properties:
resource_type:
type: string
description: Type of the resource.
example: job
resource_id:
type: string
format: uuid
description: Resource identifier.
example: 48421e16-1f50-4048-b62c-d3bc0789d30d
success:
type: boolean
description: True if this resource was processed successfully.
example: true
message:
type: string
description: Per-resource result message.
example: Resource added to project.
already_exists:
type: boolean
description: True if the resource is already assigned to this project.
default: false
example: false
ProjectResourceType:
type: string
enum:
- job
- monitor
- dataset
- monitor_group
description: 'Resource type for project association.
'
ProjectSummaryDto:
type: object
description: Abbreviated project object returned in list responses.
required:
- project_id
- name
properties:
project_id:
type: string
format: uuid
description: Project identifier.
example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
name:
type: string
description: Project name.
example: AI M&A Tracking
description:
type:
- string
- 'null'
description: Project description.
example: Tracks AI-related M&A activity for our investment team.
resources_count:
type: integer
description: Number of resources assigned to this project.
example: 4
default: 0
created_at:
type: string
format: date-time
description: Project creation timestamp.
example: '2026-05-20T14:31:35Z'
updated_at:
type: string
format: date-time
description: Timestamp of the last update.
example: '2026-05-20T14:31:35Z'
ResourceItemDto:
type: object
required:
- resource_type
- resource_id
properties:
resource_type:
$ref: '#/components/schemas/ProjectResourceType'
resource_id:
type: string
format: uuid
description: ID of the resource to add.
example: 48421e16-1f50-4048-b62c-d3bc0789d30d
ValidationErrorResponse:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/ValidationErrorDetail'
UpdateProjectRequestDto:
type: object
description: Updates one or more fields of an existing project. At least one field must be provided.
properties:
name:
type: string
minLength: 1
description: New name for the project.
example: AI M&A Tracking (Q2)
description:
type: string
description: New description for the project.
example: Updated scope to include private equity.
ProjectResourceDto:
type: object
description: A resource assigned to a project.
required:
- resource_type
- resource_id
properties:
resource_type:
$ref: '#/components/schemas/ProjectResourceType'
resource_id:
type: string
format: uuid
description: Resource identifier.
example: 48421e16-1f50-4048-b62c-d3bc0789d30d
name:
type: string
description: 'Resource display name. For jobs, this is the original query
string. For monitors and datasets, this is the resource name.
'
example: Series B fintech funding rounds
created_at:
type: string
format: date-time
description: Resource creation timestamp.
example: '2026-05-20T14:31:37Z'
metadata:
type: object
description: Additional resource-specific metadata.
additionalProperties: true
example: {}
ProjectResourceListResponseDto:
type: object
required:
- total
- page
- page_size
- total_pages
- resources
properties:
total:
type: integer
description: Total number of resources assigned to the project.
example: 1
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of resources per page.
example: 100
total_pages:
type: integer
description: Total number of pages.
example: 1
resources:
type: array
items:
$ref: '#/components/schemas/ProjectResourceDto'
description: Resources on this page.
Error:
type: object
properties:
detail:
type: string
description: Error message.
example: Invalid API key
CreateProjectRequestDto:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
description: Name for the project.
example: AI M&A Tracking
description:
type: string
description: Optional description.
example: Tracks AI-related M&A activity for our investment team.
ProjectListResponseDto:
type: object
required:
- total
- page
- page_size
- total_pages
- projects
properties:
total:
type: integer
description: Total number of projects matching the filter criteria.
example: 2
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of projects per page.
example: 100
total_pages:
type: integer
description: Total number of pages.
example: 1
projects:
type: array
items:
$ref: '#/components/schemas/ProjectSummaryDto'
description: Projects on this page.
UpdateProjectResponseDto:
type: object
required:
- success
- message
- project_id
properties:
success:
type: boolean
description: True if the operation succeeded; false otherwise.
example: true
message:
type: string
description: Human-readable result message.
example: Project updated successfully.
project_id:
type: string
format: uuid
description: Project identifier.
example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
ProjectOverviewCountsDto:
type: object
description: 'Status breakdown for a single resource type.
'
additionalProperties: true
AddResourceRequestDto:
type: object
required:
- resources
properties:
resources:
type: array
minItems: 1
description: Resources to assign to the project.
items:
$ref: '#/components/schemas/ResourceItemDto'
CreateProjectResponseDto:
type: object
required:
- success
- message
- project_id
- name
properties:
success:
type: boolean
description: True if the operation succeeded; false otherwise.
example: true
message:
type: string
description: Human-readable result message.
example: Project created successfully.
project_id:
type: string
format: uuid
description: Project identifier.
example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
name:
type: string
description: Name of the created project.
example: AI M&A Tracking
AddResourceResponseDto:
type: object
required:
- success
- message
- results
properties:
success:
type: boolean
description: True if the overall operation succeeded.
example: true
message:
type: string
description: Top-level result message.
example: Resources added to project.
results:
type: array
description: Per-resource outcome, one entry per submitted resource.
items:
$ref: '#/components/schemas/ResourceResultDto'
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"
parameters:
Page:
name: page
in: query
required: false
schema:
type: integer
default: 1
minimum: 1
description: 'Page number to retrieve.
'
ProjectId:
name: project_id
in: path
required: true
description: Unique project identifier.
schema:
type: string
format: uuid
example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
Ownership:
name: ownership
in: query
required: false
schema:
$ref: '#/components/schemas/OwnershipFilter'
DeleteResources:
name: delete_resources
in: query
required: false
description: 'If true, permanently deletes all resources (jobs, monitors, datasets) assigned to the project. If false, the project is deleted and its resources are unassigned but not deleted.
'
schema:
type: boolean
default: false
PageSize:
name: page_size
in: query
required: false
schema:
type: integer
default: 100
minimum: 1
maximum: 1000
description: 'Number of records per page.
'
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