HTTP headers

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:

​

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

​

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:

​

Correlation ID header

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

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

​

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.

​

Related resources

• Request tracing with correlation IDs
• Error handling
• Authentication