API Documentation


Accessing and Creating entities via the API

There are 2 ways to create entities :

Lazy Creation

As we saw before, you can lazily create entities merely by doing actions on them. You don’t need to create them first. Please note here that entities can be referenced, either :

  • By their hull ID if you already know it
  • By their Base64-Encoded UID
Explicitly via a hull ID

You can create / update and delete entities like any other Hull object.

Please note that this api requires admin credentials, it is not available to end users.

To create entities attached to the current app:

  POST /app/entities (for the current app)
  POST /:app_id/entities (for a specific app)

To create an Entity attached to your organization (and available to all Apps):

POST /org/entities

To update or delete them via their ID:

PUT /:entity_id
DELETE /:entity_id

Entities have these standard fields, and are augmented by the OpenGraph tags fetched if the Entity is a valid URL

A note about Querying:

URL Entites are built from whatever data can be collected from the source URL. The name, description or picture parameters are built from the entity’s own value and default to the value in the source URL’s Meta Tags. This means querying with the where parameter for their can return an empty value. To properly query for the picture you should do this:

//Do this:
Hull.api('/entities', {
  'where': {
    '$or': [
      {'picture': 'http://example.com/image.jpg'},
      {'meta_tags.image': 'http://example.com/image.jpg'}
    ]
  }
});

Also, Check the section on queries to see what fields have to be remapped