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 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

portrait_thumbnail
string or null <binary>

Content portrait 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

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "thumbnail": "string",
  • "portrait_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 samples

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

Update a live

Update one live. Cannot be used if specified live is shared to you by another application.

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

portrait_thumbnail
string or null <binary>

Content portrait 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

Request samples

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

Response samples

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

Delete a live

Delete one live. Cannot be used if specified live is shared to you by another application.

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). Cannot be used if specified live is shared to you by another application.

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. Cannot be used if specified content is shared to you by another application.

end_date
required
string

Live end date (ISO 8601 format)

Responses

Request samples

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

Response samples

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

Get live events

Get current events linked to this live. Only available on unfinished lives.

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of live

Responses

Response samples

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

Get live chat messages

Get latest chat messages linked to this live (limited to 30 messages). Only available on unfinished lives. You can also get the 30 messages that are following a given message UID as the last parameter.

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of live

Responses

Response samples

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

Get events timecodes

Get timecodes of various events linked to this live.

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of live

Responses

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 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

portrait_thumbnail
string or null <binary>

Content portrait 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

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "thumbnail": "string",
  • "portrait_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 samples

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

Update a video

Update one video. Cannot be used if specified video is shared to you by another application.

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

portrait_thumbnail
string or null <binary>

Content portrait 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

Request samples

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

Response samples

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

Delete a video

Delete one video. Cannot be used if specified video is shared to you by another application.

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of video

Responses

Generate a new upload url

Generate a new upload url for a video. Cannot be used if specified video is shared to you by another application.

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of video

Responses

Response samples

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

Get events timecodes

Get timecodes of various events linked to this video.

Authorizations:
(ApiKeyAppId)
path Parameters
id
required
string

ID of video

Responses

Response samples

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

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 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

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 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

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 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

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 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

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

Live Phone Reminders

Live Phone Reminders are used to send SMS reminders to your customers when a live is started. You can create a live phone reminder for a live or for all lives.

Create a live phone reminder

Create a live phone reminder. You need to provide the phone number and the optin to receive SMS. If you provide a live_id, it will create the phone reminder for the live.
This endpoint will return a 201 status code if phone is already registered or if the live phone reminder is created successfully.

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

Phone number

live_id
string or null

Live ID

optin
required
boolean

Optin to receive SMS

current_url
string or null

Current URL

orgin_referer
string or null

Origin Referer

Responses

Request samples

Content type
{
  • "phone": "string",
  • "live_id": "string",
  • "optin": true,
  • "current_url": "string",
  • "orgin_referer": "string"
}

Delete a live phone reminder

Delete one live phone reminder. You need to provide the phone number to delete. If you don't provide a live_id, it will delete the phone reminder for all lives.
This endpoint will return a 200 status code if the live phone reminder is deleted successfully.

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

Phone number

live_id
string or null

Live ID

Responses

Request samples

Content type
application/json
{
  • "phone": "string",
  • "live_id": "string"
}

Displays

Displays endpoints allow you to retrieve information about which products have display configurations (visible in lives or videos) and get the content displayed for a specific product or URL context.

Get displayed and removed product refs

Get all product refs that have a display configured (visible in at least one live or video) for the current website.

When called without a timestamp, returns all currently active product refs.
When called with a timestamp, returns only product refs that were activated or removed since that time.

This endpoint is useful for synchronizing product display states with external systems.

Authorizations:
(ApiKeyAppId)
query Parameters
timestamp
integer

Unix timestamp (in seconds). When provided, returns only changes since that time: activated refs (new displays) and removed refs (deleted displays).

Responses

Response samples

Content type
application/json
{
  • "activated": [
    ],
  • "removed": [
    ]
}

Get displayed data on page or item

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 samples

Content type
application/json
[
  • {
    }
]