---
title: "Create an automation"
method: POST
path: "/v1/automations"
tags: ["Automations"]
---

# Create an automation

`POST /v1/automations`

## Request

- Base URL: `https://api.dexto.ai`
- URL: `https://api.dexto.ai/v1/automations`
- Auth: HTTP bearer

Create an automation that runs an agent of this key's Cloud project on a schedule or on signed webhook requests. Each firing is a run of the agent, paid from credits.

## Request body

- object
  - `name` string, required: Display name.
  - `target` object, required
    - `agent_id` string, uuid, required: An active agent of this key's Cloud project.
    - `message` string, required: The message each firing sends the agent. It may use {{automation.id}}, {{automation.name}}, {{firing.id}}, {{firing.source}}, {{firing.fired_at}}, {{firing.scheduled_for}}, {{webhook.payload}}; {{webhook.payload}} is the request's JSON body (webhook automations only).
    - `session` union: Which session each firing writes to.
      - object
        - `metadata` object: Your context for this session, such as a tenant id. Function tools receive it with every call; the model never sets it.
        - `mode` 'new', required: Start a new session of the agent for each firing.
        - `user` string: The new sessions' end-user label. Defaults to automation:<automation id>.
      - object
        - `mode` 'fixed', required: Send every firing to one session.
        - `session_id` string, uuid, required: A session of the target agent.
    - `type` 'agent', required: Run an Agents API agent.
  - `trigger` union, required: What fires the automation.
    - object
      - `schedule` union, required: When the automation fires.
        - object
          - `run_at` string, date-time, required: When to fire, an ISO 8601 date and time with an offset, in the future and at most 366 days ahead.
          - `type` 'once', required: Fire once, within a minute of run_at.
        - object
          - `cron` string, required: A five-field cron expression (minute, hour, day of month, month, day of week). Two firings may be no closer than 5 minutes.
          - `timezone` string, required: The IANA timezone the cron is read in, such as Europe/Berlin.
          - `type` 'recurring', required: Fire on every cron occurrence.
      - `type` 'schedule', required
    - object
      - `type` 'webhook', required: Fire on each signed request to the automation's webhook URL. The signing secret is returned once, when the automation is created.

## Response `201`

Created.

- object
  - `cloud_project` object, required
    - `id` string, uuid, required
    - `name` string, required
  - `created_at` string, date-time, required
  - `created_by` union, required: The API key while it exists, the person otherwise (who may have used an OAuth token), or the agent's automations tool, that created it.
    - object
      - `api_key_id` string, uuid, nullable, required: Null once the key is deleted.
      - `type` 'api_key', required
    - object
      - `agent_id` string, uuid, required
      - `type` 'agent', required
    - object
      - `type` 'user', required
      - `user_id` string, required: The person who created it through an OAuth token, or whose key was since deleted.
  - `id` string, uuid, required
  - `last_fired_at` string, date-time, nullable, required
  - `name` string, required
  - `object` 'automation', required
  - `paused_reason` 'requested' | 'repeated_failures' | 'target_unavailable', nullable, required: Why a paused automation is paused: requested, repeated_failures (five failed or refused firings in a row) or target_unavailable (its agent, project or session is gone).
  - `status` 'active' | 'paused' | 'completed', required: active, paused, or completed for a one-time schedule that fired.
  - `target` object, required
    - `agent_id` string, uuid, required
    - `message` string, required
    - `session` union, required
      - object
        - `metadata` object, required
        - `mode` 'new', required
        - `user` string, required
      - object
        - `mode` 'fixed', required
        - `session_id` string, uuid, required
    - `type` 'agent', required
  - `trigger` union, required
    - object
      - `next_run_at` string, date-time, nullable, required: When it fires next; null while paused or once completed.
      - `schedule` union, required
        - object
          - `run_at` string, date-time, required
          - `type` 'once', required
        - object
          - `cron` string, required
          - `timezone` string, required
          - `type` 'recurring', required
      - `type` 'schedule', required
    - object
      - `type` 'webhook', required
      - `url` string, uri, required: POST signed JSON here. Sign with Dexto-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of '<t>.<raw body>'>.
  - `updated_at` string, date-time, required
  - `webhook_secret` string, nullable, required: A webhook automation's signing secret, returned only in this response; null for a schedule.

## Other responses

- `400`: Invalid JSON or request fields.
- `401`: Missing or invalid API key.
- `402`: The account has insufficient credits.
- `403`: The account cannot perform this operation.
- `404`: The requested resource was not found.
- `409`: The request conflicts with existing resource state.
- `429`: The account exceeded this operation's request rate.
- `500`: Unexpected Dexto failure.
- `502`: The upstream model provider failed.
- `503`: A required Dexto service is temporarily unavailable.

---

[API](https://skmtc.dev/dexto/apis/dexto-api.md) - [All operations](https://skmtc.dev/dexto/apis/dexto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dexto/apis/dexto-api/revisions/47eb880cffa5?raw)