Navbar

API Reference

shell

Introduction

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

To access the API you will need an API key. API keys can be created on the Developer page on the Bambuser dashboard. If you don't already have an account, feel free to sign up for a trial.

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.

To authorize, pass your API key as a Bearer token

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

Versioning

Clients should indicate which version of the API they like to interact with using an Accept HTTP header.

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.

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.

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",
      "created": 1466083683,
      "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",
      "created": 1454496122,
      "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",
  "created": 1474082338,
  "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
}

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

Using this method, you can get a download link for an archived broadcast.

HTTP Request

GET /broadcasts/:broadcastId/downloads

Example request

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

Example response

HTTP 200 OK

{
  "url": "https://eu-west-1-archive.bambuser.io/archive/eu-west-1-abcdef/xyz/27103f58-f792-4605-9c40-887efa1d02f8.flv"
  "format": "FLV"
}

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.

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

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 either as a PUT or POST request.

Example upload using POST

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

Example request

curl \
  -i \
  -X POST \
  -F "file=@video.mp4" \
  "https://vupload01.bambuser.com/file/0b68d2c2b2f54a9d89aa9ed420675c31"

Example upload response

HTTP/1.1 100 Continue

HTTP/1.1 200 OK

Example upload using PUT

Assuming the file you want to upload is called "video.mp4", this is what your POST 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.

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