The dossier preset creates a written dossier for a known entity. It returns a text artifact, an entity_card artifact, and may create a note linked to the run.
1. Resolve the Entity
Before creating a dossier run, resolve the entity reference:
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"Use a result with "resolved": true.
2. Create the Dossier Run
curl -X POST https://havilo.ai/api/v1/runs \
-H "Authorization: Bearer $HAVILO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: dossier-550e8400-001" \
-d '{
"input_type": "preset",
"preset": "dossier",
"params": {
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440002"
},
"sections": ["background", "funding", "key_people"],
"max_tokens": 2000
}
}'Parameters
| Field | Required | Description |
|---|---|---|
entity | Yes | Entity reference. Prefer the resolved UUID form. |
sections | No | Headings to use, in order, instead of the default five (overview, key attributes, relationships, recent activity, strategic insights). Up to 12, each up to 80 characters. |
max_tokens | No | Approximate maximum output length. |
Successful Run Output
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"object": "run",
"status": "succeeded",
"artifacts": [
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"kind": "text",
"title": "Company Dossier"
},
{
"id": "550e8400-e29b-41d4-a716-446655440004",
"kind": "entity_card",
"title": "Entity Card"
}
],
"note_ids": ["550e8400-e29b-41d4-a716-446655440005"]
}Fetch the Text Artifact
curl https://havilo.ai/api/v1/artifacts/550e8400-e29b-41d4-a716-446655440003 \
-H "Authorization: Bearer $HAVILO_API_KEY"{
"id": "550e8400-e29b-41d4-a716-446655440003",
"object": "artifact",
"kind": "text",
"title": "Company Dossier",
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": 1714500018000,
"content": "## Company Dossier\n\n### Background\n\n..."
}Common Failure
If the record cannot be found in your workspace, POST /runs returns 422 entity_not_resolvable with param: "params.entity" and no run is created. Resolve the record first with GET /entities/resolve, then retry with its UUID.