Studio offers RESTful APIs for request/response flows. This section should help you familiarize yourself with how develop against our REST APIs. Our REST APIs utilize resource-oriented URLs, and all data is transferred in JSON. The endpoints for our REST APIs are generally predictable and oriented around resources that belong either to an account or legal-entity.

Servers

Our REST servers work over TLS to secure communications. We provide both a Sandbox and a Production environment with the Sandbox environment providing a safe way to explore the product without submitting live orders.

📘

To obtain access to our Sandbox environment, please send an email to [email protected] with the request along with all IP addresses you plan to connect from.

Authentication

Before calling any endpoints, you need to have a valid access token. Follow the instructions outlined in our OAuth2 Authentication guide.

With your access token, simply include it in your request header as a bearer token. Here's an example:

curl --request GET \
    --url https://api.clearstreet.io/studio/v2/entities \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <your-token>'

Errors

Studio uses conventional HTTP response codes. This generally means any response in the 2xx range was successful, while those in the 4xx and 5xx are failures. Some responses are indicative that you should programmatically retry, such as 429: Too Many Requests, which is indicative that you're being throttled.

We use RFC 9457 problem details schema for all error responses.

Pagination

Any GET endpoint that returns an array of objects will be described as a list endpoint. These list endpoints utilize cursor-based pagination, and they share a common structure in the parameters they accept for querying, along with their responses. Namely:

And the response will have the following shape:

{
  "data": [...]
  "next_page_token": <reference-to-next-page>
}

Rate Limits

Studio's API endpoints have rate-limits designed to throttle the frequency in which calls are made. The rate-limits are implemented using a token-bucket algorithm, and are enforced per user, per source IP. If you breach these limits, you will get a 429: Too Many Requests error. In the header of the response, the Retry-After value will indicate how long you need to wait before trying the request again.

The rate limits are set per endpoint and are as follows: