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.
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",
      "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",
      "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",
  "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
}

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.

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

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

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