> ## Documentation Index > Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create dataset > Creates a new dataset from a list of existing entity IDs. The optional `description` field here describes the dataset itself — it is separate from the entity-level `description` used for matching. Entities must be created before adding them to a dataset. Each entity requires a `name` plus at least one of: a `description` or a `domain`. Use [Create entity](https://www.newscatcherapi.com/docs/web-search-api/api-reference/entities/create-entity) or [Create entities batch](https://www.newscatcherapi.com/docs/web-search-api/api-reference/entities/create-entities-batch) to create entities first. 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. ## OpenAPI ````yaml catch-all-api post /catchAll/datasets openapi: 3.1.0 info: title: NewsCatcher CatchAll API version: 1.10.0 description: > CatchAll is a web search API that generates unique datasets that don't exist anywhere else on the web. Built on NewsCatcher's proprietary real-world event index, it delivers state-of-the-art recall—finding all relevant events, not just top results. ### Authentication All endpoints except /health and /version require `x-api-key` header. If the key is invalid or missing, the API returns the `403 Forbidden` error. ### Job workflow 1. (Optional) Get suggestions via /catchAll/initialize 2. Submit a query via /catchAll/submit with optional date ranges and custom validators/enrichments 3. Poll /catchAll/status/{job_id} until completed (10-15 minutes) 4. Retrieve results via /catchAll/pull/{job_id} ### Event monitor workflow 1. Create successful job via /catchAll/submit 2. Create event monitor via /catchAll/monitors/create with schedule 3. Retrieve aggregated results via /catchAll/monitors/pull/{monitor_id} ### Webhook workflow 1. Create a webhook via `POST /catchAll/webhooks` 2. Attach it to a job or event monitor via `POST /catchAll/webhooks/{webhook_id}/resources`, or pass `webhook_ids` at job or event monitor creation time 3. Receive HTTP notifications at the configured URL when each job completes ### Company search workflow 1. Create a dataset via `POST /catchAll/datasets/` or `POST /catchAll/datasets/upload` 2. Wait for the dataset `latest_status` to reach `ready` 3. Submit a job with `connected_dataset_ids` pointing to your dataset 4. Retrieve results — each record includes a `connected_entities` array with relevance scores per matched company ### Important notes **Dynamic schemas**: Response schemas are generated dynamically by LLMs. Field names in the `enrichment` object may vary and are not deterministic across jobs unless explicitly specified. contact: name: NewsCatcher url: https://newscatcherapi.com email: support@newscatcherapi.com servers: - url: https://catchall.newscatcherapi.com description: Production server security: - ApiKeyAuth: [] tags: - name: Jobs description: Operations to create, monitor, and retrieve job results. externalDocs: description: Learn about job lifecycle and status tracking url: >- https://www.newscatcherapi.com/docs/web-search-api/get-started/quickstart - name: Event Monitors description: Operations to create, operate and retrieve event monitor results. externalDocs: description: >- Automate recurring queries with scheduled jobs and webhook notifications. url: >- https://www.newscatcherapi.com/docs/web-search-api/concepts/event-monitors - name: Webhooks description: > Operations to create and manage reusable webhook endpoints. A webhook is a named HTTP endpoint that receives a POST notification when a job or event monitor completes. Create webhooks once at the organization level and attach them to any number of jobs or event monitors via `webhook_ids`. Supports Slack, Microsoft Teams, and generic HTTP targets with configurable delivery modes, authentication, and headers. externalDocs: description: Learn about centralized webhooks and notification setup url: >- https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/webhooks - name: Entities description: > Operations to create, update, and delete company entities. Entities are the building blocks of Company Monitors. 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 Monitors and entities url: >- https://www.newscatcherapi.com/docs/web-search-api/concepts/company-monitors - 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 Monitors. Datasets can be reused across multiple jobs and event monitors. externalDocs: description: Learn about datasets and Company Monitors url: >- https://www.newscatcherapi.com/docs/web-search-api/concepts/company-monitors - name: Projects description: > Operations to create, organize, and manage projects. A project is a named container for jobs, event 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/concepts/projects - name: Meta description: Operations to check API health and version. externalDocs: description: Find out more about NewsCatcher CatchAll API url: https://www.newscatcherapi.com/docs/web-search-api/get-started/introduction paths: /catchAll/datasets: post: tags: - Datasets summary: Create dataset description: > Creates a new dataset from a list of existing entity IDs. The optional `description` field here describes the dataset itself — it is separate from the entity-level `description` used for matching. Entities must be created before adding them to a dataset. Each entity requires a `name` plus at least one of: a `description` or a `domain`. Use [Create entity](https://www.newscatcherapi.com/docs/web-search-api/api-reference/entities/create-entity) or [Create entities batch](https://www.newscatcherapi.com/docs/web-search-api/api-reference/entities/create-entities-batch) to create entities first. 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' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '422': $ref: '#/components/responses/ValidationError' components: schemas: 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 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 entity_status_breakdown: type: object additionalProperties: type: integer description: > Count of entities grouped by processing status. Keys are status values (`ready`, `pending`, `enriching`, `failed`); values are entity counts. example: ready: 4 health_score: type: number description: > Overall health score of the dataset, from 0 to 100. Reflects how many entities have sufficient identifying information for reliable matching. example: 100 health_breakdown: type: object additionalProperties: type: number description: | Health scores broken down by entity type. Keys are entity types (e.g. `company`); values are scores from 0 to 100. example: company: 100 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' Error: type: object properties: detail: type: string description: Error message. example: Invalid API key ValidationErrorResponse: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationErrorDetail' 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. 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 responses: 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 entity_status_breakdown: ready: 4 health_score: 100 health_breakdown: company: 100 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. UnauthorizedError: description: > The caller could not be identified: the `x-api-key` header is missing, the key is unknown or disabled, or the key belongs to a different organization than the one requested. Once identity is established, an access failure returns `403` instead. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: X-API-Key header is required for this endpoint ForbiddenError: description: > Authenticated, but not allowed to perform this request — for example the user is not a member of the requested organization, has no active API key in it, or the resource belongs to another organization. A missing, unknown, or disabled API key returns `401`, not `403`. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.