# Untimely Agent Integration Guide

Use the Untimely API to schedule recurring email reminders, webhook calls, and Slack messages. Choose random times within a window or a fixed time in a timezone.

## Authentication

API keys are created in the dashboard by signed-in users. Agents use an existing key:

```http
Authorization: Bearer <UNTIMELY_API_KEY>
```

Step-by-step docs: https://untimely.app/docs.

The OpenAPI document is available at https://untimely.app/openapi.json.

## Create an event

Use `POST /api/events` with `Idempotency-Key` for safe retries. Supported action types are EMAIL, WEBHOOK, and SLACK (SLACK and `contentType: "gpt"` require a Pro plan).

Message content can be static or AI-generated by setting `contentType` to `static` or `gpt`; `gpt` requires a Pro plan.

Pro plans can send a 2-step pipeline via `tools`: a generate step (`{"toolType": "LLM", "prompt": ...}`) followed by a deliver step; the generated text becomes the delivery content.

For random schedules, provide `interval`, `frequency`, `betweenTimeStart`, `betweenTimeEnd`, optional `daysOfWeek`, and optional `timezone` (IANA name; times are interpreted in that timezone, or UTC when omitted).

For fixed schedules, set `scheduleType` to `deterministic`, then provide `fixedTime`, `timezone`, `interval`, and optional `daysOfWeek`.

## Check an event

Use `GET /api/events` to list recent events and `GET /api/events/{id}` to inspect one event. Schedule run details are available through `GET /api/events/{id}/schedules/{scheduleId}`.

## Update or delete

Use `PATCH /api/events/{id}` to update event settings. Use `DELETE /api/events/{id}` to remove an event.

## Configure a webhook

Webhook actions accept a method, URL, headers, and optional body. Use placeholder examples in prompts and avoid asking agents to store sensitive values in generated text.

## Reliability

Delivery is at-least-once, so duplicates are possible during retries. Failed runs retry automatically; inspect run history to check what was delivered. Exhausted retries and missed schedules raise internal incidents. Inspect per-run results with `GET /api/events/{id}/schedules/{scheduleId}`. Full policy: https://untimely.app/reliability