Entity-scoped runs need an entity reference. The most reliable reference is a resolved entity UUID.
Reference Shapes
{ "id": "550e8400-e29b-41d4-a716-446655440002" }{ "external_uri": "vault:company/example" }{ "external_id": "example", "source": "custom" }Supported source values are vault, linkedin, crunchbase, and custom.
Resolve Entities
Use GET /entities/resolve before creating a preset run when you are not sure a reference exists in the workspace.
curl "https://havilo.ai/api/v1/entities/resolve?refs=%5B%7B%22id%22%3A%22550e8400-e29b-41d4-a716-446655440002%22%7D%5D" \
-H "Authorization: Bearer $HAVILO_API_KEY"{
"results": [
{
"ref": {
"id": "550e8400-e29b-41d4-a716-446655440002"
},
"resolved": true,
"entity_id": "550e8400-e29b-41d4-a716-446655440002",
"entity_name": "Example Company",
"entity_type": "Company"
}
]
}Unresolved references return a per-result error:
{
"results": [
{
"ref": {
"external_uri": "custom:missing"
},
"resolved": false,
"error": {
"code": "entity_not_resolvable",
"message": "No entity matching the reference could be found in this workspace."
}
}
]
}For dossier runs, pass the resolved UUID form:
{
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440002"
}
}