CatchAll API quickstart guide

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

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

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"
  }'

Replace YOUR_API_KEY_HERE with your actual API key.

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.

Check job status

Wait 1-2 minutes, then check the processing status. Poll this endpoint every 30-60 seconds until the status is job_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:

Show Example response

{
  "job_id": "af7a26d6-cf0b-458c-a6ed-4b6318c74da3",
  "status": "fetching",
  "steps": [
    {
      "status": "submitted",
      "order": 1,
      "completed": true
    },
    {
      "status": "analyzing",
      "order": 2,
      "completed": true
    },
    {
      "status": "fetching",
      "order": 3,
      "completed": false
    },
    {
      "status": "clustering",
      "order": 4,
      "completed": false
    },
    {
      "status": "enriching",
      "order": 5,
      "completed": false
    },
    {
      "status": "completed",
      "order": 6,
      "completed": false
    },
    {
      "status": "failed",
      "order": 7,
      "completed": false
    }
  ]
}

Jobs advance through stages sequentially from submitted (order 1) to either completed (order 6) or failed (order 7). Processing typically takes 10-15 minutes.

Retrieve results

Once the status is job_completed, retrieve the structured records:

curl -X GET https://catchall.newscatcherapi.com/catchAll/pull/af7a26d6-cf0b-458c-a6ed-4b6318c74da3 \
  -H "x-api-key: YOUR_API_KEY_HERE"

Review response

The API returns structured records according to LLM-generated enrichment schema:

Show Example response

JSON

{
  "job_id": "89e48e60-7131-411b-b5cd-0d4c85e1927b",
  "query": "AI company acquisitions",
  "context": "Focus on deal size and acquiring company details",
  "validators": [
    "has_deal_details",
    "involves_actual_acquisition",
    "is_about_ai_company_acquisition"
  ],
  "status": "job_completed",
  "duration": "23m",
  "candidate_records": 30686,
  "valid_records": 230,
  "date_range": {
    "start_date": "2025-12-03T19:00:40Z",
    "end_date": "2025-12-08T19:00:40Z"
  },
  "all_records": [
    {
      "record_id": "5685210581375815445",
      "record_title": "Marvell to Acquire Celestial AI for $3.25 Billion",
      "enrichment": {
        "confidence": "high",
        "deal_date": "2025-12-02",
        "acquiring_company": "Marvell Technology",
        "deal_value": "$3.25 billion",
        "strategic_rationale": "To strengthen Marvell's portfolio, gain access to Celestial AI's photonics technology, accelerate its roadmap in the interconnect space, strengthen Marvell's position as a leader in the fastest-growing opportunities in the AI data center infrastructure market, and develop a 'silicon photonics turnkey solution' for AI servers.",
        "acquiring_company_details": "American semiconductor design company, a fabless semiconductor company that designs, develops, and sells integrated circuits (ICs), and supplies semiconductor chips and hardware products to the data center, telecommunications company (carrier) 5G infrastructure, corporate networking, and storage markets. Helps big-tech clients like Amazon, Google, Microsoft, and Meta Platforms design their own AI chips. Market capitalization was $78.59 billion.",
        "ai_technology_focus": "photonics, silicon photonics, Photonic Fabric technology, optical interconnect, co-packaged optical (CPO) connections",
        "acquisition_status": "announced, pending regulatory approval",
        "acquired_company": "Celestial AI"
      },
      "citations": [
        {
          "title": "'빛' 기술에 꽂힌 구글·AWS…AI 통신 속도 획기적으로 높인다",
          "link": "https://n.news.naver.com/mnews/article/015/0005221540",
          "published_date": "2025-12-08 15:52:17"
        },
        {
          "title": "Miliardový obchod v AI čipech. Marvell jedná o koupi rychle rostoucího start-upu",
          "link": "https://www.zive.cz/clanky/miliardovy-obchod-v-ai-cipech-marvell-jedna-o-koupi-rychle-rostouciho-start-upu/sc-3-a-238455/default.aspx",
          "published_date": "2025-12-06 16:45:00"
        },
        {
          "title": "Marvell to buy chip startup Celestial AI for $3.25 billion",
          "link": "https://www.communicationstoday.co.in/marvell-to-buy-chip-startup-celestial-ai-for-3-25-billion",
          "published_date": "2025-12-04 03:01:56"
        }
      ]
    }
  ]
}

The field names in the enrichment object are LLM-generated and may vary even for the same inputs. The example above shows one possible structure for earnings queries.

What’s next

Now that you’ve made your first calls to the CatchAll API:

Learn how to automate recurring queries with Monitors.
Read Dynamic schemas to understand variable response structures in your code.
Explore the API Reference for detailed endpoint documentation.

Need help? Contact our support team at support@newscatcherapi.com

Overview

How to

Endpoints

Libraries

Integrations

CatchAll API quickstart guide

Before you start

Steps

What’s next

Overview

How to

Endpoints

Libraries

Integrations

​Before you start

​Steps

​What’s next

Before you start

Steps

What’s next