Uploads

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.

RequestDescription
POST /uploadsRequest a new upload authorization URL
GET /uploadsReturn the details of recent uploads
DELETE /uploads/:idDelete an upload reference

There is no PATCH /uploads/:id because no field can be edited.

POST /uploads

Request a temporary URL to upload a file to.

We may deny the request, for example if this ability is not enabled for your account, quotas have been hit or due to abuse. 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

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

{
"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": "2021-02-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-02-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:

GET /uploads

Return the details of recent uploads. Upload URLs are temporary and so we will automatically delete records of older ones.

Example request

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

Example response

{
"success": true,
"result": [
{
"id": "abcde12345abcde12345a",
"name": "example.mp4",
"size": 12345,
"key": "path/to/file.mp4",
"url": "",
"created_by": "abcde12345abcde1234a",
"created_time": "2021-02-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-02-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

Delete a reference to an upload. The uploaded file (if one was uploaded) is automatically deleted separately.

Example request

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

Example response

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