Introduction

The Bambuser API offers a simple HTTP-based interface for managing resources created on the video platform.

If you're looking for documentation regarding Live Video Shopping, see these pages.

To access the API you will need an API key. API keys can be created on the Developer page on the Bambuser video platform dashboard.

The API responds with standard HTTP status codes and JSON from all endpoints.

Authentication

API keys

A token based authentication scheme is enforced on all endpoints. Clients should authenticate themselves by supplying their API key in an Authorization HTTP header. API keys can have different scopes/permissions assigned at key creation.

To authorize, pass your API key as a Bearer token

curl -H "Authorization: Bearer KEY" ...

Versioning

Clients should indicate which version of an API endpoint they like to interact with using an Accept HTTP header. Each API endpoint has individual version history.

Indicate API version number in a header

curl -H "Accept: application/vnd.bambuser.v1+json"

Rate limiting

Requests from clients are rate limited to N requests in intervals of M seconds. Requests exceeding the limit will receive a response with the 429 Too Many Requests HTTP status code.

Applications

The Applications API allows users to create and manage application IDs for authenticating SDK/web/rtmp clients.

Create an application

Applications are configured with a set of permissions that determine what the application will be allowed to do. It is recommended to limit the permissions given according to the application's intended usage. I.e. a broadcast application should have only broadcast permission and a player application only viewing permission.

By default an application is given broadcasting, upload and viewing permission. Rtmp applications are given only broadcast permission by default.

Each application has a title and a platform. The title is mostly for your own convenience to easier keep track of different application IDs. Platform should be set according to client application. Mobile cross-platform (ionic/cordova, react native etc.) developers can set either 'android' or 'ios'.

HTTP Request

POST /applications

Request body parameters

name	type	description
title	string	Title for the application
platform	string	Application platform. Accepted values: 'android', 'ios', 'rtmp', 'web'
mayBroadcast	boolean	Broadcast permission, defaults to true
mayUpload	boolean	Upload media permission, defaults to true, false for rtmp
mayView	boolean	Viewing permission, defaults to true, false for rtmp

Example request: define a new Android application

curl --data '{"title": "Android broadcast client", "platform": "android", "mayView": false}' \
-XPOST "https://api.bambuser.com/applications" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 200 OK

{
  "id": "gFFb52RIm562bzYiKciznA",
  "title": "Android broadcast client",
  "environment": "08b22c31-3c77-a881-4cd5-68c7659e8ac3",
  "platform": "android",
  "created": 1579787113,
  "mayBroadcast": true,
  "mayUpload": true,
  "mayView": false
}

Get applications

Get all applications associated with the caller's environment.

HTTP Request

GET /applications

Example request

curl -XGET "https://api.bambuser.com/applications" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 200 OK

{
  "results": [
    {
      "id": "gFFb52RIm562bzYiKciznA",
      "title": "Android broadcast client",
      "environment": "08b22c31-3c77-a881-4cd5-68c7659e8ac3",
      "platform": "android",
      "created": 1579787113,
      "mayBroadcast": true,
      "mayUpload": true,
      "mayView": false
    },
    {
      "id": "yLDFz9a1Nl9PuZYRtj4yeg",
      "title": "webplayer client",
      "environment": "08b22c31-3c77-a881-4cd5-68c7659e8ac3",
      "platform": "web",
      "created": 1579787799,
      "mayBroadcast": false,
      "mayUpload": false,
      "mayView": true
    }
  ]
}

Get application by application ID

HTTP Request

GET /applications/:applicationId

Example request

curl -XGET "https://api.bambuser.com/applications/gFFb52RIm562bzYiKciznA" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 200 OK

{
  "id": "gFFb52RIm562bzYiKciznA",
  "title": "Android broadcast client",
  "environment": "08b22c31-3c77-a881-4cd5-68c7659e8ac3",
  "platform": "android",
  "created": 1579787113,
  "mayBroadcast": true,
  "mayUpload": true,
  "mayView": false
}

Delete an application

HTTP Request

DELETE /applications/:applicationId

Example request

curl -XDELETE "https://api.bambuser.com/applications/gFFb52RIm562bzYiKciznA" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 204 No Content

Broadcasts

Get a list of broadcasts

Sorted by creation date, descendingly.

HTTP Request

GET /broadcasts

Filtration options

name	type	description
after	string	Pagination cursor (use the value of the `next` property of an earlier request).
byAuthors	string	Include broadcasts from specific authors only (comma separated list).
createdAfter	integer	Unix timestamp in seconds.
createdBefore	integer	Unix timestamp in seconds.
hasAllTags	string	Find broadcasts having a specific set of tags (comma separated list, case insensitive).
hasAnyTags	string	Find broadcasts having at least one of a set of tags (comma separated list, case insensitive).
limit	integer	Override the default size of the result set.
titleContains	string	Find broadcasts having a title containing a given string.
order	string	Set to `live` to sort live broadcasts first in the results.

Example request

curl -XGET "https://api.bambuser.com/broadcasts?limit=2&titleContains=Test" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.bambuser.v1+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 200 OK

{
  "results": [
    {
      "author": "Sveninge Bambuser",
      "clientVersion": "0.9.24 libbambuser com.bambuser.myapp 1.1.3",
      "created": 1466083683,
      "customData": "{\"foo\":\"bar\"}",
      "height": 480,
      "id": "3ea88ab0-7f98-11e6-9b48-fbbdc08b78b9",
      "ingestChannel": "04e32ddd-112d-7f2e-ef9a-2c8dbf104471",
      "lat": 59.345258,
      "length": 411,
      "lon": 18.093741,
      "positionAccuracy": 75,
      "positionType": "network",
      "preview": "https://archive.bambuser.com/3ea88ab0-7f98-11e6-9b48-fbbdc08b78b9.jpg",
      "resourceUri": "https://cdn.bambuser.net/broadcasts/3ea88ab0-7f98-11e6-9b48-fbbdc08b78b9?da_signature_method=HMAC-SHA256&da_id=62e69c26-1c9b-4832-223a-42a5b9d87894&da_timestamp=1474482206&da_static=1&da_ttl=0&da_signature=91143d7410b18a92bfd6d0c2981aa6acb733208d2b6e86d7114e9aea01585c81",
      "tags": [
        {
          "text": "test"
        }
      ],
      "title": "Test broadcast foo",
      "type": "archived",
      "width": 720
    },
    {
      "author": "Sveninge Bambuser",
      "clientVersion": "0.9.24 libbambuser com.bambuser.myapp 1.1.3",
      "created": 1454496122,
      "customData": "{\"foo\":\"bar\"}",
      "height": 480,
      "id": "42580552-7f98-11e6-9b48-fbbdc08b78b9",
      "ingestChannel": "04e32ddd-112d-7f2e-ef9a-2c8dbf104471",
      "lat": -14.235004,
      "length": 19986084,
      "lon": -51.92528,
      "positionAccuracy": 3195790,
      "positionType": "country",
      "preview": "https://archive.bambuser.com/42580552-7f98-11e6-9b48-fbbdc08b78b9.jpg",
      "resourceUri": "https://cdn.bambuser.net/broadcasts/42580552-7f98-11e6-9b48-fbbdc08b78b9?da_signature_method=HMAC-SHA256&da_id=62e69c26-1c9b-4832-223a-42a5b9d87894&da_timestamp=1474482206&da_static=1&da_ttl=0&da_signature=5a87a6484f131c43149f8ee27065928fd7e9500b65e98bcd2e6a206b2d93e632",
      "tags": [],
      "title": "Test broadcast bar",
      "type": "live",
      "width": 640
    }
  ],
  "next": "eyJicm9hZGNhc3Rfb3JkZXJfaWRfYWZ0ZXIiOiIxMzYxMTkyMjkyXzkwMDk1IiwiaW1hZ2VfY3JlYXRlZF9hZnRlciI6IjEzNjExOTIyOTIifQ=="
}

Get a single broadcast

HTTP Request

GET /broadcasts/:broadcastId

Example request

curl -XGET "https://api.bambuser.com/broadcasts/48f12975-7f98-11e6-9b48-fbbdc08b78b9" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.bambuser.v1+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 200 OK

{
  "author": "Sveninge Bambuser",
  "clientVersion": "0.9.24 libbambuser com.bambuser.myapp 1.1.3",
  "created": 1474082338,
  "customData": "{\"foo\":\"bar\"}",
  "height": 270,
  "id": "48f12975-7f98-11e6-9b48-fbbdc08b78b9",
  "ingestChannel": "04e32ddd-112d-7f2e-ef9a-2c8dbf104471",
  "lat": 43.09025,
  "length": 149,
  "lon": -97.712892,
  "positionAccuracy": 3800200,
  "positionType": "country",
  "positionType": "country",
  "preview": "https://archive.bambuser.com/48f12975-7f98-11e6-9b48-fbbdc08b78b9.jpg",
  "resourceUri": "https://cdn.bambuser.net/broadcasts/48f12975-7f98-11e6-9b48-fbbdc08b78b9?da_signature_method=HMAC-SHA256&da_id=62e69c26-1c9b-4832-223a-42a5b9d87894&da_timestamp=1474482171&da_static=1&da_ttl=0&da_signature=09157a24876ee9a1c73e77e07e252d562763bed8ec043dc207226ade0a754616",
  "tags": [],
  "title": "Test broadcast",
  "type": "archived",
  "width": 480
}

Update a broadcast's metadata

The API PATCH call has higher priority than the client the broadcast is originating from. Once a metadata property has been changed through the API the broadcast client can no longer update it.

Request body parameters

name	type	description
author	string	The author of the broadcast.
title	string	The title of the broadcast.

HTTP Request

PATCH /broadcasts/:broadcastId

Example request

curl --data '{"title": "New title"}' -X PATCH "https://api.bambuser.com/broadcasts/48f12975-7f98-11e6-9b48-fbbdc08b78b9" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.bambuser.v1+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 204 No Content

Remove a broadcast

HTTP Request

DELETE /broadcasts/:broadcastId

Example request

curl -XDELETE "https://api.bambuser.com/broadcasts/48f12975-7f98-11e6-9b48-fbbdc08b78b9" \
  -H "Accept: application/vnd.bambuser.v1+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 204 No Content

Get download link for a single broadcast

Using v2 of this method, you can check availability and get download links for different formats for an archived broadcast.

Some formats are not available by default. If the status of a format in the response is not-available, the format may be produced upon request. See Request download format.

When a new format has been requested, the response status property may transition through stages such as waiting and processing before reaching ok. You may also observe the progress property for time-consuming video format conversions. Finished files appear in the response url property with status ok.

HTTP Request

GET /broadcasts/:broadcastId/downloads

Example request

curl -XGET "https://api.bambuser.com/broadcasts/45f12975-7f98-11e6-9a48-fbbdc08b78b9/downloads" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.bambuser.v2+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example initial response

HTTP 200 OK

[
  {
    "url":"https://eu-west-1-s3archive.bambuser.io/xyz/046a35d7-a361-49d1-ab25-e30805a04417.flv",
    "format":"flv-h264",
    "status":"ok",
    "progress":100
  },
  {
    "url":null,
    "format":"mp4-h264",
    "status":"not-available",
    "progress":null
  }
]

Example later response

HTTP 200 OK

[
  {
    "url":"https://eu-west-1-s3archive.bambuser.io/xyz/fcfc9939-64ae-4c34-a01c-11a29132482b.flv",
    "format":"flv-h264",
    "status":"ok",
    "progress":100
  },
  {
    "url":"https://eu-west-1-s3archive.bambuser.io/xyz/bbdd0a33-5a64-49e1-8b00-667efcfeeded.mp4",
    "format":"mp4-h264",
    "status":"ok",
    "progress":100
  }
]

Request download format for a broadcast

V2 of this method can be used to trigger production of alternative download formats for a broadcast. Conversion of long broadcasts may take time. Use the response status and progress properties to track progress. The finished file will appear in the response url property when status is ok.

The request should be JSON-formatted and contain a format parameter. The only currently supported format is mp4-h264.

HTTP Request

POST /broadcasts/:broadcastId/downloads

Example request

curl --data '{"format": "mp4-h264"}' \
  -XPOST "https://api.bambuser.com/broadcasts/48a12975-7f98-11e6-9b48-fbbdc08b78b9/downloads" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.bambuser.v2+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example initial response

HTTP 200 OK

{
  "url":null,
  "format":"mp4-h264",
  "status":"waiting",
  "progress":0
}

Example final response

HTTP 200 OK

{
  "url":"https://eu-west-1-s3archive.bambuser.io/xyz/4701c04f-c9a0-4c48-86fc-0b402dd3e732.mp4",
  "format":"mp4-h264",
  "status":"ok",
  "progress":100
}

Create a clip from a broadcast

Using this method you can create clips from existing broadcasts (live or on-demand).

Clips will be represented as new broadcasts and will therefore be listed among your broadcasts and trigger webhooks accordingly.

This method is non-destructive, the original broadcast from which a clip is made will remain untouched.

HTTP Request

POST /broadcasts

Example request: Extract a clip from 30 seconds into the broadcast to 120 seconds into the broadcast (the result will be around 90 seconds).

curl -XPOST "https://api.bambuser.com/broadcasts" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{"source": {"broadcastId": "ba703517-a205-1149-724d-687d5dd78bcf", "start": 30, "end": 120}}'

Request body parameters

The request should be JSON-formatted and contain a source object with the following parameters:

name	type	description
source	object
source.broadcastId	string	Id of the original broadcast.
source.start	number	When the segment should start (in seconds into the broadcast).
source.end	number	When the segment should end (in seconds into the broadcast).

Response

Example response

202 OK

{
  "status": "processing",
  "newBroadcastId": "39cde3b3-fa1d-4e4c-d06b-2205ca9f89ce"
}

The value in newBroadcastId contains the id of the broadcast produced when the clipping is complete. Use this id and match it against your incoming webhook messages to get notified when the clip is ready. You can, of course, also get details about the new broadcast via the get broadcasts metadata method.

The value in status can be either waiting, processing or ok. A clip in the waiting state is in a queue waiting to be assigned for processing. A clip in the processing state is currently being generated. As you only need to call this method once per clip, you'll likely only see the waiting state. If you call the method multiple times with identical parameters, you can see the clip transition to processing and ok.

Example response

202 Accepted

{
  "status": "waiting",
  "newBroadcastId": "39cde3b3-fa1d-4e4c-d06b-2205ca9f89ce"
}

Please note The GET /broadcasts/:broadcastId endpoint will respond with a 404 until the clip is ready. Generating clips too close to realtime can result in an error or a truncated result.

Tag a broadcast

Using this method you can add tags to broadcasts. Tags can be used both when filtering broadcasts in GET /broadcasts and when marking important segments of a broadcast.

HTTP Request

POST /broadcasts/:broadcastId/tags

Request body parameters

The request should be JSON-formatted.

name	type	description
text	string	The text of the tag.
positionStart	integer	Optional start time of this tag in the broadcast, in seconds from broadcast start.
positionEnd	integer	Optional end time of this tag in the broadcast, in seconds since broadcast start.

Example request: Add the tag cats to broadcast id abcd1234.

curl -XPOST "https://api.bambuser.com/broadcasts/abcd1234/tags" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{"text": "cats"}'

Response

Example response

201 Created

{
  "text": "cats",
  "id": 12345
}

The response contains an id that identifies this tag on this broadcast. This is needed when removing a specific tag, see Remove a tag.

Example request: Add the tag kittens at time 100 to 120 to broadcast id abcd1234.

curl -XPOST "https://api.bambuser.com/broadcasts/abcd1234/tags" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{"text": "kittens", "positionStart": 100, "positionEnd": 120}'

Response

Example response

201 Created

{
  "text": "kittens",
  "id": 12346,
  "positionStart": 100,
  "positionEnd": 120
}

Remove a tag from a broadcast

Using this method you can remove a tag from a broadcast.

HTTP Request

DELETE /broadcasts/:broadcastId/tags/:tagId

Example request: Remove tag id 12345 from broadcast id abcd1234.

curl -XDELETE "https://api.bambuser.com/broadcasts/abcd1234/tags/12345" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example response

204 No content

Remove all tags from a broadcast

Using this method you can remove all tags from a broadcast.

HTTP Request

DELETE /broadcasts/:broadcastId/tags

Example request: Remove all tags from broadcast id abcd1234.

curl -XDELETE "https://api.bambuser.com/broadcasts/abcd1234/tags" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example response

204 No content

Stop a live broadcast remotely

Using this method you can force stop an incoming live broadcast.

HTTP Request

PUT /broadcasts/:broadcastId/stop

Example request: stop broadcast id abcd1234.

curl -XPUT "https://api.bambuser.com/broadcasts/abcd1234/stop" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>"

Example response

204 No content

Images

Get a list of images

The image metadata API can be used to fetch updated information about a single image, or get a paginated list of all images, optionally using filtration. Results are sorted by creation date, descendingly.

HTTP Request

GET /images

Filtration options

name	type	description
after	string	Pagination cursor (use the value of the `next` property of an earlier request).
byAuthors	string	Include images from specific authors only (comma separated list).
createdAfter	integer	Unix timestamp in seconds.
createdBefore	integer	Unix timestamp in seconds.
hasAllTags	string	Find images having a specific set of tags (comma separated list, case insensitive).
hasAnyTags	string	Find images having at least one of a set of tags (comma separated list, case insensitive).
limit	integer	Override the default size of the result set.
titleContains	string	Find images having a title containing a given string.

curl -XGET "https://api.bambuser.com/images?limit=2" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.bambuser.v1+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 200 OK

{
  "results": [
    {
      "added": 1466124181,
      "author": "Sveninge Bambuser",
      "created": 1466083683,
      "derivatives": [
        {
          "url": "https://img.bambuser.com/8730cce0-992a-464c-149b-ea0c7c3b6b20.jpg",
          "width": 250,
          "height": 140,
          "title": "small"
        },
        {
          "url": "https://img.bambuser.com/8517e6a1-0fc5-2608-afd2-d9aed2f11a24.jpg",
          "width": 750,
          "height": 421,
          "title": "medium"
        },
        {
          "url": "https://img.bambuser.com/77202228-cb18-c65c-9a79-458c7ba89cae.jpg",
          "width": 1000,
          "height": 562,
          "title": "large"
        }
      ],
      "height": 2448,
      "id": "4ee15d99-826f-11e6-b000-0811968eca44",
      "ingestChannel": "04e32ddd-112d-7f2e-ef9a-2c8dbf104471",
      "lat": 0.04746,
      "lon": 115.13609,
      "positionAccuracy": 75,
      "positionType": "network",
      "originalFilename": "IMG-0002.jpg",
      "tags": [
        {
          "text": "test"
        }
      ],
      "title": "Oh look!",
      "url": "https://archive.bambuser.com/4ee15d99-826f-11e6-b000-0811968eca44.jpg",
      "width": 3264
    },
    {
      "added": "1454497888",
      "author": "Sveninge Bambuser",
      "created": 1454496122,
      "height": 2448,
      "id": "56c0e5e9-826f-11e6-b000-0811968eca44",
      "ingestChannel": "04e32ddd-112d-7f2e-ef9a-2c8dbf104471",
      "lat": -2.85749,
      "lon": 15.57654,
      "positionAccuracy": 1500,
      "positionType": "network",
      "originalFilename": "IMG-0001.jpg",
      "tags": [],
      "title": "Elephants!",
      "url": "https://archive.bambuser.com/56c0e5e9-826f-11e6-b000-0811968eca44.jpg",
      "width": 3264
    }
  ],
  "next": "eyJicm9hZGNhc3Rfb3JkZXJfaWRfYWZ0ZXIiOiIxMzYxMTkyMjkyXzkwMDk1IiwiaW1hZ2VfY3JlYXRlZF9hZnRlciI6IjEzNjExOTIyOTIifQ=="
}

Get a single image

HTTP Request

GET /images/:imageId

Example request

curl -XGET "https://api.bambuser.com/images/4ee15d99-826f-11e6-b000-0811968eca44" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.bambuser.v1+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example request

Example response

HTTP 200 OK

{
  "added": 1466124181,
  "author": "Sveninge Bambuser",
  "created": 1466083683,
  "derivatives": [
    {
      "url": "https://img.bambuser.com/8730cce0-992a-464c-149b-ea0c7c3b6b20.jpg",
      "width": 250,
      "height": 140,
      "title": "small"
    },
    {
      "url": "https://img.bambuser.com/8517e6a1-0fc5-2608-afd2-d9aed2f11a24.jpg",
      "width": 750,
      "height": 421,
      "title": "medium"
    },
    {
      "url": "https://img.bambuser.com/77202228-cb18-c65c-9a79-458c7ba89cae.jpg",
      "width": 1000,
      "height": 562,
      "title": "large"
    }
  ],
  "height": 2448,
  "id": "4ee15d99-826f-11e6-b000-0811968eca44",
  "ingestChannel": "04e32ddd-112d-7f2e-ef9a-2c8dbf104471",
  "lat": 0.04746,
  "lon": 115.13609,
  "positionAccuracy": 75,
  "positionType": "network",
  "originalFilename": "IMG-0002.jpg",
  "tags": [
    {
      "text": "test"
    }
  ],
  "title": "Oh look!",
  "url": "https://archive.bambuser.com/4ee15d99-826f-11e6-b000-0811968eca44.jpg",
  "width": 3264
}

Remove an image

HTTP Request

DELETE /images/:imageId

Example request

curl -XDELETE "https://api.bambuser.com/images/08770d65-827b-11e6-b000-0811968eca44" \
  -H "Accept: application/vnd.bambuser.v1+json" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Example response

HTTP 204 No Content

Uploading media

In some apps it might be desirable to ingest pre-recorded video or images.

The SDK bundles for Android and iOS contain a working example of how to upload a file to Bambuser, using the protocol detailed below.

Acquiring an upload ticket

Before uploading your video or image file, an upload ticket must be acquired from the https://cdn.bambuser.net/uploadTickets endpoint.

HTTP Request

POST /uploadTickets

Example ticket request

curl \
  -i \
  -X POST \
  -H "Accept: application/vnd.bambuser.cdn.v1+json" \
  -H "X-Bambuser-ApplicationId: GFZalqkR5iyZcIgaolQmA" \
  -H "X-Bambuser-ClientVersion: com.skynet.skyapp 1.0" \
  -H "X-Bambuser-ClientPlatform: curl x64" \
  -d 'type=video' \
  -d 'filename=video.mp4' \
  "https://cdn.bambuser.net/uploadTickets"

Required ticket request parameters

name	type	description
type	string	must be either "image" or "video"
filename	string	The original filename. The file extension must be in the server's whitelist of common image and video file types

Optional ticket request parameters

name	type	description
author	string	Can be used to identify an individual end-user in a sandbox or production environment
title	string	Can be used to encourage end-users to provide context in text form
custom_data	string	Arbitrary data stored along with the file for the customer's purposes. Max 1KB per uploaded file (soft limit)
created	integer	Unix timestamp in seconds
device_model	string	A string identifying the platform, manufacturer and model
client_version	string	Your app's name and build version
platform	string	Device platform Example: "Android", "iOS"
platform_version	string	Version string related to the device platform
manufacturer	string	Device manufacturer Example: "Samsung", "HTC", "Apple"
lat	number	Latitude, as a decimal number
lon	number	Longitude, as a decimal number
position_accuracy	string	Position accuracy in meters

Required request headers

"Accept: application/vnd.bambuser.cdn.v1+json" To specify which version of the API we adhere to
"X-Bambuser-ApplicationId: GFZalqkR5iyZcIgaolQmA" applicationId used to authenticate your application
"X-Bambuser-ClientVersion: com.skynet.skyapp 1.0" Should correspond to the version of your application
"X-Bambuser-ClientPlatform: iPhone1,0" Should correspond to model or platform used

Response

The response includes an URL which you should upload your file to.

Example ticket response

200 OK

{
  "upload_url": "https://vupload01.bambuser.com/file/0b68d2c2b2f54a9d89aa9ed420675c31",
  "id": "0b68d2c2b2f54a9d89aa9ed420675c31",
  "created": 1477659999,
  "ttl": 180
}

Uploading a video or image file

Uploading your file will be done to the upload URL provided to you in the ticket response. Note that the upload ticket will expire after the ttl value in seconds. You can upload your file as a PUT request.

Example upload using PUT

Assuming the file you want to upload is called "video.mp4", this is what your PUT upload request should look like using the upload ticket aquired using the steps above.

Example request

curl \
  -i \
  -X PUT \
  --upload-file video.mp4 \
  "https://vupload01.bambuser.com/file/0b68d2c2b2f54a9d89aa9ed420675c31"

Example upload response

HTTP/1.1 100 Continue

HTTP/1.1 200 OK

Stream forwarding

The Stream Forwarding API allows users to stream Bambuser broadcasts to remote destinations using RTMP.

Start a new pipeline

A pipeline can have one input (read: a broadcast) and one or multiple outputs (read: RTMP endpoints). At this point, no input or outputs exists yet.

HTTP Request

POST /pipelines

Example response

HTTP 200 OK

{
  "id": "14db2e67-2e82-06de-99f8-fa884390c2e6"
}

List all pipelines associated with the caller's environment.

HTTP Request

GET /pipelines

Example response

HTTP 200 OK

{
  "results": {
    "14db2e67-2e82-06de-99f8-fa884390c2e6": {
      "started": 1525788937,
      "outputs": [
        {
          "started": 1525789116,
          "id": "3ee97f90-40b8-4791-99a0-85e6973964f5",
          "size": "1920x1080"
        }
      ]
    }
  }
}

Set the input broadcast for a pipeline.

HTTP Request

PATCH /pipelines/:pipelineId

Request body parameters

name	type	description
broadcastId	string	Id for the broadcast to be forwarded.
closeOnEnd	boolean	Close the pipeline after the input broadcast ends.
title	string	Title for the broadcast (optional).
seek	number	Time in the input broadcast at which forwarding will start, in seconds (optional). For use on archived broadcasts only.
end	number	Time in the input broadcast at which forwarding will end, in seconds (optional). For use on archived broadcasts only.

Example response

HTTP 204 No Content

Start an RTMP output from a pipeline to a remote destination

HTTP Request

POST /pipelines/:pipelineId/outputs

Returns a unique id for the new output.

Request body parameters

name	type	description
destination	string	Target server URL
rtmpStreamId	string	Stream key
resolution	string	Output resolution
framerate	integer	Output framerate

Example response

HTTP 200 OK

{
  "id": "3ee97f90-40b8-4791-99a0-85e6973964f5"
}

Stop a pipeline.

HTTP Request

DELETE /pipelines/:pipelineId

Example response

HTTP 204 No Content

Remove an output from a pipeline.

HTTP Request

DELETE /pipelines/:pipelineId/outputs/:outputId

Example response

HTTP 204 No Content

Misc

Create a Virtual Resource URI

This endpoint produces a signed Virtual Resource URI that can be used directly in a player.

By default, the Virtual Resource URI will resolve to the latest broadcast created inside the environment.

Using the optional parameters below, we can produce a Virtual Resource URI that resolves to the latest broadcast matching a set of requirements.

HTTP Request

POST /virtualResourceUri

Example request: Create a Virtual Resource URI that resolves to the latest broadcast tagged with both "foo" and "bar"

curl -XPOST "https://api.bambuser.com/virtualResourceUri" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{"hasAllTags": "foo,bar"}'

Request body parameters

name	type	description
byAuthors	string	Match broadcasts from specific authors only (comma separated list).
createdAfter	integer	Match broadcasts created after a certain time (unix timestamp in seconds).
createdBefore	integer	Match broadcasts created before a certain time (unix timestamp in seconds).
hasAllTags	string	Match broadcasts having a specific set of tags (comma separated list, case insensitive).
hasAnyTags	string	Match broadcasts having at least one of a set of tags (comma separated list, case insensitive).
titleContains	string	Match broadcasts having a title containing a given string.
order	string	Override the default order (descendingly by the resources' creation date). Set to 'live' to move all/any live broadcasts to the top of the result set, the rest are sorted by their creation date (desc).
ttl	integer	Specify how long (in seconds) the Virtual Resource URI should be usable.

Example response

HTTP 200 OK

{
  "resourceUri": "https://cdn.bambuser.net/groups/35333/broadcasts?has_all_tags=foo%2Cbar&da_ttl=3600&da_id=2545b8b1-3b42-11e9-a2ff-06f6cf6daabc&da_timestamp=1551349014&da_nonce=0.5480343287290147&da_signature_method=HMAC-SHA256&da_signature=d70c678645dea0545d0f60f13ba3d8239719a96727c06d50bebe97e13a776f11"
}

Create a web broadcaster embed URL

This endpoint produces a signed web broadcaster url that can be loaded in an iframe on your whitelisted domain(s) only.

Parameters passed to this method will be signed using your credentials. Any attempts to copy the embed code to another domain, or modify parameters, will be met with an error.

For more details about the broadcaster component, see our web broadcaster guide.

HTTP Request

POST /broadcasterEmbedUrl

Example request: Create a broadcaster embed URL that can only be embedded on the domain "example.com".

curl -XPOST "https://api.bambuser.com/broadcasterEmbedUrl" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.bambuser.v1+json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{"applicationId": "gFab78Ram512yNYicciznA", "domain": "example.com"}'

Request body parameters

name	type	description
applicationId	string	Mandatory. A web application id generated on the Developer page or using the application API.
domain	string	Mandatory. A comma-separated whitelist of domains, for example "example.com,production.example.com".
ttl	integer	Optional. Specifies how long (in seconds) the broadcaster embed should be valid. Minimum 3600. Default is unlimited.
externalControl	string	Optional. Specifies if the broadcaster embed should show an off the shelf UI and/or be controlled programmatically. Use `enforced` to enforce external control and hide the off-the-shelf UI. Use `disabled` to explicitly disable external programmatic control. Default is that both UI and external controls are enabled.

Example response

HTTP 200 OK

{
  "embedUrl": "https://dist.bambuser.net/broadcaster/?..."
}

API Reference

Introduction

Authentication

API keys

Versioning

Rate limiting

Applications

Create an application

HTTP Request

Request body parameters

Get applications

HTTP Request

Get application by application ID

HTTP Request

Delete an application

HTTP Request

Broadcasts

Get a list of broadcasts

HTTP Request

Filtration options

Get a single broadcast

HTTP Request

Update a broadcast's metadata

Request body parameters

HTTP Request

Remove a broadcast

HTTP Request

Get download link for a single broadcast

HTTP Request

Request download format for a broadcast

HTTP Request

Create a clip from a broadcast

HTTP Request

Request body parameters

Response

Tag a broadcast

HTTP Request

Request body parameters

Response

Response

Remove a tag from a broadcast

HTTP Request

Remove all tags from a broadcast

HTTP Request

Stop a live broadcast remotely

HTTP Request

Images

Get a list of images

HTTP Request

Get a single image

HTTP Request

Remove an image

HTTP Request

Uploading media

Acquiring an upload ticket

HTTP Request

Required ticket request parameters

Optional ticket request parameters

Required request headers

Response

Uploading a video or image file

Example upload using PUT

Stream forwarding

Start a new pipeline

HTTP Request

List all pipelines associated with the caller's environment.

HTTP Request

Set the input broadcast for a pipeline.

HTTP Request

Request body parameters

Start an RTMP output from a pipeline to a remote destination

HTTP Request

Request body parameters

Stop a pipeline.

HTTP Request

Remove an output from a pipeline.

HTTP Request

Misc

Create a Virtual Resource URI

HTTP Request