NAV Navbar
DEVELOPER

Introduction

Welcome to the HIVO API! You can use our API to access HIVO API endpoints.

You can view code examples in the dark area to the right.

This API follows the json:api specification.

You can register a new HIVO API key in the HIVO User Profile, or by contacting HIVO Support.

Basics

Test your API credentials:

# Replace USER_ID and API_KEY with your HIVO credentials.

curl "https://api.hivo.com.au/rest/v1/users/me"
  -H "X-User-Id: <USER_ID>"
  -H "X-Api-Key: <API_KEY>"

200 OK:

{
  "meta": {
    "timestamp": 0123456789,
    "authentication": "apiKey",
    "links": {
      "me": "https://api.hivo.com.au/rest/v1/users/<USER_ID>"
    }
  },
  "links": {
    "self": "https://api.hivo.com.au/rest/v1/users/me"
  },
  "data": {
    "type": "users",
    "id": "<USER_ID>",
    "attributes": {
      "name": "Joe Bloggs"
    },
    "links": {
      "self": "https://api.hivo.com.au/rest/v1/users/<USER_ID>"
    }
  }
}

HIVO uses API keys to allow access to the API.

HIVO expects a USER_ID and API_KEY in all API requests to the server in headers.

You can register a new HIVO API key in the HIVO User Profile, under Configure API Access. The USER_ID and API_KEY will be given to you here.

Response Details

Every response has the following properties:

Assets

List Assets

curl "https://api.hivo.com.au/rest/v1/assets"
  -H "X-User-Id: <USER_ID>"
  -H "X-Api-Key: <API_KEY>"

200 OK:

{
  "meta": {
    "timestamp": 0123456789,
    "authentication": "apiKey",
    "links": {
      "me": "https://api.hivo.com.au/rest/v1/users/<USER_ID>"
    },
    "pageCount": 2,
    "itemCount": 100
  },
  "links": {
    "self": "https://api.hivo.com.au/rest/v1/assets",
    "first": "https://api.hivo.com.au/rest/v1/assets",
    "last": "https://api.hivo.com.au/rest/v1/assets?skip=50",
    "next": "https://api.hivo.com.au/rest/v1/assets?skip=50"
  },
  "data": [
    {
      "type": "assets",
      "id": "aaaaaaaaaaaaaaaaa",
      "attributes": {
        "name": "IMG_004.jpeg",
        "createdAt": 0123456789,
        "lastModified": 0123456789,
        "versions": {
          "original": {
            "size": 200000,
            "type": "image/jpeg"
          },
          "thumbnail": {
            "size": 10000,
            "type": "image/jpeg"
          }
        }
      },
      "links": {
        "self": "https://api.hivo.com.au/rest/v1/assets/aaaaaaaaaaaaaaaaa",
      }
    },
    {
      "type": "assets",
      "id": "bbbbbbbbbbbbbbbbb",
      "attributes": {
        "name": "IMG_005.jpeg",
        "createdAt": 0123456789,
        "lastModified": 0123456789,
        "versions": {
          "original": {
            "size": 200000,
            "type": "image/jpeg"
          }
        }
      },
      "links": {
        "self": "https://api.hivo.com.au/rest/v1/assets/bbbbbbbbbbbbbbbbb"
      }
    }
  ]
}

GET https://api.hivo.com.au/rest/v1/assets

Gets a list of Assets on HIVO that you have permission to view.

Search Parameters

Key Description
sort Sort the assets by a particular sort key.
limit Maximum number of assets to return in the array.
skip Number of assets to skip in the returned array. Used for pagination. Set this to limit for page 2, limit * 2 for page 3, etc.
filter[id] Comma-separated Assets IDs to search for.
filter[search] Comma-separated general search.

Examples

GET https://api.hivo.com.au/rest/v1/assets?sort=-createdAt&limit=32&skip=32

Gets page 2 of Assets sorted by createdAt date, with 32 items per page.

 

GET https://api.hivo.com.au/rest/v1/assets?filter[search]=dog,clouds

Searches for Assets that contain general search "dog" and "clouds".

Get Asset

curl "https://api.hivo.com.au/rest/v1/assets/<ASSET_ID>"
  -H "X-User-Id: <USER_ID>"
  -H "X-Api-Key: <API_KEY>"

200 OK:

{
  "meta": {
    "timestamp": 0123456789,
    "authentication": "apiKey",
    "links": {
      "me": "https://api.hivo.com.au/rest/v1/users/<USER_ID>"
    }
  },
  "links": {
    "self": "https://api.hivo.com.au/rest/v1/assets/<ASSET_ID>",
  },
  "data": {
    "type": "assets",
    "id": "<ASSET_ID>",
    "attributes": {
      "name": "IMG_004.jpeg",
      "createdAt": 0123456789,
      "lastModified": 0123456789,
      "folder": "2020/photos/",
      "tags": [
        "construction",
        "building",
        "architecture"
      ],
      "versions": {
        "original": {
          "createdAt": 0123456789,
          "size": 200000,
          "type": "image/jpeg",
          "channels": 3,
          "views": 1,
          "downloads": 5
        },
        "thumbnail": {
          "createdAt": 0123456789,
          "size": 10000,
          "type": "image/jpeg",
          "channels": 3,
          "views": 20
        }
      },
      "location": {
        "label": "Example House, Roslyn Street, Rushcutters Bay NSW, Australia",
        "placeId": "ChIJezO5VWGvEmsRca9nd5aJAwY",
        "location": {
          "lat": -33.87562680000001,
          "lng": 151.2258514
        }
      },
      "metadata": {
        "description": "Project rebuild 2020 photos",
        "copyright": "Joe Bloggs © 2020"
      },
      "views": 21,
      "downloads": 5
    },
    "links": {
      "self": "https://api.hivo.com.au/rest/v1/assets/<ASSET_ID>"
    }
  }
}

GET https://api.hivo.com.au/rest/v1/assets/<ASSET_ID>

Gets an individual Asset on HIVO that you have permission to view.

Asset Attributes

Key Description
name Asset Name
createdAt Date when this Asset was first entered into HIVO (Unix timestamp in seconds).
lastModified Date when this Asset was last modified on HIVO (Unix timestamp in seconds).
folder Asset location on HIVO.
tags Array of tags that describe the contents of this Asset.
versions Object containing all versions of this asset.
location Google geolocation of the Asset.
metadata Object containing additional Asset metadata.
views Total Asset views.
downloads Total Asset downloads.

Download Asset

curl "https://api.hivo.com.au/rest/v1/assets/<ASSET_ID>/download"
  -H "X-User-Id: <USER_ID>"
  -H "X-Api-Key: <API_KEY>"

302 Found:

HTTP/2 302
date: Thu, 04 May 2020 08:58:40 GMT
location: https://hivo-client-0000000000000000000000000000000000.s3.ap-southeast-2.amazonaws.com/uploads/aaaaaaaaaaaaaaaaa/original.jpg?AWSAccessKeyId=AAAAAAAAAAAAAAAAAAAA&Expires=0123456789&Signature=ABCDABCDABCDABCDABCDABCDABCDABCDAB

GET https://api.hivo.com.au/rest/v1/assets/<ASSET_ID>/download

Downloads an asset version from HIVO.

Search Parameters

Key Default Description
version original The version to download.
attachment 1 Set to make Content-Disposition attachment (1) or inline (0).
inline 0 Inverse of attachment. Set to make Content-Disposition attachment (0) or inline (1).

Examples.

https://api.hivo.com.au/rest/v1/assets/<ASSET_ID>/download

Downloads the original version of the Asset.

 

https://api.hivo.com.au/rest/v1/assets/<ASSET_ID>/download?version=thumbnail&inline=1

Downloads the thumbnail with Content-Disposition set to inline.

Errors

403 - Forbidden

{
  "meta": {
    "timestamp": 0123456789,
    "authentication": "apiKey",
    "links": {
      "me": "https://api.hivo.com.au/rest/v1/users/<USER_ID>"
    }
  },
  "errors": [{
    "status": "403",
    "title": "Forbidden"
  }]
}

429 - Too Many Requests

{
  "meta": {
    "timestamp": 0123456789,
    "retryAfter": 1000
  },
  "errors": [{
    "status": "429",
    "title": "Too Many Requests"
  }]
}

The HIVO API uses the following error codes:

Code Description
400 Bad Request - Your request is invalid.
401 Unauthorized - Your API key is incorrect/missing.
403 Forbidden - You do not have permission to make this request.
404 Not Found - The specified resource could not be found.
405 Method Not Allowed - The request method is not allowed.
406 Not Acceptable - You requested a format that isn't json.
413 Payload Too Large - Your request body is too large and the request was discarded.
415 Unsupported Media Type - Your request body is not the required type of application/json or application/vnd.api+json.
429 Too Many Requests - You are making too many requests. Please slow down.
431 Request Header Fields Too Large - The request header is too large and the request was discarded.
500 Internal Server Error - We had a problem with our server. Please try again shortly.
502 Bad Gateway - We had a problem with our network. Please try again shortly.
503 Service Unavailable - We're temporarily offline for maintenance. Please try again shortly.

The meta property may contain additional info related to the error:

Name Description
retryAfter How long you should wait (in milliseconds) until re-attempting the request.