If you're keen on getting Streamtime to seamlessly interact with your bespoke software, you'll need to understand our API documentation and your exclusive API key.
About Swagger API
Streamtime's API docs are hosted on Swagger. Swagger presents a human-friendly interface where users can explore and understand an API. It also allows users to "try out" API calls directly from the browser, facilitating testing and understanding of API behaviour. The UI is generated from an OpenAPI Specification (OAS) file, which describes the API's structure, endpoints, parameters, responses, and authentication methods. This ensures the documentation is always in sync with the API's definition.
Check out Streamtime on Swagger here.
Step 1. Locate Your API Key
Head to Settings: Tap the ⚙️ icon and choose Integrations under Account Settings.
Grab Your Key: Scroll down to the API section and hit Connect. You will then have access to your key. Copy and paste the string.
Test the Key within Swagger's interface (that link again is here).
Once the key is obtained, enter it within the 🔓 Authorise settings page on Swagger. Now you're ready to start testing your API calls directly within the browser.
🔑 Can't locate the key? Only the account subscriber can access this key, ensuring you keep your setup snug and secure.
Rate Limits on our API
There are limits to the number of API calls that your application can make against a particular organisation in order to ensure reliability and availability:
60 requests per minute
720 requests per hour
In addition to the request limits, there are also duration limits as well to prevent against long running requests:
30 seconds of processing time per minute (2 second delay applied, request is still processed)
300 seconds of processing time per hour (429 error returned)
These limits are implemented to ensure the stability of our own application. If you're hitting them, chances are there is a more efficient way to make the calls! Reach out to help@streamtime.net if you are seeing rate limiting errors.
Searching Filter Groups
We've prepared some quick notes to help you search the filter groups through the API. Dev talk incoming!
🔍 Search View
Before we make any searches, we need to identify which searchView we are going to be using. The full list is enumerated in the swagger UI, however an example would be that Jobs are searchView 7, Invoices are searchView 11, and so on.
🛒 Available Filters
Now that we have our search view, we want to see what filters are available for that given data set. Again, Swagger UI has a route for just that, and once you’ve specified your search view, you can see all the available filters to use.
The filter group type also includes a lot of information about what the filter is, how it might be calculated (for some of the more complex calculated fields), and what the available options are for that field (for instance a status field will show you the list of status’ the field might have)
🔍 Constructing your search
Now that we have the foundational information we need, it’s time to start constructing our JSON search. Each search will follow this format:
filterGroupCollections are the large blocks of filters that apply to your query. Most simple searches will only have a single array of filterGroups, but if you want more complex conditions (eg complex nested AND/OR conditions), you may start having nested filterGroupCollections.
Eac0 filterGroupCollection and filterGroup will have a conditionMatchTypeId, which is whether to apply an AND (1) or OR (2) to the filters that are contained within.
The filterGroupTypeId is the reference to which specific field you are wanting to filter on, which you would have retrieved earlier.
🥧 Simple filtering example
Let’s start constructing an example to search for jobs that are “In Play” for either the company Nike or Adidas. We firstly identify our “groups” of filters and their respective IDs. In this example, it’s Job Status (ID 3) and Company Name (ID 1). Because we are applying an AND condition between the filters, we use conditionMatchTypeId 1 in the filterGroupCollection to represent AND.
Now we start constructing the company filterGroup. In our example, because we are looking for “Nike” OR “Adidas”, we use conditionMatchTypeId 2 to represent OR between these filters. Then for each filter, we use valueMatchTypeId 1 for “Equals”, and provide the name of the company in the value field.
The Job Status filter is much the same, except instead of the name “In Play”, we just use the options we retrieved earlier and use the value ‘1’ to represent “In Play”.
With that, we’ve constructed the entire filterGroupCollection and we’re ready to make the request.
🧪 Complex conditions
Now that we’ve finished with simple conditions, let’s dive into a more complex example. Just like with maths operators, we might need to have more complex combinations of our AND/OR conditions. This is where filterCollections come into play.
Let’s consider the following example:
Job label isn’t “internal” and (job label is “Campaign” or “Branding”)
In this scenario, we’re trying to find any job with the “Campaign” or “Branding” label, but we want to exclude all of our in-house jobs like “Admin” or “Annual Leave”. What we need to do is create a collection with the “Campaign” and “Branding” filters with a conditionMatchTypeId of 2 (OR) and a second collection with our “Internal” filter.
