WeatherStack Core External API 1.x.x

These API routes follow the standard API guidelines, and can provide data in a range of different methods, mainly JSON (application/json), some may not accept data at all, or only by JSON (application/json), please see individual API route documentation.

---

GET /

Description:
This API route is simply to return a small JSON object, telling you some basic information as to what is running on that port.
Accepts:
(0)

Possible responses:

200

{
    "success": true,
    "code": 200,

    "message": "Number 5 is alive!",

    "version": "1.0.0",                                         // Current version
    "name": "WeatherStack Core External API",                   // Name (Makes it easier to look it up)
    "repository": "https://github.com/WeatherStack/Core"        // Repository link
}

---

GET /v1/health/liveliness

Description:
Only returns status 200 if everything is good, and working correctly and as expected.
Accepts:
(0)

Possible responses:

200

No content.

---

GET /v1/health/info

Description:
This API route gives more in-depth information, such as uptime.
Accepts:
(0)

Possible responses:

200

{
    "success": true,
    "code": 200,

    "message": "Dude, you can't run from the future!",

    "stats": {
        "uptime": 3538688.83811651,
        "uptime_human": "1 months 10 days 12 hours 24 minutes 32 seconds 838 milliseconds"
    }
}

---

POST /v1/auth/authenticate/

Not yet implemented

This has not yet been implemented, so the below documentation may change.

Description:
The API route to do basic authentication, this API route does not handle token upgrading, only basic authentication.
For more information, read the security documentation (which doesn't exist yet).
Accepts:
JSON (application/json) (1)

note

This can only return a basic token, as that is the default, to perform any elevated actions, such as modifying configuration, or making any changes, you will need to elevate/upgrade the token temporarily.

Expected body content:

JSON (application/json)

{
    // Username OR email
    "username": "john.doe",
    "email": null,

    "password": "s0m3%c00l!p@$$w0rd123"     // Passwords do not need to be encrypted, as it's over HTTPS
}

Possible responses:

200

Headers:

Header	Value
Content-Type	application/json

Data type:
JSON (application/json)

{
    "success": true,
    "code": 200,

    "message": "Authenticated successfully!",

    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30",
    
    "info": {
        "token_duration": 2592000,
        "token_duration_human": "30 days",

        "valid_from": "2026-01-00T17:30:00.000Z",
        "valid_to": "2026-01-30T17:30:00.000Z",

        "token_level": 0 // Returns a basic token first
    }
}

403

Headers:

Header	Value
Content-Type	application/json

Data type:
JSON (application/json)

{
    "success": true,
    "code": 403,

    "message": "Invalid credentials",

    // A generic error code that can be easily understood by the front-end
    // doesn't have be documented
    "error": "AUTH_INVALID_CREDENTIALS"
}

500

Headers:

Header	Value
Content-Type	application/json

Data type:
JSON (application/json)

{
    "success": true,
    "code": 403,

    "message": "We goin' to the moon!",

    // A generic error code that can be easily understood by the front-end
    // doesn't have be documented
    "error": "AUTH_NOT_READY_YET"
}