Note that all these endpoints require the X-API-Key header to be set.
All returned JSON payloads adhere to the following return format unless explicitly stated otherwise:
See Data Models for more information about the models that can be returned.
All fields in the returned payload are nullable, apart from user.user_id, user.provider, and data which are guaranteed to be populated with a string, string, and empty or populated array respectively.
Some endpoints support the sending of the returned data to your webhook URL instead of in the response. Whether or not an endpoint supports this feature can be seen in the endpoint description. To tell the server to send the data in the response instead of to the webhook, you should pass an additional query parameter - to_webhook=false - to the request. If this flag is not passed, you will be sent a payload in the response which adheres to the following schema:
The reference field contains a unique identifier which will also be sent in the webhook request header terra-reference and allows you to link the webhook payload back to the request to our server that fetched the data. Note that the order of the response being sent back to you and the data arriving at your webhook is not guaranteed - therefore the data may arrive at the webhook before you have received the response.
An additional query parameter, with_samples is supported to allow the filtering of sample/timeseries data out of the payload returned to you. If set to false, no samples will be returned in the payload we send. This can significantly reduce the amount of data transferred so may be useful to reduce the amount of time that data transfer takes. The default value is true.
Some data providers do not implement appropriate endpoints for the ones seen below. In this case we return a generic "no data returned response" which adheres to the following schema:
In some cases, providers may require extra time to process data for the request. If this happens, a special response will be returned to you indicating that this is the case. In this response, the field retry_after will be included which contains the number of seconds until the request data will be ready. You should remake the same request after retry_after seconds in order to receive the data. The schema for this response can be seen below:
All HTTP endpoints support response compression. Responses can be compressed using either the brotli or gzip compression algorithms. To enable response compression you should send the algorithm(s) that your HTTP client can accept in the Accept-Encoding header - the server will choose an algorithm to use based on this header and return the compressed response with the header Content-Encoding set appropriately for the algorithm that was used.