# Dossier Preset

Source: https://docs.havilo.ai/reference/ai-engine/dossier

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:

```bash
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

```bash
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

```json
{
  "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

```bash
curl https://havilo.ai/api/v1/artifacts/550e8400-e29b-41d4-a716-446655440003 \
  -H "Authorization: Bearer $HAVILO_API_KEY"
```

```json
{
  "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.