Core Endpoints

Authentication

When a developer licenses content through the Vermillio Platform, client credentials are provided. Client credentials consist of a client_id and client_secret which are used in an OAuth 2 Authorization Code Flow to acquire an access_token. All requests to Vermillio Endpoints require a valid access_token passed via the Authorization header as a bearer token.

The flow is initiated by calling the following endpoint:

POST https://auth.cloud.vermill.io/oauth2/token

with the following form (not JSON) parameters: - client_id: The client_id provided by Vermillio associated with your application. - client_secret: The client_secret provided by Vermillio associated with your application. - grant_type: Required and always set to client_credentials. - audience: Required and always set to grant_type=https://application.vermill.io

If the provided credentials are correct, the endpoint will respond with a JSON object with the following fields:

• access_token : This is the access token that should be used in all subsequent requests to Vermillio Endpoints.
• expires_in : The number of seconds as an int until the access_token is expired. Expired tokens will not be accepted by Vermillio Endpoints.
• scope : The scope of the access token.
• token_type : The type of token.

On subsequent calls to Vermillio Endpoints the access_token should be used in the Authorization header as a bearer token, for example:

Authorization: Bearer {access_token}

Asset Management

Partner applications interact with assets on Vermillio through the following endpoints.

• GET /partner/asset/list - Retrieves List[PartnerAsset] records available to the licensed application.
• GET /partner/asset/{id} - Retrieves a specific PartnerAsset record, if available to the licensed application.
• GET /partner/asset/download/{id} - Retrieves the media files for a PartnerAsset record that the licensed application has available. If there are multiple files they will be packaged as a .zip with a metadata file that describes the contents.
• GET /partner/asset/download/media/{id} - Retrieves the specified media file for a PartnerAsset record that is available to the licensed application.
• POST /partner/asset/upload - Creates a new asset by uploading file(s), passing the following query parameters, and returning a Asset owned by the application owner:
  • title : What is the new asset called.
  • type : Type of asset, one of the following options: Image, Video, Audio, Model, or Dataset
  • parentAssetId : Optional field referencing which parent asset this new asset is derived from.

An example of a PartnerAsset record:

{
  "id": "assetId123",
  "type": "Image",
  "title": "Source IP",
  "description": "Source IP Description",
  "traceIds": ["traceId1", "traceId2"],
  "media": [
    {
      "id": "mediaId1",
      "filename": "mediaFile.png",
      "byteSize": 1234
    }
  ],
  "owner": {
    "id": "owner123",
    "name": "IP Owner"
  }
}

Usage Tracking

The following endpoints are available for use cases of reporting usage of licensed assets that fall outside of the scope of the typical asset upload process.

POST /partner/tracking/usage - Report the usage of an asset, post body is JSON object with the following fields:

• title : A friendly name describing what was created.
• parentAssetIds : The ids of all of the asset(s) that were used to create the new content.
• count : Optional number of pieces of content that were generated, defaults to 1.
• data : Optional arbitrary metadatadata to store alongside the usage tracking.

POST /partner/tracking/action - Report an action of asset(s), post body is a JSON object with the following fields:

• action : What the action is, options include: Publish
• assetIds : List of asset ids that the action applies to.
• location : Optional location that the content is accessible at.
• data: Optional arbitrary metadata to store alongside the action tracking.

POST /partner/tracking/revenue - Report revenue that was generated from derived assets, post body is a List of JSON objects, each with the following fields:

• assetIds : List of asset ids that the revenue was driven by.
• currency : ISO 417 currency code for the amount of reported.
• amount : float amount of currency.
• transactionId : Optional transaction id that drove the transaction.
• data : Optional arbitrary metadata to store alongside the revenue tracking.