# AI Engine API

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

The AI Engine API lets you submit natural-language queries, structured execution plans, and supported presets to Havilo. Every successful run starts asynchronously: create a run, poll or stream progress, then fetch the generated artifacts.

`POST /runs` returns a run envelope immediately after the request is accepted. It does not wait for the AI work to finish and does not include full artifact bodies. Poll `GET /runs/{id}` or stream events until the run reaches a terminal state, then fetch each artifact body from `GET /artifacts/{id}`.

## Base URL

```txt
https://havilo.ai/api/v1
```

All paths in this section are relative to that base URL.

## Core Flow

1. Create a run with `POST /runs`.
2. Poll `GET /runs/{id}` or stream events from `/runs/{id}/events/stream`.
3. Read artifact metadata from the run envelope.
4. Fetch artifact bodies with `GET /artifacts/{id}`.

## Available Guides

* [Quickstart](https://docs.havilo.ai/reference/ai-engine/quickstart.md) - Create a run and fetch a table artifact.
* [Authentication](https://docs.havilo.ai/reference/ai-engine/authentication.md) - Bearer keys, scopes, and key safety.
* [Runs](https://docs.havilo.ai/reference/ai-engine/runs.md) - Request bodies, run envelopes, cancel, and idempotency.
* [Step Kinds](https://docs.havilo.ai/reference/ai-engine/step-kinds.md) - Parameters for every plan step kind.
* [Artifacts](https://docs.havilo.ai/reference/ai-engine/artifacts.md) - Table, text, and entity-card artifact bodies.
* [Events](https://docs.havilo.ai/reference/ai-engine/events.md) - Polling, event tokens, and SSE streams.
* [Webhooks](https://docs.havilo.ai/reference/ai-engine/webhooks.md) - Lifecycle callbacks and signature verification.
* [Entity References](https://docs.havilo.ai/reference/ai-engine/entity-refs.md) - Resolve entity IDs before entity-scoped runs.
* [Dossier Preset](https://docs.havilo.ai/reference/ai-engine/dossier.md) - Generate a dossier for a known entity.
* [Errors](https://docs.havilo.ai/reference/ai-engine/errors.md) - Error shape, status codes, and retry guidance.
* [Reliability](https://docs.havilo.ai/reference/ai-engine/reliability.md) - Idempotency, retries, and practical limits.

## Supported Run Inputs

| Input type | Use when                                                        |
| ---------- | --------------------------------------------------------------- |
| `query`    | You want Havilo to understand the question and create the plan. |
| `plan`     | You already know the exact steps to run.                        |
| `preset`   | You want a supported packaged workflow such as `dossier`.       |

## Timestamp and ID Format

Run IDs, artifact IDs, and entity IDs are UUID strings. Timestamps such as `created_at`, `completed_at`, and event `occurred_at` are Unix epoch milliseconds. `completed_at` appears only after a run reaches a terminal state.

`api_version` is echoed on run and event responses so clients can log which contract handled a request. Treat it as an opaque version string; you do not need to send it on normal requests.