Grabyo's public API (1.0.0)

Download OpenAPI specification:

Welcome

The Grabyo Public API provides secure, programmatic access to Grabyo’s cloud-based video platform. Use it to list and retrieve campaigns, manage assets and creative sets, and manage live streams.

Configuration

The Grabyo API exclusively uses the HTTPS protocol.

The default domain is https://oapi.grabyo.com


OpenAPI Specification

Download the machine-readable specification: openapi.yaml — import it into tools such as Postman or Insomnia, or try requests interactively in Swagger UI.


Authentication

To work with the Grabyo API you will need to send your API key in the x-api-key HTTP header with every request, like so:

x-api-key: YOUR-API-KEY-HERE

Content Type

All requests and responses use JSON. Send Content-Type: application/json when a request body is present, and include Accept: application/json to specify the response format.


Errors

Standard HTTP status codes are used. Error bodies include a short message (for v1) or an error object with httpResponseStatusCode and errorMessage (for some legacy routes). Common cases include 401 (missing/invalid API key), 403 (forbidden), and 404 (not found).


Support

For credentials and assistance, contact help@grabyo.com.

campaigns

Everything about your campaigns and its associated clips

Get a list of campaigns

Returns a list of Grabyo campaigns set up for your organization.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Get a campaign by ID

Returns details for a single Grabyo campaign.

Authorizations:
ApiKeyAuth
path Parameters
campaignId
required
string
Example: campaign-abcde

Unique identifier of the campaign.

Responses

Response samples

Content type
application/json
{
  • "coverImage": "string",
  • "allowedCountries": [
    ],
  • "disallowedCountries": [
    ],
  • "campaignId": "string",
  • "name": "string",
  • "status": "string"
}

assets

Create and manage assets for your campaigns

Get a list of assets for a campaign

Returns a list of Grabyo assets in the specified campaign in descending date order.

Authorizations:
ApiKeyAuth
path Parameters
campaignId
required
string
Example: campaign-abcde

Unique identifier of the campaign.

query Parameters
offset
integer
Default: 0
Example: offset=20

Offset count indicating where to begin paginated results.

limit
integer
Default: 20
Example: limit=20

Maximum number of items to return.

sortOrder
string
Enum: "descending" "ascending"
Example: sortOrder=descending

Specifies the order in which results are sorted. Options are 'descending' for reverse chronological order and 'ascending' for chronological order.

Responses

Response samples

Content type
application/json
{}

Upload a new asset

Upload a new Grabyo asset via video file or URL. The file must be less than 5GB. Use the GET asset by ID endpoint to check job status. If uploading a video file, use the following steps: Phase 1: @post a 'filename' with the file extension included and 'phase':'init'. You will be returned an 'uploadId', 'uploadUrl' and 'uploadUrlExpiry'. Phase 2: @put your video file as binary data in the body of the request to the 'uploadUrl'. Be aware that once the expiration has passed this URL will be unusable. Phase 3: @post the 'uploadId' along with 'phase':'complete'. This will start processing your video.

Authorizations:
ApiKeyAuth
path Parameters
campaignId
required
string
Example: campaign-abcde

Unique identifier of the campaign.

Request Body schema: application/json
required
One of
phase
required
string
Value: "init"
filename
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "phase": "init",
  • "filename": "string"
}

Response samples

Content type
application/json
Example
{
  • "assetId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "creatorUserId": "string",
  • "title": "string",
  • "description": "string",
  • "status": "string",
  • "type": "clip",
  • "creativeSetId": "string",
  • "tags": [
    ],
  • "clip": {
    }
}

Get an asset by ID

Authorizations:
ApiKeyAuth
path Parameters
assetId
required
string
Example: asset-12345

Unique identifier of the asset.

campaignId
required
string
Example: campaign-abcde

Unique identifier of the campaign.

Responses

Response samples

Content type
application/json
Example
{}

Update an asset

Change the properties of an existing asset.

Authorizations:
ApiKeyAuth
path Parameters
assetId
required
string
Example: asset-12345

Unique identifier of the asset.

campaignId
required
string
Example: campaign-abcde

Unique identifier of the campaign.

Request Body schema: application/json
required
title
string
description
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Example
{}

Delete a campaign asset

Authorizations:
ApiKeyAuth
path Parameters
assetId
required
string
Example: asset-12345

Unique identifier of the asset.

campaignId
required
string
Example: campaign-abcde

Unique identifier of the campaign.

Responses

Response samples

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

streams

Access to your Grabyo Streams

Get a list of streams

Returns a list of Grabyo streams set up for your organization.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Get a stream by ID

Returns details for a single Grabyo stream.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

Responses

Response samples

Content type
application/json
{
  • "streamId": "string",
  • "displayName": "string",
  • "coverImage": "http://example.com",
  • "encodeSource": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "streamStatus": "online",
  • "streamType": "continuous"
}

Set the status of a stream

Returns details for a single Grabyo stream.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

streamStatus
required
string
Enum: "online" "offline"
Example: online

The desired status of the stream.

Responses

Response samples

Content type
application/json
{
  • "streamId": "string",
  • "displayName": "string",
  • "coverImage": "http://example.com",
  • "encodeSource": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "streamStatus": "online",
  • "streamType": "continuous"
}

Get a signed HLS playlist for a Stream

Returns a publically accessible signed HLS playlist

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

query Parameters
startTimestamp
required
number
Example: startTimestamp=1704067200000

The Start Timestamp in UNIX epoch milliseconds.

endTimestamp
number
Example: endTimestamp=1704153600000

The End Timestamp in UNIX epoch milliseconds.

urlExpiryTimestamp
required
number
Example: urlExpiryTimestamp=1704240000000

The signed playlist Expiry Timestamp in UNIX epoch milliseconds. (Must be less than 30 days in the future)

Responses

Response samples

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

Set the source of a stream

Returns the source for a single Grabyo stream.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

Request Body schema: application/json
source
required
string
skipSourceHealthcheck
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "source": "string",
  • "skipSourceHealthcheck": false
}

Response samples

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

markers

Create and manage markers for your streams

Search markers in a stream

Returns a list of markers for the given stream within the given time range.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

query Parameters
startTime
required
string <date-time>
Example: startTime=2023-01-01T00:00:00Z

Start time of the time range in RFC3339 format.

endTime
required
string <date-time>
Example: endTime=2023-01-01T23:59:59Z

End time of the time range in RFC3339 format.

name
string
Example: name=important-event

Name of the marker.

color
Array of strings (MarkerColor)
Items Enum: "blue" "cyan" "green" "yellow" "orange" "red"
Example: color=red&color=blue

Color of the marker.

Responses

Response samples

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

Create a new marker

Creates a new marker in the given stream.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

Request Body schema: application/json
name
string <= 70 characters

Name of the marker.

description
string <= 1000 characters

Description of the marker.

inPoint
string <date-time>

Absolute marker start, in RFC3339 format. Mutually exclusive with inPointMillisFromNow, and preferred over it. Combine with outPoint or durationMillis for a segment marker.

outPoint
string <date-time>

Absolute marker end, in RFC3339 format. Requires inPoint. Cannot be combined with durationMillis. Omit for a moment marker.

inPointMillisFromNow
integer <int64> [ -86400000 .. 86400000 ]

Marker start as a signed offset in milliseconds from the server's current time; negative for the past, positive for the future. Resolved when the request is processed, and therefore subject to network and processing delays — use inPoint whenever possible. Mutually exclusive with inPoint. Combine with durationMillis for a segment marker. Maximum ±24 hours.

durationMillis
integer <int64> [ 1 .. 86400000 ]

Marker length in milliseconds, measured from the resolved start point. Cannot be combined with outPoint. Omit for a moment marker. Maximum 24 hours.

color
string
Enum: "blue" "cyan" "green" "yellow" "orange" "red"

Color of the marker.

emoji
string

Emoji associated with the marker.

rating
integer <int64>

Marker rating.

collectionId
string

Collection identifier to associate with the marker.

applyCollectionOffset
boolean
Default: false

Whether collection offset should be applied to the marker in and out points.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "inPoint": "2019-08-24T14:15:22Z",
  • "outPoint": "2019-08-24T14:15:22Z",
  • "inPointMillisFromNow": -86400000,
  • "durationMillis": 1,
  • "color": "blue",
  • "emoji": "string",
  • "rating": 0,
  • "collectionId": "string",
  • "applyCollectionOffset": false
}

Response samples

Content type
application/json
{
  • "markerId": "string",
  • "name": "string",
  • "description": "string",
  • "inPoint": "2019-08-24T14:15:22Z",
  • "outPoint": "2019-08-24T14:15:22Z",
  • "color": "blue",
  • "emoji": "string",
  • "type": "string",
  • "collectionId": "string",
  • "creationTime": "2019-08-24T14:15:22Z",
  • "rating": 0,
  • "streamId": "string",
  • "tags": [
    ]
}

Get a marker

Returns the marker with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

markerId
required
string
Example: marker-12345

Unique identifier of the marker.

Responses

Response samples

Content type
application/json
{
  • "markerId": "string",
  • "name": "string",
  • "description": "string",
  • "inPoint": "2019-08-24T14:15:22Z",
  • "outPoint": "2019-08-24T14:15:22Z",
  • "color": "blue",
  • "emoji": "string",
  • "type": "string",
  • "collectionId": "string",
  • "creationTime": "2019-08-24T14:15:22Z",
  • "rating": 0,
  • "streamId": "string",
  • "tags": [
    ]
}

Update a marker

Updates the marker with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

markerId
required
string
Example: marker-12345

Unique identifier of the marker.

Request Body schema: application/json
name
string <= 70 characters

Name of the marker.

description
string <= 1000 characters

Description of the marker.

inPoint
string <date-time>

Marker in point in RFC3339 format.

outPoint
string <date-time>

Marker out point in RFC3339 format.

offsetMillis
integer <int64>

Marker offset in milliseconds.

tags
Array of strings

Marker tags.

color
string
Enum: "blue" "cyan" "green" "yellow" "orange" "red"

Color of the marker.

emoji
string

Emoji associated with the marker.

collectionId
string

Collection identifier to associate with the marker.

applyCollectionOffset
boolean

Whether collection offset should be applied to the marker in and out points.

rating
integer <int64>

Marker rating.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "inPoint": "2019-08-24T14:15:22Z",
  • "outPoint": "2019-08-24T14:15:22Z",
  • "offsetMillis": 0,
  • "tags": [
    ],
  • "color": "blue",
  • "emoji": "string",
  • "collectionId": "string",
  • "applyCollectionOffset": true,
  • "rating": 0
}

Response samples

Content type
application/json
{
  • "markerId": "string",
  • "name": "string",
  • "description": "string",
  • "inPoint": "2019-08-24T14:15:22Z",
  • "outPoint": "2019-08-24T14:15:22Z",
  • "color": "blue",
  • "emoji": "string",
  • "type": "string",
  • "collectionId": "string",
  • "creationTime": "2019-08-24T14:15:22Z",
  • "rating": 0,
  • "streamId": "string",
  • "tags": [
    ]
}

Delete a marker

Deletes the marker with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

markerId
required
string
Example: marker-12345

Unique identifier of the marker.

Responses

Response samples

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

Get all markers in a collection

Returns a list of all markers in the given collection.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

collectionId
required
string
Example: collection-12345

Unique identifier of the collection.

Responses

Response samples

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

Get all marker collections for a stream

Returns a list of marker collections for the given stream.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

Responses

Response samples

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

Create a new collection for markers in a stream

Creates a new collection to store markers in the given stream.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

Request Body schema: application/json
name
required
string

The name of the collection to create.

offsetDelta
number
Default: 0

The offset in milliseconds applied to each marker in the collection.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "offsetDelta": 0
}

Response samples

Content type
application/json
{
  • "collectionId": "string",
  • "name": "string",
  • "offsetMillis": 0
}

Get a marker collection

Returns the markers collection with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

collectionId
required
string
Example: collection-12345

Unique identifier of the collection.

Responses

Response samples

Content type
application/json
{
  • "collectionId": "string",
  • "name": "string",
  • "offsetMillis": 0
}

Update a marker collection

Updates the marker collection with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

collectionId
required
string
Example: collection-12345

Unique identifier of the collection.

Request Body schema: application/json
name
string

The updated name of the collection.

offsetDelta
number
Default: 0

The change in milliseconds to the current offset which will be applied to new markers in the collection. Use applyToAllMarkersInCollection to apply the change to all existing markers in the collection.

applyToAllMarkersInCollection
boolean
Default: false

Whether the updated offset should be applied to all existing markers in the collection.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "offsetDelta": 0,
  • "applyToAllMarkersInCollection": false
}

Response samples

Content type
application/json
{
  • "collectionId": "string",
  • "name": "string",
  • "offsetMillis": 0
}

Delete a marker collection and all markers in it

Deletes the marker collection and all markers in it.

Authorizations:
ApiKeyAuth
path Parameters
streamId
required
string
Example: stream-abcde

Unique identifier of the stream.

collectionId
required
string
Example: collection-12345

Unique identifier of the collection.

Responses

Response samples

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