Please read the sections below before trying to build any production software against the Pine API. While the API is designed to be simple and easy-to-use, there are a few powerful features and paradigms that you should be familiar with prior to starting development.
If you're ready to go, and you've read the sections below, then jump straight to the Endpoints Reference →
Note: The API is still under development and the format is subject to change, but we will try to maintain backwards compatibility in most cases. Fields may be added to responses, but rarely removed or changed unless absolutely necessary.
General requests to the API and site are rate limited by client IP to ~60/minute to prevent spam. Normally this won't be an issue for users or for those looking to write simple scripts against the API. However if you need more frequent access to the API you can upgrade to a Premium Account to remove this restriction. Premium accounts are useful for anyone wanting to build production software against the Pine API.
Premium accounts can authenticate with the API to receive a time-limited access token and remove the ~60/minute limit. These premium accounts use an OAuth scheme called client_credentials and are designed to be invoked on a secure server which proxies requests to Pine from a client. Do not put your Premium API Keys in your web or native clients as neither can be trusted to keep the secret safe. If at any time you need to regenerate your API keys, you can do so from your account page.
Note: Requests to the API even with an access token are technically also rate limited to ~1000/minute to prevent spam. If you require that the limit be removed, please email support@skyrocket.software and we can talk about your needs.
As indicated, throttling limits are approximations and may in-fact be higher than indicated. This is because API results are cached for a short period to ease the burden of repeated, identical queries. This means that in practice the API limit you encounter could be slightly higher than but no less than the indicated limit if you repeatedly request the same data. You can see whether or not your query was served from the cache by checking the X-Proxy-Cache header.
The Pine API is a JSON-REST API and abides by most of the typical REST paradigms. The API uses response codes and HTTP request methods to determine intent. This is enforced as much as possible so while it may not be strictly the case for all endpoints, the vast majority of endpoints use the standard conventions.
Note: Endpoints with custom request method behavior will be noted as such in the endpoint's documentation.
Most response codes used by Pine's API reflect standard behaviour defined in the HTTP specification, however here are some common scenarios where you might encounter a response code and what it might mean.
200 OK
This is the typical response code that a request will encounter. It means according to standard behaviour that the request succeeded and returned results.
429 Too Many Requests
If you've exceeded your request count, then subsequent requests will receive responses with error code 429 with both a response containing a human-readable message and a
Retry-Afterheader field with the seconds until requests will again be accepted.$ http https://pine.blog/api/too_frequent_request HTTP/1.0 429 Too Many Requests Allow: GET, HEAD, OPTIONS // ... Retry-After: 34 { "detail": "Request was throttled. Expected available in 34 seconds." }
Note: Endpoints with special response codes will be noted as such in the endpoint's documentation.
API responses may, at any time, include a _meta entry at the top level. This entry will contain at least one important piece of information about the current query or endpoint. These can be deprecation notices, beta API notices, and more. These notices are intended to be read by a developer and provide helpful information about the requested API endpoint.
Deprecation notices will often, but not always include an effective_date and replaced_by entry if one exists. In all cases the deprecation notice will have a plain-text message explaining the deprecation.
As an example, if an API was deprecated, then the developer requesting the deprecated API would see something like the following:
$ http http://pine.blog/api/some_deprecated_api
{
"_meta": {
"deprecation_notice": {
"effective_date": "2018-01-01",
"message": "Warning, this API has been deprecated and will be no longer be reliable after the specified date.",
"replaced_by": "/api/some_new_api"
}
},
// ...
}
Endpoints are sometimes released while still in beta for developers to try out and give feedback. These APIs will not only be marked as beta in the documentation, but will also have a beta_notice in the meta section of all API responses.
Beta notices will often, but not always include an link entry which points to a section of the documentation explaining the new endpoint. In all cases the beta notice will have a plain-text message explaining that is is subject to change.
$ http http://pine.blog/api/some_beta_api
{
"_meta": {
"beta_notice": {
"link": "https://pine.blog/api/documentation/endpoints#some_beta_api",
"message": "Warning, this endpoint is currently in beta and is subject to change. Please see our documentation for more information."
}
},
// ...
}