Download OpenAPI specification:
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.
The Grabyo API exclusively uses the HTTPS protocol.
The default domain is https://oapi.grabyo.com
Download the machine-readable specification: openapi.yaml — import it into tools such as Postman or Insomnia, or try requests interactively in Swagger UI.
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
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.
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).
For credentials and assistance, contact help@grabyo.com.
Returns a list of Grabyo campaigns set up for your organization.
{- "data": [
- {
- "coverImage": "string",
- "allowedCountries": [
- "string"
], - "disallowedCountries": [
- "string"
], - "campaignId": "string",
- "name": "string",
- "status": "string"
}
], - "pagination": {
- "total": 0,
- "limit": 0,
- "offset": 0,
- "hasMore": true
}
}Returns details for a single Grabyo campaign.
| campaignId required | string Example: campaign-abcde Unique identifier of the campaign. |
{- "coverImage": "string",
- "allowedCountries": [
- "string"
], - "disallowedCountries": [
- "string"
], - "campaignId": "string",
- "name": "string",
- "status": "string"
}Returns a list of Grabyo assets in the specified campaign in descending date order.
| campaignId required | string Example: campaign-abcde Unique identifier of the campaign. |
| 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. |
{- "data": [
- {
- "assetId": "C9azq6unWpE",
- "createdAt": "2026-07-29T14:22:08.441Z",
- "creatorUserId": "nBIGqD38R2s",
- "title": "A video clip",
- "status": "complete",
- "type": "clip",
- "clip": {
- "fileName": "flexar-1080p-60fps_sbr.mp4",
- "durationMillis": 30017,
- "fileSizeBytes": 35747770,
- "aspectRatio": "16:9",
}
}, - {
- "assetId": "NyXafjWipMk",
- "createdAt": "2026-07-30T09:14:02.117Z",
- "creatorUserId": "nBIGqD38R2s",
- "title": "A still image",
- "status": "complete",
- "type": "image",
- "image": {
- "fileName": "CKDjZs2O_image.png",
- "fileSizeBytes": 3185647,
- "aspectRatio": "16:9",
}
}, - {
- "assetId": "C7Q6sFjhrYh",
- "createdAt": "2026-07-30T11:41:55.882Z",
- "creatorUserId": "nBIGqD38R2s",
- "title": "An animated gif",
- "status": "complete",
- "type": "gif",
- "gif": {
- "fileName": "hYa1VsXj_gif.gif",
- "durationMillis": 4772,
- "fileSizeBytes": 10727387,
- "aspectRatio": "16:9",
}
}
], - "pagination": {
- "total": 3,
- "limit": 25,
- "offset": 0,
- "hasMore": false
}
}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.
| campaignId required | string Example: campaign-abcde Unique identifier of the campaign. |
| phase required | string Value: "init" |
| filename required | string |
{- "phase": "init",
- "filename": "string"
}{- "assetId": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "creatorUserId": "string",
- "title": "string",
- "description": "string",
- "status": "string",
- "type": "clip",
- "creativeSetId": "string",
- "tags": [
- "string"
], - "clip": {
- "fileName": "string",
- "durationMillis": 0,
- "fileSizeBytes": 0,
- "aspectRatio": "string",
- "clipPresignedUrl": "string",
- "thumbnailPresignedUrl": "string"
}
}| assetId required | string Example: asset-12345 Unique identifier of the asset. |
| campaignId required | string Example: campaign-abcde Unique identifier of the campaign. |
{- "assetId": "C9azq6unWpE",
- "createdAt": "2026-07-29T14:22:08.441Z",
- "creatorUserId": "nBIGqD38R2s",
- "title": "A video clip",
- "status": "complete",
- "type": "clip",
- "clip": {
- "fileName": "flexar-1080p-60fps_sbr.mp4",
- "durationMillis": 30017,
- "fileSizeBytes": 35747770,
- "aspectRatio": "16:9",
}
}Change the properties of an existing asset.
| assetId required | string Example: asset-12345 Unique identifier of the asset. |
| campaignId required | string Example: campaign-abcde Unique identifier of the campaign. |
| title | string |
| description | string |
{- "title": "string",
- "description": "string"
}{- "assetId": "C9azq6unWpE",
- "createdAt": "2026-07-29T14:22:08.441Z",
- "creatorUserId": "nBIGqD38R2s",
- "title": "A video clip",
- "status": "complete",
- "type": "clip",
- "clip": {
- "fileName": "flexar-1080p-60fps_sbr.mp4",
- "durationMillis": 30017,
- "fileSizeBytes": 35747770,
- "aspectRatio": "16:9",
}
}| assetId required | string Example: asset-12345 Unique identifier of the asset. |
| campaignId required | string Example: campaign-abcde Unique identifier of the campaign. |
{- "error": {
- "httpResponseStatusCode": 0,
- "errorMessage": "string"
}
}Returns a list of Grabyo streams set up for your organization.
{- "data": [
- {
- "streamId": "string",
- "displayName": "string",
- "encodeSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "streamStatus": "online",
- "streamType": "continuous"
}
]
}Returns details for a single Grabyo stream.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
{- "streamId": "string",
- "displayName": "string",
- "encodeSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "streamStatus": "online",
- "streamType": "continuous"
}Returns details for a single Grabyo stream.
| 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. |
{- "streamId": "string",
- "displayName": "string",
- "encodeSource": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "streamStatus": "online",
- "streamType": "continuous"
}Returns a publically accessible signed HLS playlist
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| 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) |
{- "signedUrl": "string"
}Returns the source for a single Grabyo stream.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| source required | string |
| skipSourceHealthcheck | boolean Default: false |
{- "source": "string",
- "skipSourceHealthcheck": false
}{- "source": "string"
}Returns a list of markers for the given stream within the given time range.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| 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. |
{- "data": [
- {
- "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": [
- {
- "name": "string"
}
]
}
], - "pagination": {
- "total": 0,
- "limit": 0,
- "offset": 0,
- "hasMore": true
}
}Creates a new marker in the given stream.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| 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 |
| outPoint | string <date-time> Absolute marker end, in RFC3339 format. Requires |
| 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 |
| durationMillis | integer <int64> [ 1 .. 86400000 ] Marker length in milliseconds, measured from the resolved start point. Cannot be combined with |
| 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. |
{- "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
}{- "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": [
- {
- "name": "string"
}
]
}Returns the marker with the given ID.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| markerId required | string Example: marker-12345 Unique identifier of the marker. |
{- "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": [
- {
- "name": "string"
}
]
}Updates the marker with the given ID.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| markerId required | string Example: marker-12345 Unique identifier of the marker. |
| 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. |
{- "name": "string",
- "description": "string",
- "inPoint": "2019-08-24T14:15:22Z",
- "outPoint": "2019-08-24T14:15:22Z",
- "offsetMillis": 0,
- "tags": [
- "string"
], - "color": "blue",
- "emoji": "string",
- "collectionId": "string",
- "applyCollectionOffset": true,
- "rating": 0
}{- "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": [
- {
- "name": "string"
}
]
}Deletes the marker with the given ID.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| markerId required | string Example: marker-12345 Unique identifier of the marker. |
{- "error": {
- "httpResponseStatusCode": 0,
- "errorMessage": "string"
}
}Returns a list of all markers in the given collection.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| collectionId required | string Example: collection-12345 Unique identifier of the collection. |
{- "data": [
- {
- "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": [
- {
- "name": "string"
}
]
}
], - "pagination": {
- "total": 0,
- "limit": 0,
- "offset": 0,
- "hasMore": true
}
}Returns a list of marker collections for the given stream.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
{- "data": [
- {
- "collectionId": "string",
- "name": "string",
- "offsetMillis": 0
}
], - "pagination": {
- "total": 0,
- "limit": 0,
- "offset": 0,
- "hasMore": true
}
}Creates a new collection to store markers in the given stream.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| 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. |
{- "name": "string",
- "offsetDelta": 0
}{- "collectionId": "string",
- "name": "string",
- "offsetMillis": 0
}Returns the markers collection with the given ID.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| collectionId required | string Example: collection-12345 Unique identifier of the collection. |
{- "collectionId": "string",
- "name": "string",
- "offsetMillis": 0
}Updates the marker collection with the given ID.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| collectionId required | string Example: collection-12345 Unique identifier of the collection. |
| 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. |
{- "name": "string",
- "offsetDelta": 0,
- "applyToAllMarkersInCollection": false
}{- "collectionId": "string",
- "name": "string",
- "offsetMillis": 0
}Deletes the marker collection and all markers in it.
| streamId required | string Example: stream-abcde Unique identifier of the stream. |
| collectionId required | string Example: collection-12345 Unique identifier of the collection. |
{- "error": {
- "httpResponseStatusCode": 0,
- "errorMessage": "string"
}
}