Get started
Authentication
Every endpoint except Status needs an API key, sent in the X-Api-Key header:
curl "https://studyingstocks.com/api/v1/companies/AAPL" -H "X-Api-Key: ss_live_..."
The key
- A key looks like
ss_live_followed by 40 random letters and digits. -
Header only. There is no
?apikey=query parameter, on purpose: keys in URLs end up in server logs, proxies and browser history. A key in the query string is ignored and the request is answered with401. - Keep the key secret and do not use it in code that runs in a browser or an app you distribute.
Creating, regenerating and revoking
Only active Premium subscribers can manage a key, on the profile page:
- Create: the full key is shown once. We store only a SHA-256 hash and the first characters (the prefix), so we cannot show it again or recover it.
- Regenerate: creates a new key and revokes the old one at once. Do this if a key may have leaked.
- Revoke: the key stops working at once.
When the subscription ends
A key works only while its owner's Premium subscription is active. When the subscription lapses, requests are answered with 403 and the code subscription_inactive. Because the check is cached, this can take up to 5 minutes to show. Renew the subscription and the same key works again.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated |
The header is missing, or the key is malformed, unknown or revoked |
| 403 | subscription_inactive |
The key is valid but its Premium subscription is not active |
| 429 | rate_limited |
Too many requests (also for repeated requests with a wrong key from one IP address) |
See errors for the format.