Skip to main content
This guide helps you make your first API call to transform natural language questions into structured, validated records with source citations.

​
Before you start

Before you begin, make sure you meet these prerequisites:
  • CatchAll API key (obtain from platform.newscatcherapi.com)
  • Basic understanding of REST APIs
  • Your preferred programming language and HTTP client
  • Basic knowledge of JSON data format

​
Steps

1

Set up environment

Install the CatchAll client library for your programming language:
# cURL is typically included in your system
# To check, open the terminal and type the following:
curl --version
2

Create job

Submit a natural language query to create a new processing job:
curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI company acquisitions",
    "context": "Focus on deal size and acquiring company details",
    "start_date": "2025-12-03T19:00:40Z",
    "end_date": "2025-12-08T19:00:40Z",
    "limit": 10
  }'
Replace YOUR_API_KEY_HERE with your actual API key. Only query is required - all other parameters are optional. For details, see POST /catchAll/submit.
Use limit=10 for faster testing, then continue processing more with POST /catchAll/continue without restarting.
You receive a response with a job ID:
{
  "job_id": "af7a26d6-cf0b-458c-a6ed-4b6318c74da3"
}
Use this job_id to check the status and retrieve results.
3

Check job status

Wait 1-2 minutes, then check the processing status. Poll this endpoint every 30-60 seconds until the status is completed:
curl -X GET https://catchall.newscatcherapi.com/catchAll/status/af7a26d6-cf0b-458c-a6ed-4b6318c74da3 \
  -H "x-api-key: YOUR_API_KEY_HERE"
The response shows the current processing stage:Jobs advance through stages sequentially from submitted (order 1) to either completed (order 6) or failed (order 7). Processing typically takes 10-15 minutes.
4

Retrieve results

Results become available during the enriching stage. The progress_validated field shows how many candidate clusters have been validated. You can retrieve partial results as batches are completed, or wait until status is completed and retrieve all records:
curl -X GET https://catchall.newscatcherapi.com/catchAll/pull/af7a26d6-cf0b-458c-a6ed-4b6318c74da3 \
  -H "x-api-key: YOUR_API_KEY_HERE"
5

Review response

The API returns structured records according to LLM-generated enrichment schema:
Field names in the enrichment object are LLM-generated and vary between jobs, even with identical queries. The example shows one possible structure for acquisition queries. Use POST /catchAll/initialize to preview suggested fields, or define custom enrichments for consistent schemas.

​
What’s next

Now that you’ve made your first calls to the CatchAll API:
  1. Learn how to automate recurring queries with Monitors.
  2. Read Dynamic schemas to understand variable response structures in your code.
  3. Explore the API Reference for detailed endpoint documentation.
Need help? Contact our support team at support@newscatcherapi.com