Skip to main content
Documentation Powered by Redocly

Caast API Reference (v1)

Download OpenAPI specification:Download

Caast is a solution to easily create, manage and display live shopping stream and video content on your website directly with just a script.
Caast has an online admin panel where you can manage everything, but you can also use our API to include some Caast content handling in your own solution.

Lives

Caast lives are entities that are created to display live streaming content on your website.
Once created, you can retrieve an RTMP url along with a stream key to start sending your video flux.
You can affiliate a seller and some products to a live with their unique ID and also tag it at your will.

Note : They must have at start date and have three states on our side (unstarted, started, and finished). Once finished, a live produce a replay of the stream session

List lives

Get all lives of your app. You can add some parameters to filter the response.
This endpoint will return a paginated response with 20 items per page (along with pagination related response headers).

Authorizations:
(ApiKeyAppId)
query Parameters
name
string

Search by live name

product_id
string

Search for live with products of given id

product_ref
string

Search for live with products that match given reference (SKU)

seller_id
string

Filter lives created by seller with given ID

seller_name
string

Search for lives created by seller with given name

seller_external_id
string

Filter lives created by seller with given external ID

tags
Array of arrays

Filter lives that match the given array of tags

state
string

Search for lives with a specific state (not_started, started or finished)

order
string

Sort the results by creation date or start date with or without a direction (ASC, DESC). Possible values created_at:ASC, created_at:DESC, start_date:ASC, start_date:DESC

page
integer

Page number (this endpoint returns 20 items per page)

Responses

Response Headers
Current-Page
any

The current page returned by the API

Page-Items
any

The total of elements return for this page

Total-Pages
any

The number of pages available for this query

Total-Count
any

The total of items for this query

Response Schema: application/json
Array of objects
Array
id
required
string

Live's unique id

type
required
string

Will always return 'live'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

Array of objects or null

Array of products linked to the content

tags
Array of strings or null

Content's tags

startDate
string or null

Live's planned start date (if ommited, the live start date will be set to current time)

rtmpUrl
string

Live's RTMP URL to send your live stream to

streamKey
string

Live's stream key to authenticate your live stream

state
string or null

Live currentstate (not_started, started or finished)

isFinished
boolean or null

Boolean to indicate if the live is finished

Response samples

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

Create a live

Authorizations:
(ApiKeyAppId)
Request Body schema:
name
required
string

Content's name

description
string or null

Content's description

thumbnail
string or null <binary>

Content main thumbnail binary

seller_id
string or null

Seller id to link the content to

tags
Array of strings or null

Content's tags

product_ids
Array of strings or null

Array of product ids to link the content to. If you also add a seller_id, the product ids needs to belongs to the seller

start_date
required
string

Live planned start date (ISO 8601 format)

Responses

Response Schema: application/json
object
id
required
string

Live's unique id

type
required
string

Will always return 'live'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

id
required
string

Seller's unique id

type
required
string

seller

object
Array of objects or null

Array of products linked to the content

Array
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
tags
Array of strings or null

Content's tags

startDate
string or null

Live's planned start date (if ommited, the live start date will be set to current time)

rtmpUrl
string

Live's RTMP URL to send your live stream to

streamKey
string

Live's stream key to authenticate your live stream

state
string or null

Live currentstate (not_started, started or finished)

isFinished
boolean or null

Boolean to indicate if the live is finished

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "thumbnail": "string",
  • "seller_id": "string",
  • "tags": [
    ],
  • "product_ids": [
    ],
  • "start_date": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a live

Get one live

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of live

Responses

Response Schema: application/json
object
id
required
string

Live's unique id

type
required
string

Will always return 'live'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

id
required
string

Seller's unique id

type
required
string

seller

object
Array of objects or null

Array of products linked to the content

Array
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
tags
Array of strings or null

Content's tags

startDate
string or null

Live's planned start date (if ommited, the live start date will be set to current time)

rtmpUrl
string

Live's RTMP URL to send your live stream to

streamKey
string

Live's stream key to authenticate your live stream

state
string or null

Live currentstate (not_started, started or finished)

isFinished
boolean or null

Boolean to indicate if the live is finished

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a live

Update one live

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of live

Request Body schema:
name
required
string

Content's name

description
string or null

Content's description

thumbnail
string or null <binary>

Content main thumbnail binary

seller_id
string or null

Seller id to link the content to

tags
Array of strings or null

Content's tags

product_ids
Array of strings or null

Array of product ids to link the content to. If you also add a seller_id, the product ids needs to belongs to the seller

start_date
required
string

Live planned start date (ISO 8601 format)

Responses

Response Schema: application/json
object
id
required
string

Live's unique id

type
required
string

Will always return 'live'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

id
required
string

Seller's unique id

type
required
string

seller

object
Array of objects or null

Array of products linked to the content

Array
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
tags
Array of strings or null

Content's tags

startDate
string or null

Live's planned start date (if ommited, the live start date will be set to current time)

rtmpUrl
string

Live's RTMP URL to send your live stream to

streamKey
string

Live's stream key to authenticate your live stream

state
string or null

Live currentstate (not_started, started or finished)

isFinished
boolean or null

Boolean to indicate if the live is finished

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "thumbnail": "string",
  • "seller_id": "string",
  • "tags": [
    ],
  • "product_ids": [
    ],
  • "start_date": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a live

Delete one live

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of live

Responses

Finish a live

Finish a live (will stop current stream, generate a replay and flag the live as finished)

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of live

Request Body schema: application/json
is_finished
required
boolean

Set to true to finish the live. Set to false to restart the live

end_date
required
string

Live end date (ISO 8601 format)

Responses

Response Schema: application/json
object
id
required
string

Live's unique id

type
required
string

Will always return 'live'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

id
required
string

Seller's unique id

type
required
string

seller

object
Array of objects or null

Array of products linked to the content

Array
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
tags
Array of strings or null

Content's tags

startDate
string or null

Live's planned start date (if ommited, the live start date will be set to current time)

rtmpUrl
string

Live's RTMP URL to send your live stream to

streamKey
string

Live's stream key to authenticate your live stream

state
string or null

Live currentstate (not_started, started or finished)

isFinished
boolean or null

Boolean to indicate if the live is finished

Request samples

Content type
application/json
{
  • "is_finished": true,
  • "end_date": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Videos

Caast videos are entities that are created to display video content on your website.
You first have to create the entity to receive an upload link available for one hour where you can upload your video to.
You can affiliate a seller and some products to a live with their unique ID and also tag it at your will.

List videos

Get all videos of your app. You can add some parameters to filter the response.
This endpoint will return a paginated response with 20 items per page (along with pagination related response headers).

Authorizations:
(ApiKeyAppId)
query Parameters
name
string

Search by video name

product_id
string

Search for video with products of given id

product_ref
string

Search for video with products that match given reference (SKU)

seller_id
string

Filter videos created by seller with given ID

seller_name
string

Search for videos created by seller with given name

seller_external_id
string

Filter videos created by seller with given external ID

tags
Array of arrays

Filter lives that match the given array of tags

page
integer

Page number (this endpoint returns 20 items per page)

Responses

Response Headers
Current-Page
any

The current page returned by the API

Page-Items
any

The total of elements return for this page

Total-Pages
any

The number of pages available for this query

Total-Count
any

The total of items for this query

Response Schema: application/json
Array of objects
Array
id
required
string

Video's unique id

type
required
string

Will always return 'video'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

Array of objects or null

Array of products linked to the content

tags
Array of strings or null

Content's tags

uploadUrl
string or null

A signed URL for a Google Cloud Storage bucket where you can upload your media. Your media will automatically be linked to the Caast video.
This upload link is provided at video creation and will only be valid for 1 hour.
If expired you can request another upload link with the dedicated endpoint

Google Cloud storage API is S3 compatible, so whatever tool you use to upload to either GCS or S3 should work.
For large video files, you can take advantage of things like resumable or multipart uploads.

Response samples

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

Create a video

Authorizations:
(ApiKeyAppId)
Request Body schema:
name
required
string

Content's name

description
string or null

Content's description

thumbnail
string or null <binary>

Content main thumbnail binary

seller_id
string or null

Seller id to link the content to

tags
Array of strings or null

Content's tags

product_ids
Array of strings or null

Array of product ids to link the content to. If you also add a seller_id, the product ids needs to belongs to the seller

Responses

Response Schema: application/json
object
id
required
string

Video's unique id

type
required
string

Will always return 'video'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

id
required
string

Seller's unique id

type
required
string

seller

object
Array of objects or null

Array of products linked to the content

Array
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
tags
Array of strings or null

Content's tags

uploadUrl
string or null

A signed URL for a Google Cloud Storage bucket where you can upload your media. Your media will automatically be linked to the Caast video.
This upload link is provided at video creation and will only be valid for 1 hour.
If expired you can request another upload link with the dedicated endpoint

Google Cloud storage API is S3 compatible, so whatever tool you use to upload to either GCS or S3 should work.
For large video files, you can take advantage of things like resumable or multipart uploads.

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "thumbnail": "string",
  • "seller_id": "string",
  • "tags": [
    ],
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a video

Get one video

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of video

Responses

Response Schema: application/json
object
id
required
string

Video's unique id

type
required
string

Will always return 'video'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

id
required
string

Seller's unique id

type
required
string

seller

object
Array of objects or null

Array of products linked to the content

Array
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
tags
Array of strings or null

Content's tags

uploadUrl
string or null

A signed URL for a Google Cloud Storage bucket where you can upload your media. Your media will automatically be linked to the Caast video.
This upload link is provided at video creation and will only be valid for 1 hour.
If expired you can request another upload link with the dedicated endpoint

Google Cloud storage API is S3 compatible, so whatever tool you use to upload to either GCS or S3 should work.
For large video files, you can take advantage of things like resumable or multipart uploads.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a video

Update one video

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of video

Request Body schema:
name
required
string

Content's name

description
string or null

Content's description

thumbnail
string or null <binary>

Content main thumbnail binary

seller_id
string or null

Seller id to link the content to

tags
Array of strings or null

Content's tags

product_ids
Array of strings or null

Array of product ids to link the content to. If you also add a seller_id, the product ids needs to belongs to the seller

Responses

Response Schema: application/json
object
id
required
string

Video's unique id

type
required
string

Will always return 'video'

object
name
required
string

Content's name

description
string or null

Content's description

thumbnailUrl
string or null

URL of content's main thumbnail image

object or null

Returns the seller linked to the content if any

id
required
string

Seller's unique id

type
required
string

seller

object
Array of objects or null

Array of products linked to the content

Array
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
tags
Array of strings or null

Content's tags

uploadUrl
string or null

A signed URL for a Google Cloud Storage bucket where you can upload your media. Your media will automatically be linked to the Caast video.
This upload link is provided at video creation and will only be valid for 1 hour.
If expired you can request another upload link with the dedicated endpoint

Google Cloud storage API is S3 compatible, so whatever tool you use to upload to either GCS or S3 should work.
For large video files, you can take advantage of things like resumable or multipart uploads.

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "thumbnail": "string",
  • "seller_id": "string",
  • "tags": [
    ],
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a video

Delete one video

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of video

Responses

Generate a new upload url

Generate a new upload url for a video

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of video

Responses

Response Schema: application/json
url
string

A signed URL for a Google Cloud Storage bucket where you can upload your media. Your media will automatically be linked to the Caast video.
This new link will only be valid for 1 hour.

Google Cloud storage API is S3 compatible, so whatever tool you use to upload to either GCS or S3 should work.
For large video files, you can take advantage of things like resumable or multipart uploads.

Response samples

Content type
application/json
{
  • "url": "string"
}

Sellers

Sellers are used to organize lives and products under a shop or a brand.
They only can use their own products on the videos and lives they create.

List sellers

Get all sellers of your app. You can add some parameters to filter the response.
This endpoint will return a paginated response with 20 items per page (along with pagination related response headers).

Authorizations:
(ApiKeyAppId)
query Parameters
name
string

Search by seller name

external_id
string

Search by external ID

page
integer

Page number (this endpoint returns 20 items per page)

Responses

Response Headers
Current-Page
any

The current page returned by the API

Page-Items
any

The total of elements return for this page

Total-Pages
any

The number of pages available for this query

Total-Count
any

The total of items for this query

Response Schema: application/json
Array of objects
Array
id
required
string

Seller's unique id

type
required
string

seller

object
name
required
string

Name of seller

url
string

Seller's external url

external_id
string

Use this external id parameter with a string to identify the seller in your system

moderated
required
boolean

A boolean value that indicates if the seller is moderated

Response samples

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

Create a seller

Authorizations:
(ApiKeyAppId)
Request Body schema: application/json
name
required
string

Name of seller

url
string

Seller's external url

external_id
required
string

Use this external id parameter with a string to identify the seller in your system

moderated
boolean

A boolean value that indicates if the seller is moderated

Responses

Response Schema: application/json
object
id
required
string

Seller's unique id

type
required
string

seller

object
name
required
string

Name of seller

url
string

Seller's external url

external_id
string

Use this external id parameter with a string to identify the seller in your system

moderated
required
boolean

A boolean value that indicates if the seller is moderated

Request samples

Content type
application/json
{
  • "name": "string",
  • "url": "string",
  • "external_id": "string",
  • "moderated": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a seller

Get one seller

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of seller

Responses

Response Schema: application/json
object
id
required
string

Seller's unique id

type
required
string

seller

object
name
required
string

Name of seller

url
string

Seller's external url

external_id
string

Use this external id parameter with a string to identify the seller in your system

moderated
required
boolean

A boolean value that indicates if the seller is moderated

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a seller

Update one seller

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of seller

Request Body schema: application/json
name
required
string

Name of seller

url
string

Seller's external url

external_id
required
string

Use this external id parameter with a string to identify the seller in your system

moderated
boolean

A boolean value that indicates if the seller is moderated

Responses

Response Schema: application/json
object
id
required
string

Seller's unique id

type
required
string

seller

object
name
required
string

Name of seller

url
string

Seller's external url

external_id
string

Use this external id parameter with a string to identify the seller in your system

moderated
required
boolean

A boolean value that indicates if the seller is moderated

Request samples

Content type
application/json
{
  • "name": "string",
  • "url": "string",
  • "external_id": "string",
  • "moderated": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a seller

Delete one seller

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of seller

Responses

Products

Products are displayed on lives and videos. They can be manually created or recovered by a preconfigured product flux
They are linked to your aplpication but they also can be linked to a specific seller.

List products

Get all products of your app. You can add some parameters to filter the response.
This endpoint will return a paginated response with 20 items per page (along with pagination related response headers).

Authorizations:
(ApiKeyAppId)
query Parameters
name
string

Search by product name

ref
string

Search by product reference (SKU)

seller_id
string

Search by seller ID

page
integer

Page number (this endpoint returns 20 items per page)

Responses

Response Headers
Current-Page
any

The current page returned by the API

Page-Items
any

The total of elements return for this page

Total-Pages
any

The number of pages available for this query

Total-Count
any

The total of items for this query

Response Schema: application/json
object
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
name
required
string

Product name

description
string or null

Product description

thumbnailUrl
string or null

URL of product's thumbnail image

ref
required
string

Product reference/SKU

ean
string or null

Product EAN

price
string or null

Product base price (without discount)

discountPrice
string or null

Product discounted price (if any)

inStock
boolean or null

Boolean to indicate if the product is in stock

url
string or null

Product page URL

complementaryInformations
object or null

Used to add custom complementary informations to your product

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a product

Product creation can either be fully manual or semi-automatic (based on a pre-defined product catalog).
If you wish to create a Caast product based on a product from your catalog, you can give only a ref as parameter of your query. If the ref match a product ref/SKU in your catalog, other parameters will be ignored and the product will only be created.
Otherwise we will try to create a product manually with the query parameters.

Another special parameter is seller_id. If given, the product catalog search by ref will be limited to products that belongs to the given seller in your catalog. If we can't find any matching product, we will link the manual product creation with the given seller.

Authorizations:
(ApiKeyAppId)
Request Body schema:
name
required
string

Product name

description
string or null

Product description

thumbnail
string or null <binary>

Product thumbnail binary

ref
string

Product reference/SKU

seller_id
string or null

Seller id to link the product to. Seller has to exist

ean
string or null

Product EAN

price
string or null

Product base price (without discount)

discount_price
string or null

Product discounted price (if any)

in_stock
boolean or null

Boolean to indicate if the product is in stock

url
string or null

Product page URL

complementary_informations
object or null

Used to add custom complementary informations to your product

Responses

Response Schema: application/json
object
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
name
required
string

Product name

description
string or null

Product description

thumbnailUrl
string or null

URL of product's thumbnail image

ref
required
string

Product reference/SKU

ean
string or null

Product EAN

price
string or null

Product base price (without discount)

discountPrice
string or null

Product discounted price (if any)

inStock
boolean or null

Boolean to indicate if the product is in stock

url
string or null

Product page URL

complementaryInformations
object or null

Used to add custom complementary informations to your product

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "thumbnail": "string",
  • "ref": "string",
  • "seller_id": "string",
  • "ean": "string",
  • "price": "string",
  • "discount_price": "string",
  • "in_stock": true,
  • "url": "string",
  • "complementary_informations": { }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a product

Get one product

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of product

Responses

Response Schema: application/json
object
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
name
required
string

Product name

description
string or null

Product description

thumbnailUrl
string or null

URL of product's thumbnail image

ref
required
string

Product reference/SKU

ean
string or null

Product EAN

price
string or null

Product base price (without discount)

discountPrice
string or null

Product discounted price (if any)

inStock
boolean or null

Boolean to indicate if the product is in stock

url
string or null

Product page URL

complementaryInformations
object or null

Used to add custom complementary informations to your product

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a product

Update one product

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of product

Request Body schema:
name
required
string

Product name

description
string or null

Product description

thumbnail
string or null <binary>

Product thumbnail binary

ref
string

Product reference/SKU

seller_id
string or null

Seller id to link the product to. Seller has to exist

ean
string or null

Product EAN

price
string or null

Product base price (without discount)

discount_price
string or null

Product discounted price (if any)

in_stock
boolean or null

Boolean to indicate if the product is in stock

url
string or null

Product page URL

complementary_informations
object or null

Used to add custom complementary informations to your product

Responses

Response Schema: application/json
object
id
required
string

Product's unique id

type
required
string

Will always return 'product'

object
name
required
string

Product name

description
string or null

Product description

thumbnailUrl
string or null

URL of product's thumbnail image

ref
required
string

Product reference/SKU

ean
string or null

Product EAN

price
string or null

Product base price (without discount)

discountPrice
string or null

Product discounted price (if any)

inStock
boolean or null

Boolean to indicate if the product is in stock

url
string or null

Product page URL

complementaryInformations
object or null

Used to add custom complementary informations to your product

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "thumbnail": "string",
  • "ref": "string",
  • "seller_id": "string",
  • "ean": "string",
  • "price": "string",
  • "discount_price": "string",
  • "in_stock": true,
  • "url": "string",
  • "complementary_informations": { }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a product

Delete one product

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of product

Responses

Get displayed data

Get data displayed related to a context given as parameter. Mimic the basic Caast script usage.

Authorizations:
(ApiKeyAppId)
query Parameters
product_ref
string

Will return data displayed for the given product ref. Mutually exclusive with url parameter

url
string

Will return data displayed on the given URL. Mutually exclusive with product ref parameter

Responses

Response Schema: application/json
Array
Any of
Array of objects
Array
id
required
string

Live's unique id

type
required
string

Will always return 'live'

object

Response samples

Content type
application/json
[
  • {
    }
]
Spacial ship