This guide explains the HTTP headers used in the NewsCatcher APIs, including required request headers, useful response headers, and best practices for working with them.

​
Request headers

These are the headers you should include when making requests:

HeaderRequiredDescriptionExample
x-api-tokenYesYour API key for authenticationx-api-token: abcd1234...
Content-TypeYes*Content type of the request body (*required for POST requests)Content-Type: application/json
AcceptNoPreferred response formatAccept: application/json

​
Authentication header

The x-api-token header is required for all API requests and contains your API key:

POST /api/search HTTP/1.1
Host: v3-api.newscatcherapi.com
x-api-token: YOUR_API_KEY

Never share your API key publicly or commit it to source control. Consider using environment variables or a secure secrets manager to store it.

​
Content-Type header

For POST requests, always set the Content-Type header to application/json:

POST /api/search HTTP/1.1
Host: v3-api.newscatcherapi.com
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

{
  "q": "bitcoin",
  "from_": "30d"
}

​
Response headers

These are the headers returned in API responses that provide useful information:

HeaderDescriptionExample
DateWhen the response was generatedDate: Sat, 22 Mar 2025 13:49:07 GMT
Content-TypeFormat of the response bodyContent-Type: application/json
Transfer-EncodingHow the response is encoded for transferTransfer-Encoding: chunked
ConnectionConnection status between client and serverConnection: keep-alive
x-process-timeTime taken to process the request (in seconds)x-process-time: 0.7334954738616943
correlation-idUnique identifier for tracing the request through our systemcorrelation-id: a702576c-2007-4b23-9ba4-cad305c84275
cf-cache-statusCloudflare cache statuscf-cache-status: DYNAMIC
ServerServer software handling the requestServer: cloudflare
CF-RAYCloudflare ray ID for request tracingCF-RAY: 924626834b0fbfb4-WAW
Content-EncodingCompression method used for the response bodyContent-Encoding: br

​
Correlation ID header

The correlation-id header contains a unique identifier for your request:

correlation-id: a702576c-2007-4b23-9ba4-cad305c84275

Always include this ID when contacting support about an issue with an API request. It helps us quickly locate your specific request in our logs.

​
Process time header

The x-process-time header shows how long it took our system to process your request (in seconds):

x-process-time: 0.7334954738616943

This can be useful for performance monitoring and optimization. If you consistently see high process times, consider optimizing your queries or implementing caching strategies.

​
Code examples

Here are the examples of how to work with headers in your requests for differnt programming languages:

curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"q": "bitcoin", "from_": "30d"}' \
  -i

# The -i flag displays response headers in the output
# Look for the correlation-id in the response headers

​
Best practices

  1. Always use the correct authentication header: Use x-api-token instead of x-api-key for authentication.

  2. Always log correlation IDs: Store correlation IDs alongside your application logs for easier troubleshooting.

  3. Monitor process times: Keep track of x-process-time values to identify performance trends or issues.

  4. Handle headers consistently: Implement consistent header handling in your error handling and logging code.

  5. Be aware of case sensitivity: While HTTP headers are case-insensitive in the protocol, many libraries preserve the original casing when accessing them.

  6. Add proper Content-Type headers: Always include the Content-Type: application/json header for POST requests.