API docs by Redocly

Stipify REST API - OpenAPI 3.0 (1.0)

Download OpenAPI specification:

Stipify API documentation.

public

Heartbeat

Responses

Response samples

Content type
application/json
{
  • "time": "2025-11-01T09:37:15+00:00"
}

Aggregator status

Responses

Response samples

Content type
application/json
{
  • "status": "up"
}

authentication

Issue OAuth2 client token

Client credentials token endpoint accepting JSON (preferred) or form data.

Request Body schema:
required
grant_type
required
string
Value: "client_credentials"
client_id
required
string
client_secret
required
string

Responses

Request samples

Content type
grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0
}

Mint a User Delegation Token

Issues a UDT for the specified user/device using tenant client credentials.

Authorizations:
OAuth2
path Parameters
userId
required
string

ID of the end user for whom the UDT is issued.

Request Body schema: application/json
required
deviceId
required
string <uuid>

Unique identifier of the device the UDT is bound to.

Responses

Request samples

Content type
application/json
{
  • "deviceId": "a9b66a51-3cb6-4e66-bb94-675e83380fe5"
}

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "expires_in": 600,
  • "token": "token-string"
}

users

List users

Returns a paginated list of users belonging to the tenant.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": { },
  • "meta": { }
}

Create user

Creates a new user for the tenant.

Authorizations:
OAuth2
Request Body schema: application/json
required
first_name
required
string
last_name
required
string
email
required
string <email>
date_of_birth
required
string <date>
status
string
Enum: "SUBSCRIBED" "UNSUBSCRIBED" "PENDING_SUBSCRIPTION"

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get user

Returns details of a specific user.

Authorizations:
OAuth2
path Parameters
user
required
string <uuid>

ID of the user.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update user

Updates details of a specific user.

Authorizations:
OAuth2
path Parameters
user
required
string <uuid>

ID of the user.

Request Body schema: application/json
required
first_name
string
last_name
string
email
string <email>
date_of_birth
string <date>
status
string
Enum: "SUBSCRIBED" "UNSUBSCRIBED" "PENDING_SUBSCRIPTION"

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete user

Deletes a specific user.

Authorizations:
OAuth2
path Parameters
user
required
string <uuid>

ID of the user.

Responses

other

Current user profile

Returns profile data for the caller authenticated with a UDT.

Authorizations:
UDT

Responses

Response samples

Content type
application/json
{
  • "user_id": "e916baf0-7985-417e-8a8a-6166baf0d9cd",
  • "tenant_id": "0584967b-57e1-491b-8b3e-a84c5dfe6b66",
  • "client_id": "019a82f5-c038-7357-a567-31ce76b96a52"
}

Search artists

Search for artists using the aggregator service.

Authorizations:
OAuth2
query Parameters
q
required
string

Search terms

page
integer >= 1

Page number

pageSize
integer [ 10 .. 50 ]

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "estimatedTotalItems": 0,
  • "page": 0,
  • "expectedPageSize": 0,
  • "results": [
    ]
}

Get artist details

Get detailed information about a specific artist.

Authorizations:
OAuth2
path Parameters
artistId
required
string

ID of the artist

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "artist": {
    }
}

Get artist releases

Get releases for a specific artist.

Authorizations:
OAuth2
path Parameters
artistId
required
string

ID of the artist

query Parameters
usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

type
string
Enum: "album" "single" "video"

Release type

imageSize
integer
Enum: 33 50 100 180 182 200 350 500 800

Image size

page
integer >= 1

Page number

pageSize
integer [ 10 .. 50 ]

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "releases": {
    }
}

Browse artists

Browse artists by letter.

Authorizations:
OAuth2
query Parameters
letter
required
string

Letter to browse by

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "artists": {
    }
}

playback

Fetch HLS manifest for a track

Returns an HLS manifest. The payload query parameter is an opaque token that identifies the track to fetch.

Authorizations:
BearerAuth
query Parameters
payload
required
string

Opaque token that identifies the track to fetch.

Responses

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

Fetch a single HLS segment

Returns HLS segment bytes. The segment query parameter is an opaque token that identifies the segment to fetch.

Authorizations:
BearerAuth
query Parameters
payload
required
string

Opaque token that identifies the track to fetch.

segment
required
string

Opaque token that identifies the segment to fetch.

header Parameters
Range
string

Optional byte-range request.

If-None-Match
string

Optional ETag validator.

If-Modified-Since
string

Optional date validator.

Responses

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}