Endpoints for managing safelisting licenses. Allows partners to create, list, update, and delete licenses for channels and videos on behalf of their end users.
openapi: 3.0.1
info:
title: Partner Content Assets Safelisting API
version: 0.1.17
description: These endpoints allows your application to upload assets such as images or audio.
servers:
- url: https://partner-content-api.epidemicsound.com
description: Epidemic Sound Content API
tags:
- name: Safelisting
description: Endpoints for managing safelisting licenses. Allows partners to create, list, update, and delete licenses for channels and videos on behalf of their end users.
paths:
/v0/safelisting/licenses:
get:
tags:
- Safelisting
summary: List safelisting licenses
description: List safelisting licenses for the specified end user. Supports filtering by asset type, platform, and status, with pagination and sorting.
operationId: GET_Safelisting_Licenses
parameters:
- name: X-Partner-User-Id
in: header
description: The partner's end user identifier. Used to scope licenses per end user.
required: true
- name: assetType
in: query
description: Filter by asset type
required: true
schema:
type: string
enum:
- channel
- video
- name: platform
in: query
description: Filter by platform
required: false
schema:
type: string
enum:
- youtube
- instagram
- facebook
- twitch
- tiktok
- podcast
- website
- name: status
in: query
description: Filter by status. Currently only `active` licenses are returned.
required: false
schema:
type: string
enum:
- active
- name: sortBy
in: query
description: Field to sort results by
required: false
schema:
type: string
enum:
- createdAt
- expiresAt
default: expiresAt
- name: sortOrder
in: query
description: Sort direction
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
- name: page
in: query
description: Page number (1-based)
required: false
schema:
type: integer
format: int32
default: 1
- name: pageSize
in: query
description: Number of results per page
required: false
schema:
type: integer
format: int32
default: 25
responses:
'200':
description: License list
content:
application/json:
schema:
$ref: '#/components/schemas/SafelistingLicenseListResponse'
example:
page: 1
pageSize: 25
totalItems: 1
data:
- id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createdAt: '2024-06-01T10:00:00Z'
expiresAt: '2026-12-31T23:59:59Z'
asset:
id: UCxxxxxxxxxxxxxxxxxx
type: channel
platform: youtube
url: https://www.youtube.com/@somechannel
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Bad request
'401':
description: Unauthorized. Most likely your access token has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Invalid credentials
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Rate limit exceeded
security:
- ApiKeyAuth: []
post:
tags:
- Safelisting
summary: Create a safelisting license
description: Create a new safelisting license for a channel or video. The `X-Partner-User-Id` header is required to scope the license to a specific end user.
operationId: POST_Safelisting_License
parameters:
- name: X-Partner-User-Id
in: header
description: The partner's end user identifier. Used to scope licenses per end user.
required: true
requestBody:
description: License creation request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSafelistingLicenseRequest'
example:
asset:
type: channel
platform: youtube
url: https://www.youtube.com/@somechannel
expiresAt: '2026-12-31T23:59:59Z'
required: true
responses:
'201':
description: Created license
content:
application/json:
schema:
$ref: '#/components/schemas/SafelistingLicenseResponse'
example:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createdAt: '2024-06-01T10:00:00Z'
expiresAt: '2026-12-31T23:59:59Z'
asset:
id: UCxxxxxxxxxxxxxxxxxx
type: channel
platform: youtube
url: https://www.youtube.com/@somechannel
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Bad request
'401':
description: Unauthorized. Most likely your access token has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Invalid credentials
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Rate limit exceeded
'409':
description: Asset already safelisted by another user in this workspace
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Conflict
'403':
description: Workspace does not have safelisting entitlement
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Forbidden
security:
- ApiKeyAuth: []
delete:
tags:
- Safelisting
summary: Delete all licenses for an end user
description: Expires all active licenses for the specified end user within the workspace. Intended for end-user churn scenarios (e.g. when a user cancels their subscription). Returns 204 regardless of whether the user had any active licenses.
operationId: DELETE_Safelisting_Licenses
parameters:
- name: X-Partner-User-Id
in: header
description: The partner's end user identifier. Used to scope licenses per end user.
required: true
responses:
'204':
description: All licenses expired successfully
'401':
description: Unauthorized. Most likely your access token has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Invalid credentials
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Rate limit exceeded
security:
- ApiKeyAuth: []
/v0/safelisting/licenses/{licenseId}:
get:
tags:
- Safelisting
summary: Get a safelisting license
description: Retrieve a single safelisting license by ID. Returns 404 if the license does not exist or does not belong to the specified end user.
operationId: GET_Safelisting_License
parameters:
- name: licenseId
in: path
description: License ID
required: true
- name: X-Partner-User-Id
in: header
description: The partner's end user identifier. Used to scope licenses per end user.
required: true
responses:
'200':
description: License
content:
application/json:
schema:
$ref: '#/components/schemas/SafelistingLicenseResponse'
example:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createdAt: '2024-06-01T10:00:00Z'
expiresAt: '2026-12-31T23:59:59Z'
asset:
id: UCxxxxxxxxxxxxxxxxxx
type: channel
platform: youtube
url: https://www.youtube.com/@somechannel
'401':
description: Unauthorized. Most likely your access token has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Invalid credentials
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Rate limit exceeded
'404':
description: License not found or does not belong to this end user
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Safelisting license was not found
security:
- ApiKeyAuth: []
delete:
tags:
- Safelisting
summary: Delete a safelisting license
description: Expire a safelisting license by ID. The license is soft-deleted and will no longer appear in active license listings.
operationId: DELETE_Safelisting_License
parameters:
- name: licenseId
in: path
description: License ID
required: true
- name: X-Partner-User-Id
in: header
description: The partner's end user identifier. Used to scope licenses per end user.
required: true
responses:
'204':
description: License expired successfully
'401':
description: Unauthorized. Most likely your access token has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Invalid credentials
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Rate limit exceeded
'404':
description: License not found or does not belong to this end user
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Safelisting license was not found
security:
- ApiKeyAuth: []
patch:
tags:
- Safelisting
summary: Update a safelisting license
description: Update a safelisting license. Currently only the expiration date can be modified.
operationId: PATCH_Safelisting_License
parameters:
- name: licenseId
in: path
description: License ID
required: true
- name: X-Partner-User-Id
in: header
description: The partner's end user identifier. Used to scope licenses per end user.
required: true
requestBody:
description: License update request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSafelistingLicenseRequest'
example:
expiresAt: '2027-12-31T23:59:59Z'
required: true
responses:
'200':
description: Updated license
content:
application/json:
schema:
$ref: '#/components/schemas/SafelistingLicenseResponse'
example:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createdAt: '2024-06-01T10:00:00Z'
expiresAt: '2027-12-31T23:59:59Z'
asset:
id: UCxxxxxxxxxxxxxxxxxx
type: channel
platform: youtube
url: https://www.youtube.com/@somechannel
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Bad request
'401':
description: Unauthorized. Most likely your access token has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Invalid credentials
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Rate limit exceeded
'404':
description: License not found or does not belong to this end user
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Safelisting license was not found
security:
- ApiKeyAuth: []
components:
schemas:
SafelistingAssetRequest:
required:
- platform
- type
- url
type: object
properties:
type:
type: string
enum:
- channel
- video
platform:
type: string
enum:
- youtube
- instagram
- facebook
- twitch
- tiktok
- podcast
- website
url:
type: string
SafelistingLicenseListResponse:
required:
- data
- page
- pageSize
- totalItems
type: object
properties:
page:
type: integer
format: int32
pageSize:
type: integer
format: int32
totalItems:
type: integer
format: int32
data:
type: array
items:
$ref: '#/components/schemas/SafelistingLicenseResponse'
Error:
required:
- key
- messages
type: object
properties:
key:
type: string
description: Error key
messages:
type: array
description: Error messages
items:
type: string
description: Error messages
MessageResponse:
required:
- message
type: object
properties:
message:
type: string
description: Human readable message
errors:
type: array
items:
$ref: '#/components/schemas/Error'
UpdateSafelistingLicenseRequest:
required:
- expiresAt
type: object
properties:
expiresAt:
type: string
CreateSafelistingLicenseRequest:
required:
- asset
type: object
properties:
asset:
$ref: '#/components/schemas/SafelistingAssetRequest'
expiresAt:
type: string
SafelistingAssetResponse:
required:
- id
- platform
- type
- url
type: object
properties:
id:
type: string
type:
type: string
enum:
- channel
- video
platform:
type: string
enum:
- youtube
- instagram
- facebook
- twitch
- tiktok
- podcast
- website
url:
type: string
SafelistingLicenseResponse:
required:
- asset
- createdAt
- id
type: object
properties:
id:
type: string
createdAt:
type: string
expiresAt:
type: string
asset:
$ref: '#/components/schemas/SafelistingAssetResponse'
securitySchemes:
ApiKeyAuth:
type: http
description: 'API key authentication for server-to-server communication.
Pass your API key as a Bearer token in the Authorization header.
API keys are prefixed with `epidemic_live_`.
> **Example Header:** `Authorization: Bearer epidemic_live_your-api-key`'
scheme: bearer
PartnerAuth:
type: http
description: 'Partner authentication is handled with short lived partner access tokens.
Use your api credentials to request these tokens.
The access token is of JWT format and should be passed in a header with your API requests:
> **Example Header:** `Authorization: Bearer your-partner-token`'
scheme: Bearer
UserAuth:
type: http
description: "User authentication is handled with short lived user access tokens.\n Use a partner token to request these tokens.\n The access token is of JWT format and should be passed in a header with your API requests:\n\n > **Example Header:** `Authorization: Bearer a-user-token`"
scheme: Bearer
EpidemicSoundConnectAuth:
type: oauth2
description: 'For users signing in with an Epidemic Sound account, user authentication is
handled with OpenID Connect, which is a layer on top of OAuth 2.0.
> **Example Header:** `Authorization: Bearer es-connect-token`'
flows:
authorizationCode:
authorizationUrl: https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/auth
tokenUrl: https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/token
scopes: {}