API Documentation

Everything you need to use Hindsight Data API.

Authentication

All API requests (except /getSample) require authentication using your API key. You can pass your API key in any one of three ways:

1. X-API-Key Header (Recommended)

X-API-Key: hindsight_live_xxxxx

2. Authorization Header (Bearer Token)

Authorization: Bearer hindsight_live_xxxxx

3. Query Parameter

?api_key=hindsight_live_xxxxx

You receive your API key after purchase. You can rotate your key at any time via the API.

Base URL

All API requests should be made to:

https://hindsightapi.com/.netlify/functions

Endpoints

GET/getData

Retrieve economic calendar data for a date range. Requires authentication.

Query Parameters

Parameter	Type	Description
`start_date`	string	Start date (YYYY-MM-DD)
`end_date`	string	End date (YYYY-MM-DD)
`country`	string	Filter by country code (US, UK, EU, etc.)
`min_volatility`	integer	Minimum volatility level (1-3, where 3 is highest impact)

Example Request

curl -X GET "https://hindsightapi.com/.netlify/functions/getData?start_date=2024-08-05&end_date=2024-08-05&country=US" \
  -H "X-API-Key: hindsight_live_xxxxx"

GET/getSample

Get free sample data (August-September 2023, US markets, volatility 2+). No authentication required.

Example Request

curl "https://hindsightapi.com/.netlify/functions/getSample"

POST/rotateApiKey

Rotate your API key. Your current key will be invalidated immediately and a new one will be returned.

Request Body

{
  "currentApiKey": "hindsight_live_xxxxx"
}

Example Request

curl -X POST "https://hindsightapi.com/.netlify/functions/rotateApiKey" \
  -H "Content-Type: application/json" \
  -d '{"currentApiKey": "hindsight_live_xxxxx"}'

Response

{
  "success": true,
  "newApiKey": "hindsight_live_yyyyy",
  "message": "API key rotated successfully. Your old key is now invalid."
}

Response Format

All responses are in JSON format. A successful response includes:

{
  "success": true,
  "data": [
    {
      "event_id": "abc123def456",
      "date": "2024-08-05",
      "time": "10:00",
      "timezone": "America/New_York",
      "country": "United States",
      "country_code": "US",
      "event_name": "ISM Services PMI",
      "volatility": 3,
      "actual": "51.4",
      "forecast": "51.0",
      "previous": "48.8"
    },
    {
      "event_id": "xyz789ghi012",
      "date": "2024-08-05",
      "time": "14:00",
      "timezone": "America/New_York",
      "country": "United States",
      "country_code": "US",
      "event_name": "Treasury Sec. Yellen Speaks",
      "volatility": 2,
      "actual": null,
      "forecast": null,
      "previous": null
    }
  ]
}

Field Descriptions

Field	Description
`event_id`	Unique identifier for the event
`date`	Event date (YYYY-MM-DD)
`time`	Event time (HH:MM, Eastern Time)
`country / country_code`	Full country name and ISO code
`event_name`	Name of the economic event
`volatility`	Impact level (1=low, 2=medium, 3=high)
`actual`	Actual reported value (null if not yet released)
`forecast`	Consensus forecast value
`previous`	Previous period value

Error Handling

The API uses standard HTTP status codes:

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing API key
`403`	Forbidden - Invalid or expired API key
`500`	Internal Server Error

Error Response Format

{
  "success": false,
  "error": "Invalid or expired API key. Please check your subscription status."
}

Need Help?

If you have any questions or need assistance, reach out to us at hi@fullstackcraft.com