---
title: "Generate a scheduled task spec from a prompt."
method: POST
path: "/scheduled_tasks/generate_spec"
tags: ["System"]
---

# Generate a scheduled task spec from a prompt.

`POST /scheduled_tasks/generate_spec`

## Request

- Base URL: `https://h2ogpte.genai.h2o.ai/api/v1`
- URL: `https://h2ogpte.genai.h2o.ai/api/v1/scheduled_tasks/generate_spec`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/h2o/apis/h2ogpte-rest-api/docs/scheduled_tasks/generate_spec/post.ts> (a function with typed inputs; its response is checked against the schema)

Uses an LLM with guided JSON to generate a scheduled task configuration
from a natural language description. The returned spec can be used directly
with the create_scheduled_task RPC.

## Request body

- object
  - `prompt` string, required: Natural language description of the desired scheduled task.
  - `llm` string: Optional LLM model override for generation.
  - `timezone` string: Optional IANA timezone string (e.g. "America/New_York") used to compute today's local date for relative schedule expressions. Defaults to UTC.
  - `use_agent` boolean: When true, signals to the LLM that the user has agent mode enabled in their chat so it should prefer task_type=agent_task unless the prompt clearly describes a plain chat-completion task. Does not force the generated task_type.

## Response `200`

Generated scheduled task configuration.

- object
  - `task` object: The generated scheduled task spec.
  - `passed` boolean: Whether the user prompt was minimally sufficient to create the task. Callers MUST NOT create the task when passed is false; only show `response` to the user.
  - `dialog` 'none' | 'text' | 'ui': Confirmation strategy the caller should use before creating the task. - "none": user gave everything needed; create directly and show `response`. - "text": confirm in chat with the user before creating (caller waits for a yes/no reply). - "ui": open the full schedule-task dialog pre-filled from the spec for the user to review/edit. Always "text" when passed=false. `response` is suitable for any of the three modes.
  - `response` string: When passed=false, a clarifying question describing what info is missing. When passed=true, a human-language message — a one-line confirmation when dialog=none, a yes/no ask when dialog=text, a "review the form" message when dialog=ui. May include the literal tokens `{artifact_url}` and `{artifact_name}` which the caller substitutes after creation.
  - `llm_used` string: The actual model that generated the spec.

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `default`: Unexpected error

---

[API](https://skmtc.dev/h2o/apis/h2ogpte-rest-api.md) - [All operations](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/revisions/a82a117320f4?raw)