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:
An API key (obtain one through
Book a demo page)
Basic understanding of REST APIs
Your preferred programming language and HTTP client
Basic knowledge of JSON data format
Steps
Set up your environment
Install the CatchAll client library for your programming language: curl
Python
TypeScript
Java (Gradle)
Java (Maven)
# cURL is typically included in your system # To check, open the terminal and type the following: curl --version
Create a job
Submit a natural language query to create a new processing job: curl
JSON
Python
TypeScript
Java
curl -X POST https://catchall.newscatcherapi.com/catchAll/submit \ -H "x-api-key: YOUR_API_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{ "query": "Tech company earnings this quarter", "context": "Focus on revenue and profit margins", "schema": "Company [NAME] earned [REVENUE] in [QUARTER]" }'
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: { "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 the response
The API returns structured records according to LLM-generated enrichment schema: { "job_id" : "af7a26d6-cf0b-458c-a6ed-4b6318c74da3" , "query" : "Tech company earnings this quarter" , "context" : "Focus on revenue and profit margins" , "validators" : [ "is_current_quarter" , "contains_financial_data" , "is_about_tech_company_earnings" ], "status" : "job_completed" , "duration" : "12m" , "candidate_records" : 59150 , "valid_records" : 156 , "date_range" : { "start_date" : "2025-11-05T13:06:10Z" , "end_date" : "2025-11-05T14:06:10Z" }, "all_records" : [ { "record_id" : "5262823697790152939" , "record_title" : "Oracle Q1 2026 Earnings Exceed Expectations" , "enrichment" : { "company_name" : "Oracle" , "quarter_identifier" : "Q1 2026" , "revenue" : "$14.9 billion" , "revenue_change" : "up 12%" , "profit_margin" : "42% non-GAAP operating margin" , "eps" : "$1.47" , "schema_based_summary" : "Company Oracle earned $14.9 billion in Q1 2026" }, "citations" : [ { "title" : "Oracle Reports Strong Q1 2026 Results" , "link" : "https://example.com/article" , "published_date" : "2025-09-26 08:54:20" } ] } ] } 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.
