Skip to content
On this page

Uploads

If you want to upload a file into our temporary storage to then use in a subsequent API request, you need to request a URL to upload that file to.

POST /uploads

NOTE

If this ability is not enabled for your account or quotas have been hit, the request may be denied. You will see the returned error code and message if so.

Required parameters

You must provide the file's name and size.

KeyTypeDescription
nameStringThe file's name
sizeNumberThe file's size

The name should have the appropriate extension to avoid issues later on. For example if you are uploading:

  • a video? Its name should end with .mp4, .mov, .mpg, .wmv, .mkv
  • a thumbnail image? Its name should end with .jpg
  • a captions/subtitles WebVTT track? Its name should end with .vtt

The size should be a number, in bytes. How to get that depends on your application but every language has a way to get a file's size. For example:

On a Mac/Linux, you can get that using stat -f%z example.jpg.

With PHP, you can get that using filesize("example.jpg")

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY"  \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"example.mp4", "size": 12345}' \
"https://api.vidbeo.com/v2/uploads"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "example.mp4",
    "size": 12345,
    "key": "path/to/file.mp4",
    "url": "https://example.com/path/to/file.mp4?...",
    "created_by": "abcde12345abcde1234a",
    "created_time": "2022-01-01T00:00:00.000Z",
    "updated_by": "abcde12345abcde12345a",
    "updated_time": "2022-01-01T00:00:00.000Z"
  },
  "links": null,
  "errors": []
}

The important fields are url and id:

The url is what you now upload your file to. It is only valid for a very short time.

The id will be used in your subsequent API request to reference that file.

How do I upload to that URL?

Do a PUT request to it, sending the binary data of the file in the body of the request.

How exactly that is done depends on your application. In our documentation we use the curl command line tool, so using that you would do:

curl -L -X PUT "THE-URL-GOES-HERE" --data-binary "@path/to/file.ext"

For example if you have an image called example.jpg in the same folder you are running the command from, you would do:

curl -L -X PUT "THE-URL-GOES-HERE" --data-binary "@example.jpg"

As another example, using the free Postman app/extension, the request type is PUT, the URL is of course the URL we provide, and then underneath make sure you have picked binary as the body (as shown below). Then select your file. And send the request:

Postman

Once the upload is complete, you send its id in your subsequent API request like vidbeo://uploads/abcde12345abcde12345. As:

  • the input in POST /videos
  • the url in POST /videos/:id/thumbnail
  • the url in POST /videos/:id/tracks

GET /uploads

Since upload URLs are temporary we will automatically delete records of older ones.

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/uploads"

Example response

json
{
    "success": true,
    "result": [
        {
          "id": "abcde12345abcde12345a",
          "name": "example.mp4",
          "size": 12345,
          "key": "path/to/file.mp4",
          "url": "",
          "created_by": "abcde12345abcde1234a",
          "created_time": "2022-01-01T00:00:00.000Z",
          "updated_by": "abcde12345abcde12345a",
          "updated_time": "2022-01-01T00:00:00.000Z"
        },
        ...
    ],
    "links": {},
    "errors": []
}

Optional parameters

NameTypeDefaultInformation
limitString25Maximum number to return
cursorString""Used to get the next page of results: if applicable we return this as part of the links.next URL

Response format

KeyTypeDescription
idStringThe unique identifier given to this upload
nameStringThe name of the uploaded file (e.g "example.mp4")
sizeNumberThe size of the uploaded file
keyStringThe generated path to the temporary file we will store
urlStringThe temporary authorization URL to upload your file to in a PUT request
created_byStringThe ID of the user who created it (if known)
created_timeStringThe date and time it was created
updated_byStringThe ID of the user who last modified it (if known)
updated_timeStringThe date and time it was last modified

DELETE /uploads/:id

Note: The uploaded file (if one was uploaded using the URL) is automatically deleted separately.

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/uploads/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {},
  "links": null,
  "errors": []
}