Search
Voog.com
Search
Voog.com

Assets

Assets are images used within the Site's content blocks, or other documents. The typical client workflow is as follows:

  • Create a new asset via a POST request to /assets. If the response is successful:
    • Upload the asset body to the returned upload_url.
    • Upon a successful upload, make a PUT request to /assets/:id/confirm.
  • Periodically poll all confirmed assets until their status is done. done image assets include the sizes array, specifying all generated variants of the original image. In order to not make a separate API request for every polled asset, combine these using a filter, e.g.: GET /assets?q.asset.id.$in=1,2,3.

Summary of asset endpoints

List all available assets for the current site

GET /assets

By default, this request returns a list of all assets for the current site (newer first).

Asset may be one of type: image, document or flash.

When asset type is image, an array of available sizes are included in the response as sizes. If processing has not completed (status: done), the sizes array may be empty.

When asset type is image or flash then width and height are provided in the response.

Possible statuses are:

  • created — The asset has been created, but its body has not been uploaded and a confirm request has not been received.
  • uploaded — A confirm request to signal that the client has uploaded the asset body has been received and the asset is awaiting processing.
  • in_progress — The asset is being processed.
  • done — Asset processing has completed successfully.
  • failed — Asset processing has failed.

Example response:

Status: 200 OK

[
  {
    "id": 2,
    "filename": "report.pdf",
    "content_type": "application/pdf",
    "size": 36657,
    "extension": "pdf",
    "status": "done",
    "type": "document",
    "created_at": "2014-02-04T14:37:41.000Z",
    "updated_at": "2014-02-04T14:37:41.000Z",
    "url": "http://helloworld.voog.co/admin/api/assets/2",
    "public_url": "http://media.voog.com/0000/0000/0001/files/report.pdf"
  }, {
    "id": 1,
    "filename": "Screen Shot 2014-01-28 at 10.53.26.png",
    "content_type": "image/png",
    "size": 5305339,
    "extension": "png",
    "type": "image",
    "status": "done",
    "created_at": "2014-02-04T10:55:28.000Z",
    "updated_at": "2014-02-04T10:55:30.000Z",
    "url": "http://helloworld.voog.co/admin/api/assets/1",
    "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26.png",
    "sizes": [
      {
        "thumbnail": "huge",
        "filename": "Screen Shot 2014-01-28 at 10.53.26_huge.png",
        "content_type": "image/png",
        "size": 211910,
        "width": 2048,
        "height": 1365,
        "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26_huge.png"
      },
      {
        "thumbnail": "large",
        "filename": "Screen Shot 2014-01-28 at 10.53.26_large.png",
        "content_type": "image/png",
        "size": 114420,
        "width": 1280,
        "height": 853,
        "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26_large.png"
      },
      {
        "thumbnail": "block",
        "filename": "Screen Shot 2014-01-28 at 10.53.26_block.png",
        "content_type": "image/png",
        "size": 31876,
        "width": 500,
        "height": 333,
        "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26_block.png"
      },
      {
        "thumbnail": "medium",
        "filename": "Screen Shot 2014-01-28 at 10.53.26_medium.jpg",
        "content_type": "image/jpeg",
        "size": 5904,
        "width": 150,
        "height": 100,
        "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26_medium.jpg"
      }
    ],
    "width": 5184,
    "height": 3456
  }
]

Parameters

  • per_page - elements per response (default: 50; maximum: 250).
  • page - requested page (default: 1).
  • media_set_id - media set id (eg 1). Returns only assets for requested media set.
  • name - filter assets by filename. Usage examples:
    • ?name=somename - returns all assets where filename begins with "somename" (e.g. "somename.jpg", "somename-for-gallery.jpg").
    • ?name=*somename - returns all assets where filename contains string "somename" (e.g. "file-somename.jpg", "somename-for-gallery.jpg").
    • ?name=.jpg - returns all assets where file extension is "jpg" (e.g. "file-somename.jpg", "somename-for-gallery.jpg").

Filter attributes

Read more about filters.

  • Object asset attributes: id, filename, content_type, size, created_at, updated_at.
  • Object media_set attributes: id, title, created_at, updated_at.

Create new asset

After new asset object is created, it response includes upload_url and confirm_url that is needed to complete a file upload.

After the file is successfully uploaded to given upload_url a request to confirm_url completes uploading process (see Asset confirmation).

POST /assets

Example data:

{
  "filename": "new_image.png",
  "content_type": "image/png",
  "size": 95708,
  "width": 880,
  "height": 550
}

Example response:

Status: 201 Created

{
  "id": 3,
  "filename": "new_image.png",
  "content_type": "image/png",
  "size": 95708,
  "extension": "png",
  "type": "image",
  "status": "created",
  "created_at": "2014-02-04T11:03:11.000Z",
  "updated_at": "2014-02-04T11:03:11.000Z",
  "url": "http://helloworld.voog.co/admin/api/assets/3",
  "upload_url": "http://media.voog.com/0000/0000/001/files/new_image.png?AWSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Expires=1391528261&Signature=IGPxxxxxxxx%2FdjkdjkJWjwjjwjw%3D",
  "confirm_url": "http://helloworld.voog.co/admin/api/assets/3/confirm",
  "width": 880,
  "height": 550
}

Parameters

Required parameters:

  • filename - unique filename (if file with same name exist then numbered suffix (e.g. "-1") is appended automatically to new file). (E.g. "my-new file.png")
  • size - file size in bytes (e.g. 95708).
  • content_type - content type for file (e.g. "image/jpeg").

Optional parameters:

  • height - height of the image in pixels (e.g. 720).
  • width - width of the image in pixels (e.g. 1280).

Confirm asset upload

PUT /assets/1/confirm

This request completes uploading process after new asset object is created and successfully uploaded to given upload_url.

Example request:

PUT http://helloworld.voog.co/admin/api/assets/3/confirm

Example response:

Status: 201 Created

{
  "id": 3,
  "filename": "new_image.png",
  "content_type": "image/png",
  "size": 95708,
  "extension": "png",
  "type": "image",
  "status": "uploaded",
  "created_at": "2014-02-04T11:03:11.000Z",
  "updated_at": "2014-02-04T11:04:01.000Z",
  "url": "http://helloworld.voog.co/admin/api/assets/3",
  "public_url": "http://media.voog.com/0000/0000/0001/photos/new_image.png",
  "sizes": [
    {
      "thumbnail": "block",
      "filename": "new_image_block.png",
      "content_type": "image/png",
      "size": 124204,
      "width": 500,
      "height": 344,
      "public_url": "http://media.voog.com/0000/0000/0001/photos/new_image_block.png"
    },
    {
      "thumbnail": "medium",
      "filename": "new_image_medium.jpg",
      "content_type": "image/jpeg",
      "size": 4887,
      "width": 150,
      "height": 103,
      "public_url": "http://media.voog.com/0000/0000/0001/photos/new_image_medium.jpg"
    }
  ],
  "width": 880,
  "height": 550
}

Parameters

Optional parameters:

  • media_set_id - ID of the media set (gallery) the asset should be added to

Uploading assets

Here's a basic example based on the previous asset create request:

PUT http://media.voog.com/0000/0000/0001/files/new_image.png?AWSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Expires=1391528261&Signature=IGPxxxxxxxx%2FdjkdjkJWjwjjwjw%3D

Headers:

x-amz-acl: public-read
content-type: image/png
content-length: 95708

The request body has to be the raw file data as a byte array (Buffer in NodeJS, Blob in Javascript etc.). For more details, refer to the official Amazon AWS documentation.

Code example in Ruby.

Code example in Node.

Get data for a single asset

GET /admin/api/assets/1

Get detailed data for single asset. Asset may be on of type: image, document or flash.

When asset type is image then also all array of available sizes are included to response as sizes.

When asset type is image or flash then attributes width and height is provided in response.

Example request:

GET http://helloworld.voog.co/admin/api/assets/3?include_media_sets=true

Example response:

Status: 200 OK

{
  "id": 3,
  "filename": "new_image.png",
  "content_type": "image/png",
  "size": 95708,
  "extension": "png",
  "type": "image",
  "status": "done",
  "created_at": "2014-02-04T11:03:11.000Z",
  "updated_at": "2014-02-04T11:04:01.000Z",
  "url": "http://helloworld.voog.co/admin/api/assets/3",
  "public_url": "http://media.voog.com/0000/0000/0001/photos/new_image.png",
  "sizes": [
    {
      "thumbnail": "block",
      "filename": "new_image_block.png",
      "content_type": "image/png",
      "size": 124204,
      "width": 500,
      "height": 344,
      "public_url": "http://media.voog.com/0000/0000/0001/photos/new_image_block.png"
    },
    {
      "thumbnail": "medium",
      "filename": "new_image_medium.jpg",
      "content_type": "image/jpeg",
      "size": 4887,
      "width": 150,
      "height": 103,
      "public_url": "http://media.voog.com/0000/0000/0001/photos/new_image_medium.jpg"
    }
  ],
  "width": 880,
  "height": 550,
  "media_sets": [{
    "id": 1,
    "title": "",
    "created_at": "2014-01-16T08:04:27.000Z",
    "updated_at": "2014-01-16T08:04:27.000Z",
    "url": "http://media.voog.com/admin/api/media_sets/1",
    "add_assets_url": "http://media.voog.com/admin/api/media_sets/1/add_assets"
  }]
}

Parameters

  • include_media_sets - includes list of media sets where current asset is added. (E.g. ?include_media_sets=true)

Remove an asset

DELETE /assets/1

This request deletes the asset from the database. Asset thumbnails are deleted automatically with parent.

Example request:

DELETE http://helloworld.voog.co/admin/api/assets/1

Example response:

Status: 204 No Content
Product
Create online store
Create web page
Create blog
Integrations
All Features
Partners
Company
About Voog
Affiliate program
Blog
Support
Help Centre
Contact Support
Follow Us
Facebook
Twitter
Instagram
Cookie settings Privacy Policy Terms & Conditions