Assets API | Hitchhikers Platform

Overview

The Assets Endpoint Group allows you to create, update, retrieve and delete Assets stored in the Knowledge Graph. These assets can then be applied to specific entity fields in your Knowledge Graph.

When creating new assets via this endpoint group, you must specify the asset’s name, type, value (the asset’s content), usage (which features and/or fields the asset can be used for) and forEntities (which entities it can be used for).

When making updates to existing assets, note that this endpoint is a true PUT. Fields that are not provided in an update will be cleared. The entire Asset object must be provided in the request, except for its id, which is given in the path.

Use Cases

Add new Assets that can be applied to Entities in your account
Retrieve a list of all Assets in your account
Make updates to existing Assets in your account

Reference Docs

Assets Endpoints

Guides

Assets Training

Assets: List

List assets in an account.

path Parameters

accountId

required

string

query Parameters

v required	string A date in `YYYYMMDD` format.
offset	integer Default: 0 Number of results to skip. Used to page through results. Cannot be used together with `pageToken`.
limit	integer <= 1000 Default: 100 Number of results to return.
pageToken	string If a response to a previous request contained the `pageToken` field, pass that field's value as the `pageToken` parameter to retrieve the next page of data.
format required	string >= 0 characters Default: "markdown" Present if and only if type of subfield is "Rich Text." Valid values: `markdown` `html` `none`

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"count": 0,
"assets": [{"id": "string",
"name": "string",
"description": "string",
"type": "string",
"forEntities": {"mappingType": "string",
"folderId": "string",
"entityIds": ["string"
],
"labelIds": ["string"
],
"labelOperator": "AND"
},
"usage": [{"type": "string",
"fieldNames": ["string"
]
}
],
"locale": "string",
"labels": ["string"
],
"owner": "string"
}
],
"pageToken": "string"
}
}

Assets: Create

Creates a new asset in an account.

NOTE:

If the v parameter is on or before 20190624: only the first folder the Asset is available for will be returned in the legacy folderId field.
If the v parameter is after 20190624: the complete list of folders the Asset is available to will be returned in the new folderIds field. folderId will not be returned.

path Parameters

accountId

required

string

query Parameters

v required	string A date in `YYYYMMDD` format.
format required	string >= 0 characters Default: "markdown" The formatting langauge used to parse rich text field values. Present if and only if type of field is "Rich Text." Valid values: `markdown` `html`

Request Body schema: application/json

name required	string <= 100 characters Asset name.
description	string <= 255 characters Asset description.
type required	string Asset Type. In addition to the choices below, names of custom field types may also be used. One of: complexImage complexImage complexVideo text
required	object
required	Array of objects
locale	string Language of the asset.
labels	Array of strings List of text labels for this asset.
owner	string ID of the user who owns the asset.
required	object The content of the asset.

Responses

Request samples

Payload

Content type

application/json

Example

{"name": "string",
"description": "string",
"type": "complexImage",
"forEntities": {"mappingType": "string",
"folderId": "string",
"entityIds": ["string"
],
"labelIds": ["string"
],
"labelOperator": "AND"
},
"usage": [{"type": "string",
"fieldNames": ["string"
]
}
],
"locale": "string",
"labels": ["string"
],
"owner": "string",
"value": {"image": {"url": "http://example.com",
"alternateText": "string"
},
"description": "string",
"clickthroughUrl": "http://example.com"
}
}

Response samples

201
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"id": "string"
}
}

Assets: Get

Get a specific asset.

path Parameters

accountId required	string
assetId required	string

query Parameters

v required	string A date in `YYYYMMDD` format.
format required	string >= 0 characters Default: "markdown" Present if and only if type of subfield is "Rich Text." Valid values: `markdown` `html` `none`

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"id": "string",
"name": "string",
"description": "string",
"type": "string",
"forEntities": {"mappingType": "string",
"folderId": "string",
"entityIds": ["string"
],
"labelIds": ["string"
],
"labelOperator": "AND"
},
"usage": [{"type": "string",
"fieldNames": ["string"
]
}
],
"locale": "string",
"labels": ["string"
],
"owner": "string"
}
}

Assets: Update

Update a specific asset.

NOTE: This endpoint is a true PUT. Fields that are not provided in an update will be cleared. The entire Asset object must be provided in the request, except for its id, which is given in the path.

NOTE:

If the v parameter is on or before 20190624: only the first folder the Asset is available for will be returned in the legacy folderId field.
If the v parameter is after 20190624: the complete list of folders the Asset is available to will be returned in the new folderIds field. folderId will not be returned.

path Parameters

accountId required	string
assetId required	string

query Parameters

v required	string A date in `YYYYMMDD` format.
format required	string >= 0 characters Default: "markdown" The formatting langauge used to parse rich text field values. Present if and only if type of field is "Rich Text." Valid values: `markdown` `html`

Request Body schema: application/json

name required	string <= 100 characters Asset name.
description	string <= 255 characters Asset description.
type required	string Asset Type. In addition to the choices below, names of custom field types may also be used. One of: complexImage complexImage complexVideo text
required	object
required	Array of objects
locale	string Language of the asset.
labels	Array of strings List of text labels for this asset.
owner	string ID of the user who owns the asset.
required	object The content of the asset.

Responses

Request samples

Payload

Content type

application/json

Example

{"name": "string",
"description": "string",
"type": "complexImage",
"forEntities": {"mappingType": "string",
"folderId": "string",
"entityIds": ["string"
],
"labelIds": ["string"
],
"labelOperator": "AND"
},
"usage": [{"type": "string",
"fieldNames": ["string"
]
}
],
"locale": "string",
"labels": ["string"
],
"owner": "string",
"value": {"image": {"url": "http://example.com",
"alternateText": "string"
},
"description": "string",
"clickthroughUrl": "http://example.com"
}
}

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"id": "string"
}
}

Assets: Delete

Delete a specific asset.

path Parameters

accountId required	string
assetId required	string

query Parameters

required

string

A date in YYYYMMDD format.

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": { }
}