API Documentation

All public endpoints return JSON and are rate-limited per IP. No authentication is required for GET endpoints. The POST endpoint requires an API key.

Base URL

Rate Limits

All endpoints are rate-limited per IP address. Exceeding the limit returns a 429 status. Response headers include X-RateLimit-Limit and X-RateLimit-Remaining.

/api/resume/	20 requests/min
/api/weather/	60 requests/min
/api/weather/weekly/	30 requests/min
/api/weather/report/	30 requests/min
/api/weather/create/	10 requests/min

Authentication

The POST endpoint requires an API key sent via the X-Api-Key header. Public GET endpoints require no authentication.

# Example authenticated request
curl -X POST https://yourfutureheroes.com/api/weather/create/ \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-key-here" \
  -d '{"temperature": 72.5, ...}'
            

GET /api/resume/ Public

Downloads the current active resume as a .docx file.

Response

Returns the file as a download (application/octet-stream), or a JSON error if no resume is available.

Error Response

{
  "error": "No resume available"
}
                    

Download Resume

GET /api/weather/ Public

Returns the most recent weather reading.

Example Response

{
  "data": {
    "id": 42,
    "temperature": 72.5,
    "humidity": 45.0,
    "sky_condition": "clear",
    "sky_condition_display": "Clear",
    "precipitation": "none",
    "precipitation_display": "None",
    "notes": "",
    "recorded_at": "2026-04-01T14:30:00+00:00"
  }
}
                    

GET /api/weather/weekly/ Public

Returns all weather readings from the last 7 days.

Example Response

{
  "count": 21,
  "period": {
    "from": "2026-03-25T00:00:00+00:00",
    "to": "2026-04-01T14:30:00+00:00"
  },
  "data": [
    { "id": 42, "temperature": 72.5, /* ... */ },
    // ... more entries
  ]
}
                    

GET /api/weather/report/ Public

Returns weather analytics including high/low temperatures, averages, precipitation events, and sky condition breakdowns for today and the past week.

Example Response

{
  "today": {
    "date": "2026-04-01",
    "high": 78.2,
    "low": 62.1,
    "avg_temperature": 70.3,
    "avg_humidity": 52.5,
    "readings": 5
  },
  "week": {
    "from": "2026-03-25",
    "to": "2026-04-01",
    "high": 82.0,
    "low": 55.4,
    "avg_temperature": 68.7,
    "avg_humidity": 48.2,
    "readings": 21,
    "precipitation_events": [
      { "type": "rain", "count": 3 }
    ],
    "sky_conditions": [
      { "type": "clear", "count": 12 },
      { "type": "partly_cloudy", "count": 6 }
    ]
  }
}
                    

POST /api/weather/create/ API Key Required

Submit a new weather reading. Requires an API key via the X-Api-Key header.

Request Headers

Header	Value
Content-Type	application/json
X-Api-Key	Your API key required

Request Body

Field	Type		Description
temperature	number	required	Temperature in °F
humidity	number	required	Humidity percentage (0–100)
sky_condition	string	required	Sky/cloud coverage clear mostly_clear partly_cloudy mostly_cloudy overcast foggy
precipitation	string	required	Precipitation type none rain drizzle snow sleet hail freezing_rain
notes	string	optional	Freeform notes
recorded_at	string	optional	ISO 8601 datetime. Defaults to now.

Example Request

curl -X POST https://yourfutureheroes.com/api/weather/create/ \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-key-here" \
  -d '{
    "temperature": 72.5,
    "humidity": 45.0,
    "sky_condition": "clear",
    "precipitation": "none",
    "notes": "Beautiful day"
  }'
                    

Success Response 201 Created

{
  "created": {
    "id": 43,
    "temperature": 72.5,
    "humidity": 45.0,
    "sky_condition": "clear",
    "sky_condition_display": "Clear",
    "precipitation": "none",
    "precipitation_display": "None",
    "notes": "Beautiful day",
    "recorded_at": "2026-04-01T14:30:00+00:00"
  }
}
                    

Error Responses

// 401 - Missing or invalid API key
{ "error": "Invalid or missing API key" }

// 400 - Missing required fields
{ "error": "Missing required fields: temperature, humidity" }

// 400 - Invalid enum value
{ "error": "sky_condition must be one of: clear, mostly_clear, ..." }
                    