--- title: "Create an automation" method: POST path: "/agents/automations" tags: ["Agents"] --- # Create an automation `POST /agents/automations` ## Request - Base URL: `https://api.openai.com/v1` - URL: `https://api.openai.com/v1/agents/automations` - Auth: HTTP bearer Saves an active automation without invoking it immediately. ## Request body - union: Creates an automation without invoking it immediately. - object - `type` 'periodic', required: The type of the object. Always `periodic`. - `name` string, required: A human-readable name for the automation. - `target` union, required: The session an automation invocation targets. - object: Create a session for each invocation. - `type` 'new_session', required: The type of the object. Always `new_session`. - `agent` SessionAgentConfigParam: Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field; null resets nullable fields. - `model` string: The model to use for the agent. The requested model name is preserved. - `reasoning` ReasoningParam: Reasoning configuration for the agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': The amount of reasoning effort the model should use. - `summary` 'concise' | 'detailed' | 'auto': The reasoning summary format requested from the model. - `text` TextParam: Configuration for text generated by the agent. - `format` union: The output format for generated text. - … - `verbosity` 'low' | 'medium' | 'high': The amount of text the model should produce. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast': The service tier used for model requests. - `instructions` string, nullable: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `multi_agent` MultiAgentConfigCurrentParam: Explicit configuration for creating and coordinating subagents. - `enabled` boolean, required: Whether subagent tools are enabled. - `max_concurrent_subagents` integer: Maximum number of subagents that may run concurrently. Defaults to 6. - `tools` AgentToolConfigParam[], nullable: Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. - union: A tool available to the agent. - … - `agent_id` string: A saved agent ID. Provide exactly one of agent and agent_id. - `environment` union, required: The execution environment and optional reusable template for a session. - object: Runs the agent without an execution environment. - `type` 'none', required: The type of the object. Always `none`. - object: An application-hosted environment configured inline. - `type` 'self_hosted', required: The type of the object. Always `self_hosted`. - `capability_directories` string[], nullable: Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `workspace_directory` string, required: Absolute project directory inside the self-hosted environment. - `input` InputMessageParam[], required: Initial user messages submitted with each new session. - `type` 'message': The type of the input item. Always `message`. - `role` 'user', required: The role of the message author. Always `user`. - `content` InputContentParam[], required: The content of the message. - union: Content included in an input message. - … - `vault_ids` string[], nullable: The IDs of vaults made available to each new session. - `metadata` object, nullable: Metadata attached to each new session. - object: Deliver instructions to an existing session. - `type` 'existing_session', required: The type of the object. Always `existing_session`. - `session_id` string, required: The session receiving each invocation. - `instructions` string, required: Instructions delivered as an automation notification. - `metadata` object - `expression` string, required: A standard five-field cron expression defining scheduled occurrences. - `timezone` string, required: The IANA timezone used to interpret the cron expression. - object - `type` 'once', required: The type of the object. Always `once`. - `name` string, required: A human-readable name for the automation. - `target` union, required: The session an automation invocation targets. - object: Create a session for each invocation. - `type` 'new_session', required: The type of the object. Always `new_session`. - `agent` SessionAgentConfigParam: Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field; null resets nullable fields. - `model` string: The model to use for the agent. The requested model name is preserved. - `reasoning` ReasoningParam: Reasoning configuration for the agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': The amount of reasoning effort the model should use. - `summary` 'concise' | 'detailed' | 'auto': The reasoning summary format requested from the model. - `text` TextParam: Configuration for text generated by the agent. - `format` union: The output format for generated text. - … - `verbosity` 'low' | 'medium' | 'high': The amount of text the model should produce. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast': The service tier used for model requests. - `instructions` string, nullable: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `multi_agent` MultiAgentConfigCurrentParam: Explicit configuration for creating and coordinating subagents. - `enabled` boolean, required: Whether subagent tools are enabled. - `max_concurrent_subagents` integer: Maximum number of subagents that may run concurrently. Defaults to 6. - `tools` AgentToolConfigParam[], nullable: Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. - union: A tool available to the agent. - … - `agent_id` string: A saved agent ID. Provide exactly one of agent and agent_id. - `environment` union, required: The execution environment and optional reusable template for a session. - object: Runs the agent without an execution environment. - `type` 'none', required: The type of the object. Always `none`. - object: An application-hosted environment configured inline. - `type` 'self_hosted', required: The type of the object. Always `self_hosted`. - `capability_directories` string[], nullable: Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `workspace_directory` string, required: Absolute project directory inside the self-hosted environment. - `input` InputMessageParam[], required: Initial user messages submitted with each new session. - `type` 'message': The type of the input item. Always `message`. - `role` 'user', required: The role of the message author. Always `user`. - `content` InputContentParam[], required: The content of the message. - union: Content included in an input message. - … - `vault_ids` string[], nullable: The IDs of vaults made available to each new session. - `metadata` object, nullable: Metadata attached to each new session. - object: Deliver instructions to an existing session. - `type` 'existing_session', required: The type of the object. Always `existing_session`. - `session_id` string, required: The session receiving each invocation. - `instructions` string, required: Instructions delivered as an automation notification. - `metadata` object - `run_at` integer, required: A future Unix timestamp in seconds. ## Response `201` The created automation. - union: A saved automation and its schedule. - object: Fields shared by periodic and one-time automations. - `type` 'periodic', required: The type of the object. Always `periodic`. - `id` string, required: The automation ID. - `object` 'agent.automation', required: Always `agent.automation`. - `created_at` integer, required: The creation time as a Unix timestamp in seconds. - `name` string, required: The automation's display name. - `target` union, required: Saved target configuration, excluding confidential request-only values. - object - `type` 'new_session', required: The type of the object. Always `new_session`. - `agent_id` string, nullable, required: The saved agent reference, or null when an inline agent is configured. - `agent` AutomationAgentConfigResource, required: Inline agent configuration without a generated session-local identity. - `model` string, required: The requested model name. - `reasoning` ReasoningResource, required: The reasoning configuration used by an agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required: The amount of reasoning effort used by an agent. - `summary` 'concise' | 'detailed' | 'auto', required: The reasoning summary format requested from an agent. - `text` TextResource, required: The text configuration used by an agent. - `format` union, required: The effective output format for generated text. - … - `verbosity` 'low' | 'medium' | 'high', required: The amount of text produced by an agent. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast', required: The service-tier policy configured for an agent. - `instructions` string, nullable, required: Custom instructions, or null when absent. - `tools` AgentToolResource[], required: Configured tools, excluding confidential credentials. - union: A tool available to the agent. - … - `multi_agent` MultiAgentConfigResource, required: The resolved configuration for creating and coordinating subagents. - `enabled` boolean, required: Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents` integer, nullable, required: Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `environment` union, required: Environment selection saved before an invocation creates its session. - object - `type` 'none', required: The type of the object. Always `none`. - object: Hosted environment selection with confidential setup commands and variables omitted. - `type` 'openai_hosted', required: The type of the object. Always `openai_hosted`. - `environment_id` string, nullable, required: An existing environment reference, or null when provisioning a new environment. - `environment_template_id` string, nullable, required: A template reference, or null when no template is selected. - `container_size` 'small' | 'medium' | 'large', required: The effective CPU and memory tier of an OpenAI-hosted environment. - `packages` EnvironmentPackagesResource, required: Packages installed in an OpenAI-hosted environment. - … - `network` NetworkPolicyResource, required: Network access for an OpenAI-hosted environment. - … - `desktop` DesktopResource, required: The effective desktop configuration for an OpenAI-hosted environment. - … - `capability_directories` string[], nullable, required: Directory overrides, or null to inherit the template or creation default. - `skills` HostedTemplateSkillResource[], nullable, required: Skill overrides, excluding archive contents, or null to inherit. - … - `plugins` HostedPluginResource[], nullable, required: Plugin overrides, excluding archive contents, or null to inherit. - … - `files` HostedTemplateFileResource[], nullable, required: File overrides, excluding contents, or null to inherit. - … - object - `type` 'self_hosted', required: The type of the object. Always `self_hosted`. - `environment_id` string, nullable, required: An existing registration, or null to create a session-owned environment. - `workspace_directory` string, required: The absolute project directory in the environment. - `capability_directories` string[], required: Directories that expose capabilities to the agent. - `input` InputMessageResource2[], required: Initial input delivered to each new session. - `type` 'message', required: The type of the input item. Always `message`. - `role` 'user', required: The role of the message author. Always `user`. - `content` InputContentResource[], required: The content of the message. - union: User-provided content recorded in a session item. - … - `vault_ids` string[], required: Vaults made available to each new session. - `metadata` object, required: Metadata attached to each new session. - object - `type` 'existing_session', required: The type of the object. Always `existing_session`. - `session_id` string, required: The session receiving each invocation. - `instructions` string, required: Saved instructions delivered as an automation notification. - `metadata` object, required: Custom string key-value pairs attached to the automation. - `created_by` union, required: How the automation was created, independently of how an invocation started. - object - `type` 'developer', required: The type of the object. Always `developer`. - object - `type` 'agent', required: The type of the object. Always `agent`. - `session_id` string, required: The creator session, which is also the automation's target. - `tool_call_id` string, required: The tool call that created the automation. - `expression` string, required: The cron expression determining scheduled occurrences. - `timezone` string, required: The timezone used to interpret the expression. - `status` 'active' | 'paused', required - object: Fields shared by periodic and one-time automations. - `type` 'once', required: The type of the object. Always `once`. - `id` string, required: The automation ID. - `object` 'agent.automation', required: Always `agent.automation`. - `created_at` integer, required: The creation time as a Unix timestamp in seconds. - `name` string, required: The automation's display name. - `target` union, required: Saved target configuration, excluding confidential request-only values. - object - `type` 'new_session', required: The type of the object. Always `new_session`. - `agent_id` string, nullable, required: The saved agent reference, or null when an inline agent is configured. - `agent` AutomationAgentConfigResource, required: Inline agent configuration without a generated session-local identity. - `model` string, required: The requested model name. - `reasoning` ReasoningResource, required: The reasoning configuration used by an agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required: The amount of reasoning effort used by an agent. - `summary` 'concise' | 'detailed' | 'auto', required: The reasoning summary format requested from an agent. - `text` TextResource, required: The text configuration used by an agent. - `format` union, required: The effective output format for generated text. - … - `verbosity` 'low' | 'medium' | 'high', required: The amount of text produced by an agent. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast', required: The service-tier policy configured for an agent. - `instructions` string, nullable, required: Custom instructions, or null when absent. - `tools` AgentToolResource[], required: Configured tools, excluding confidential credentials. - union: A tool available to the agent. - … - `multi_agent` MultiAgentConfigResource, required: The resolved configuration for creating and coordinating subagents. - `enabled` boolean, required: Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents` integer, nullable, required: Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `environment` union, required: Environment selection saved before an invocation creates its session. - object - `type` 'none', required: The type of the object. Always `none`. - object: Hosted environment selection with confidential setup commands and variables omitted. - `type` 'openai_hosted', required: The type of the object. Always `openai_hosted`. - `environment_id` string, nullable, required: An existing environment reference, or null when provisioning a new environment. - `environment_template_id` string, nullable, required: A template reference, or null when no template is selected. - `container_size` 'small' | 'medium' | 'large', required: The effective CPU and memory tier of an OpenAI-hosted environment. - `packages` EnvironmentPackagesResource, required: Packages installed in an OpenAI-hosted environment. - … - `network` NetworkPolicyResource, required: Network access for an OpenAI-hosted environment. - … - `desktop` DesktopResource, required: The effective desktop configuration for an OpenAI-hosted environment. - … - `capability_directories` string[], nullable, required: Directory overrides, or null to inherit the template or creation default. - `skills` HostedTemplateSkillResource[], nullable, required: Skill overrides, excluding archive contents, or null to inherit. - … - `plugins` HostedPluginResource[], nullable, required: Plugin overrides, excluding archive contents, or null to inherit. - … - `files` HostedTemplateFileResource[], nullable, required: File overrides, excluding contents, or null to inherit. - … - object - `type` 'self_hosted', required: The type of the object. Always `self_hosted`. - `environment_id` string, nullable, required: An existing registration, or null to create a session-owned environment. - `workspace_directory` string, required: The absolute project directory in the environment. - `capability_directories` string[], required: Directories that expose capabilities to the agent. - `input` InputMessageResource2[], required: Initial input delivered to each new session. - `type` 'message', required: The type of the input item. Always `message`. - `role` 'user', required: The role of the message author. Always `user`. - `content` InputContentResource[], required: The content of the message. - union: User-provided content recorded in a session item. - … - `vault_ids` string[], required: Vaults made available to each new session. - `metadata` object, required: Metadata attached to each new session. - object - `type` 'existing_session', required: The type of the object. Always `existing_session`. - `session_id` string, required: The session receiving each invocation. - `instructions` string, required: Saved instructions delivered as an automation notification. - `metadata` object, required: Custom string key-value pairs attached to the automation. - `created_by` union, required: How the automation was created, independently of how an invocation started. - object - `type` 'developer', required: The type of the object. Always `developer`. - object - `type` 'agent', required: The type of the object. Always `agent`. - `session_id` string, required: The creator session, which is also the automation's target. - `tool_call_id` string, required: The tool call that created the automation. - `run_at` integer, required: The Unix timestamp, in seconds, of the scheduled occurrence. - `status` 'active' | 'paused' | 'completed', required ## Other responses - `400`: The request was invalid. - `401`: Authentication or project context was missing. - `403`: The API key lacks the required permission. - `404`: The requested session or event was not found. - `409`: The request conflicted with the current session state. - `500`: An internal error occurred. - `503`: The service is temporarily unavailable. ## Changes - **2026-10-23** `adcff4143658`: 1 info - endpoint added [Operation history](https://skmtc.dev/openai/apis/openapi/changes/agents/automations/post.md) --- [API](https://skmtc.dev/openai/apis/openapi.md) - [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/openai/apis/openapi/revisions/b7f3ab500153?raw)