API Basics
API Access
To start building with the Streamdiver API, you need a tenant with API credentials. Request a trial to get your clientId and clientSecret – or check out the Publishing-Suite live demo to see the platform in action first.
You can explore all available endpoints in the interactive API reference right now – no signup required.
OpenAPI Specification File
See OpenAPI and Client Generation for details on the spec, client generation, and download.
API Protocols and Headers
The Streamdiver API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The HTTP responses follow the JSend JSON specification. The Streamdiver API is served over HTTPS TLS v1.2+ to ensure data privacy; HTTP and HTTPS with TLS versions below 1.2 are not supported.
Common Response Attributes
The Streamdiver API responses adhere to a standardized structure to ensure clarity and consistency. The following are the common attributes you can expect in a response:
| Field | Type | Description |
|---|---|---|
status | string | Indicates the status of the response. It can take one of three values:success, fail, or error. This field provides a high-level overview of the outcome. |
data | object | Holds the actual content of the response. Its structure and content depend on the specific endpoint and the type of request made. In a success response, this typically contains the requested data. |
message | string | Provides additional information about the response status. It's especially useful in cases where an error or failure occurs, offering details about what went wrong. |
Pagination
List endpoints return paginated results. Use the following query parameters to control pagination:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 0 | Page number (0-based) |
perpage | integer | 10 | Items per page (max 50) |
sort | string | – | Sort by property name. Append :desc for descending order (e.g., name:desc) |
Example:
GET /v2/media?perpage=20&page=0&sort=name:desc
Error Codes
The API uses standard HTTP status codes. Common error responses:
| Status | Meaning | Description |
|---|---|---|
200 | OK | Request succeeded |
201 | Created | Resource successfully created |
400 | Bad Request | Invalid request syntax or parameters |
401 | Unauthorized | Missing or invalid authentication token |
403 | Forbidden | Valid token but insufficient permissions |
404 | Not Found | Resource does not exist |
409 | Conflict | Duplicate resource (e.g., duplicate file upload) |
422 | Unprocessable Entity | Request body failed validation |
Error responses follow the standard JSend format with a message field describing the issue.