Update an automation
POST
/agents/automations/{automation_id}Updates supplied fields; target and metadata replace the whole field.
Update an automation
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{}'200 — Example
{
"id": "id",
"created_at": 0,
"created_by": {
"type": "developer"
},
"expression": "expression",
"metadata": {
"foo": "string"
},
"name": "name",
"object": "agent.automation",
"status": "active",
"target": {
"agent": {
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"agent_id": "agent_id",
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user",
"type": "message"
}
],
"metadata": {
"foo": "string"
},
"type": "new_session",
"vault_ids": [
"string"
]
},
"timezone": "timezone",
"type": "periodic",
"pause_reason": "target_session_failed"
}Body ParametersJSON
run_at: optional integer
A future Unix timestamp in seconds; accepted only before a one-time scheduled invocation exists.
formatint64
Replaces the complete target, retaining its type and any creator session.
Replaces the complete target, retaining its type and any creator session.
One of the following: NewSession { environment, input, type, 4 more } Create a session for each invocation.
environment: EnvironmentParam The execution environment for each new session.
One of the following: None { type } Runs the agent without an execution environment.
type: "none" (default: "none") The type of the object. Always none.
OpenAIHosted { type, capability_directories, container_size, 10 more } An existing OpenAI-hosted environment or new inline/template-based hosted configuration.
type: "openai_hosted" (default: "openai_hosted") The type of the object. Always openai_hosted.
capability_directories: optional array of string or null Directories that contain capabilities exposed to the agent. Defaults to an empty list.
minItems0 maxItems16384 container_size: optional "small" or "medium" or "large" The hosted container size. Omission selects the medium tier.
One of the following: "small" "medium" "large" desktop: optional object or null Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled.
enabled: boolean Whether to provision the desktop and its browser proxy.
env: optional map[string] or null Environment variables made available to the agent.
environment_id: optional string An existing prewarmed environment. Cannot be combined with a template or inline configuration.
minLength9 maxLength256 environment_template_id: optional string A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy.
minLength0 maxLength64 files: optional array of HostedEnvironmentFileParam or null Files available before the agent starts. Defaults to an empty list.
minItems0 maxItems50 One of the following: FileID { file_id, path, type } A file previously uploaded through the OpenAI Files API.
file_id: string The ID of the uploaded file.
minLength1 maxLength256 path: string The absolute destination path inside /workspace.
minLength1 maxLength4096 type: "file_id" (default: "file_id") The type of the object. Always file_id.
Inline { data, path, type } A file supplied directly as standard-base64 data.
data: string The standard-base64-encoded file contents.
minLength0 maxLength6990508 path: string The absolute destination path inside /workspace.
minLength1 maxLength4096 type: "inline" (default: "inline") The type of the object. Always inline.
network: optional object or null Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled.
access: "enabled" or "disabled" or "restricted" The environment’s network access mode.
One of the following: "enabled" Allows unrestricted network access.
"disabled" Disables network access.
"restricted" Applies the configured domain restrictions.
allowed_domains: optional array of string or null Domains the environment may access when network access is restricted.
minItems0 maxItems16384 blocked_domains: optional array of string or null Domains blocked for both executor and browser when access is restricted. A nonempty list requires access: restricted and cannot be combined with nonempty allowed_domains. Wildcard domains are not supported.
minItems0 maxItems100 packages: optional object or null Packages to install in the environment. Defaults to empty package lists.
npm: optional array of string or null npm packages to install globally. Defaults to an empty list.
minItems0 maxItems16384 python: optional array of string or null Python packages to install. Defaults to an empty list.
minItems0 maxItems16384 system: optional array of string or null System packages to install. Defaults to an empty list.
minItems0 maxItems16384 plugins: optional array of HostedPluginParam or null Plugins provided as inline ZIP archives. Defaults to an empty list.
minItems0 maxItems32 description: string The plugin description declared in .codex-plugin/plugin.json.
minLength0 maxLength1048576 name: string The plugin name declared in .codex-plugin/plugin.json.
minLength1 maxLength64 source: InlineCapabilitySourceParam { data, media_type, type } Provides ZIP bytes encoded with standard base64.
data: string Standard-base64 encoded ZIP archive bytes.
minLength1 maxLength70254592 media_type: "application/zip" (default: "application/zip") The archive media type, always application/zip.
type: "base64" (default: "base64") The type of the object. Always base64.
type: "inline" (default: "inline") The type of the object. Always inline.
setup_commands: optional array of SetupCommandParam or null Ordered, confidential setup commands. Command bodies are never returned.
minItems0 maxItems16 command: string The shell command to execute.
minLength0 maxLength65536 cwd: optional string or null The absolute working directory. Defaults to /workspace.
minLength0 maxLength4096 skills: optional array of HostedSkillParam or null Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list.
minItems0 maxItems200 One of the following: SkillReference { skill_id, type, version } References a skill uploaded through the Skills API.
skill_id: string The ID of the skill created through /v1/skills.
minLength1 maxLength64 type: "skill_reference" (default: "skill_reference") The type of the object. Always skill_reference.
version: optional string or null The skill version, a positive integer or latest; omission selects the default.
minLength0 maxLength1048576 Inline { description, name, source, type } Supplies a skill ZIP directly in the session request.
description: string The skill description declared in SKILL.md.
minLength0 maxLength1048576 name: string The skill name declared in SKILL.md.
minLength1 maxLength64 source: InlineCapabilitySourceParam { data, media_type, type } Provides ZIP bytes encoded with standard base64.
data: string Standard-base64 encoded ZIP archive bytes.
minLength1 maxLength70254592 media_type: "application/zip" (default: "application/zip") The archive media type, always application/zip.
type: "base64" (default: "base64") The type of the object. Always base64.
type: "inline" (default: "inline") The type of the object. Always inline.
SelfHosted { type, workspace_directory, capability_directories } An application-hosted environment configured inline.
type: "self_hosted" (default: "self_hosted") The type of the object. Always self_hosted.
workspace_directory: string Absolute project directory inside the self-hosted environment.
minLength0 maxLength1048576 capability_directories: optional array of string or null Directories that contain capabilities exposed to the agent. Defaults to an empty list.
minItems0 maxItems16384 input: array of AgentSessionInputMessageParam { content, role, type } Initial user messages submitted with each new session.
minItems0 maxItems16384 content: array of InputContentParam The content of the message.
minItems0 maxItems16384 One of the following: InputText { text, type } Text input to the model.
text: string The text sent to the model.
minLength0 maxLength1048576 type: "input_text" (default: "input_text") The type of the object. Always input_text.
InputImage { image_url, type } Image input to the model.
image_url: string The URL of the image sent to the model.
minLength0 maxLength1048576 type: "input_image" (default: "input_image") The type of the object. Always input_image.
role: "user" (default: "user") The role of the message author. Always user.
type: optional "message" (default: "message") The type of the input item. Always message.
type: "new_session" (default: "new_session") The type of the object. Always new_session.
agent: optional { compaction, experimental, instructions, 6 more } Inline agent configuration. Provide exactly one of agent and agent_id.
compaction: optional object or null Context compaction settings. Omit to keep the current settings. A supplied object replaces the settings; null or an empty object uses blocking compaction.
async: optional boolean or null Whether to compact context in the background. Omission or null defaults to false. Set to true to enable background compaction. Background compaction may increase token usage.
experimental: optional { time_awareness } (default: {}) Experimental settings to merge by key. Omitted settings keep their current values.
time_awareness: optional boolean Whether to give the model periodic current-time reminders. Omit to keep the current setting.
instructions: optional string or null Additional instructions appended to the agent’s default base instructions. Omit to leave unchanged.
minLength0 maxLength1048576 model: optional string The model to use for the agent. The requested model name is preserved.
minLength0 maxLength1048576 multi_agent: optional MultiAgentConfigParam or null Configuration for creating and coordinating subagents.
enabled: boolean Whether subagent tools are enabled.
max_concurrent_subagents: optional integer Maximum number of subagents that may run concurrently. Defaults to 6.
formatint64 minimum1 maximum4294967295 reasoning: optional AgentReasoningParam or null Configuration for model reasoning. Omit to keep the current settings; pass null to reset to the model’s default effort.
effort: optional "none" or "minimal" or "low" or 4 more or null The amount of reasoning effort the model should use. Omission lets the model select it.
One of the following: "none" "minimal" "low" "medium" "high" "xhigh" "max" summary: optional "concise" or "detailed" or "auto" or null Controls whether the response includes a reasoning summary.
One of the following: "concise" Returns a concise reasoning summary when supported.
"detailed" Returns a detailed reasoning summary when supported.
"auto" Automatically selects the most detailed summary supported by the model.
service_tier: optional "auto" or "default" or "flex" or 3 more or null The service tier used for model requests.
One of the following: "auto" Selects the service tier automatically.
"default" Uses the default service tier.
"flex" Uses the flex service tier.
"priority" Uses the priority service tier.
"fast" Uses the fast service tier.
"ultrafast" Uses the ultrafast service tier.
text: optional AgentTextParam or null Configuration for text generated by the agent.
format: optional TextFormatParam or null The output format. Omission uses ordinary text ({"type": "text"}).
One of the following: Text { type } Generates ordinary text without a structured-output constraint.
type: "text" (default: "text") The type of the object. Always text.
JSONSchema { schema, type } Constrains generated text to a JSON Schema.
schema: map[unknown] The JSON Schema that generated text must match.
type: "json_schema" (default: "json_schema") The type of the object. Always json_schema.
verbosity: optional "low" or "medium" or "high" or null The amount of text the model should produce. Defaults to medium, matching Responses.
One of the following: "low" Produces less text.
"medium" Uses the default amount of text.
"high" Produces more text.
tools: optional array of AgentToolParam or null 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.
minItems0 maxItems16384 One of the following: Function { description, name, parameters, 3 more } A function defined by the application.
description: string A description of what the function does.
minLength0 maxLength1048576 name: string The name of the function.
minLength0 maxLength1048576 parameters: map[unknown] A JSON Schema object describing the function’s arguments.
type: "function" (default: "function") The type of the object. Always function.
async: optional boolean (default: false) Whether the agent continues without waiting for the function result. Defaults to false.
defer_loading: optional boolean (default: false) Whether this function is deferred and discovered through tool search. Defaults to false.
ToolSearch { type } Discovers deferred function tools and loads them into the model context.
type: "tool_search" (default: "tool_search") The type of the object. Always tool_search.
ProgrammaticToolCalling { type, enabled } Enables calling tools from model-generated code.
type: "programmatic_tool_calling" (default: "programmatic_tool_calling") The type of the object. Always programmatic_tool_calling.
enabled: optional boolean (default: true) Whether tools can be called from model-generated code. Defaults to true.
Mcp { server_label, transport, type, 5 more } Tools provided by a remote MCP server.
server_label: string A label used to identify the MCP server in tool calls.
minLength0 maxLength1048576 transport: McpTransportParam The transport used to connect to the MCP server.
One of the following: HTTP { server_url, type, authorization, headers } Connects to an MCP server over HTTP.
server_url: string The URL of the MCP server.
minLength0 maxLength1048576 type: "http" (default: "http") The type of the object. Always http.
authorization: optional string or null The authorization value sent to the MCP server, if any.
minLength0 maxLength1048576 headers: optional map[string] or null Additional HTTP headers sent to the MCP server.
Stdio { command, cwd, type, 3 more } Starts an MCP server as a local process.
command: string The command used to start the MCP server.
minLength0 maxLength1048576 cwd: string The working directory used to start the MCP server.
minLength0 maxLength1048576 type: "stdio" (default: "stdio") The type of the object. Always stdio.
args: optional array of string or null Arguments passed to the MCP server command.
minItems0 maxItems16384 env: optional map[string] or null Environment variables set for the MCP server process.
env_vars: optional array of string or null Environment variable names to inherit from the selected execution environment.
minItems0 maxItems16384 type: "mcp" (default: "mcp") The type of the object. Always mcp.
allowed_tools: optional array of string or null The MCP tools the agent may call. All server tools are allowed when omitted.
minItems0 maxItems16384 connection_origin: optional "service" or "environment" or null Selects where outbound MCP HTTP connections originate. Omitted or service uses the Managed Agents service network; environment uses the session’s selected environment.
One of the following: "service" Uses the Managed Agents service network.
"environment" Uses the session’s execution environment.
credential_id: optional string or null The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL.
minLength0 maxLength1048576 request_metadata: optional map[unknown] or null Metadata included with requests to this MCP server.
required: optional boolean (default: false) Whether this MCP server must initialize before the first turn. Defaults to false.
WebSearch { type, allowed_domains, context_size, 2 more } Web search.
type: "web_search" (default: "web_search") The type of the object. Always web_search.
allowed_domains: optional array of string or null Domains the search may include.
minItems0 maxItems16384 context_size: optional "low" or "medium" or "high" or null The amount of search context made available to the model. Defaults to medium.
One of the following: "low" "medium" "high" location: optional object or null Approximate location used to localize search results.
city: optional string or null The city name.
minLength0 maxLength1048576 country: optional string or null The two-letter ISO country code, such as US.
minLength0 maxLength1048576 region: optional string or null The region or state name.
minLength0 maxLength1048576 timezone: optional string or null The IANA timezone, such as America/Los_Angeles.
minLength0 maxLength1048576 mode: optional "disabled" or "cached" or "live" or null The source used for web search results. Defaults to live.
One of the following: "disabled" Disables web search.
"cached" Uses cached search results.
"live" Searches the live web.
ComputerUse { type, include_screenshots } Browser use in an OpenAI-hosted session.
type: "computer_use" (default: "computer_use") The type of the object. Always computer_use.
include_screenshots: optional boolean (default: false) Whether computer tool outputs include screenshots. Defaults to false.
Automations { type } Lets the agent manage its own scheduled wakeups.
type: "automations" (default: "automations") The type of the object. Always automations.
agent_id: optional string A saved agent ID. Provide exactly one of agent and agent_id.
minLength0 maxLength64 metadata: optional map[string] or null Metadata attached to each new session.
vault_ids: optional array of string or null The IDs of vaults made available to each new session.
minItems0 maxItems16384 ExistingSession { instructions, session_id, type } Deliver instructions to an existing session.
instructions: string Instructions delivered as an automation notification.
minLength0 maxLength1048576 session_id: string The session receiving each invocation.
minLength0 maxLength1048576 type: "existing_session" (default: "existing_session") The type of the object. Always existing_session.
Returns
Automation = PeriodicAutomation { id, created_at, created_by, 9 more } or OneTimeAutomation { id, created_at, created_by, 8 more } A saved automation and its schedule.
Automation = PeriodicAutomation { id, created_at, created_by, 9 more } or OneTimeAutomation { id, created_at, created_by, 8 more }
A saved automation and its schedule.
One of the following: PeriodicAutomation { id, created_at, created_by, 9 more } Fields shared by periodic and one-time automations.
id: string The automation ID.
minLength0 created_at: integer The creation time as a Unix timestamp in seconds.
formatint64 created_by: AutomationCreatedBy Service-recorded provenance; callers cannot supply this field.
One of the following: Developer { type } type: "developer" (default: "developer") The type of the object. Always developer.
Agent { session_id, tool_call_id, type } session_id: string The creator session, which is also the automation’s target.
minLength0 tool_call_id: string The tool call that created the automation.
minLength0 type: "agent" (default: "agent") The type of the object. Always agent.
expression: string The cron expression determining scheduled occurrences.
minLength0 metadata: map[string] Custom string key-value pairs attached to the automation.
name: string The automation’s display name.
minLength0 object: "agent.automation" (default: "agent.automation") Always agent.automation.
status: "active" or "paused" Whether scheduled delivery is active or paused.
One of the following: "active" "paused" target: AutomationTarget The session configuration or existing session receiving invocations.
One of the following: NewSession { agent, agent_id, environment, 4 more } agent: AutomationAgentConfig or null The inline agent configuration, or null when agent_id is configured.
instructions: string or null Custom instructions, or null when absent.
minLength0 model: string The requested model name.
minLength0 multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents } The configuration for creating and coordinating subagents.
enabled: boolean Whether subagent tools are enabled. Defaults to false.
max_concurrent_subagents: integer or null Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.
formatint64 minimum1 maximum4294967295 reasoning: AgentReasoning { effort, summary } The configured reasoning policy.
effort: "none" or "minimal" or "low" or 4 more or null The requested reasoning effort, or null when the model selects its own default.
One of the following: "none" "minimal" "low" "medium" "high" "xhigh" "max" summary: "concise" or "detailed" or "auto" or null The requested reasoning summary format, or null when summaries are disabled.
One of the following: "concise" Returns a concise reasoning summary when supported.
"detailed" Returns a detailed reasoning summary when supported.
"auto" Automatically selects the most detailed summary supported by the model.
service_tier: "auto" or "default" or "flex" or 3 more The configured service-tier policy.
One of the following: "auto" "default" "flex" "priority" "fast" "ultrafast" text: AgentText { format, verbosity } The configured output format and verbosity.
format: TextFormat The effective output format. Defaults to ordinary text.
One of the following: Text { type } Generates ordinary text without a structured-output constraint.
type: "text" (default: "text") The type of the object. Always text.
JSONSchema { schema, type } Constrains generated text to a JSON Schema.
schema: map[unknown] The JSON Schema that generated text must match.
type: "json_schema" (default: "json_schema") The type of the object. Always json_schema.
verbosity: "low" or "medium" or "high" The amount of text produced by the agent. Defaults to medium.
One of the following: "low" "medium" "high" tools: array of AgentTool Configured tools, excluding confidential credentials.
minItems0 maxItems2000 One of the following: Function { defer_loading, description, name, 3 more } A function defined by the application.
defer_loading: boolean Whether the function is deferred and discovered through tool search.
description: string A description of what the function does.
minLength0 name: string The name of the function.
minLength0 parameters: map[unknown] A JSON Schema object describing the function’s arguments.
type: "function" (default: "function") The type of the object. Always function.
async: optional boolean Whether the agent continues without waiting for the function result.
ProgrammaticToolCalling { enabled, type } Enables calling tools from model-generated code.
enabled: boolean Whether tools can be called from model-generated code.
type: "programmatic_tool_calling" (default: "programmatic_tool_calling") The type of the object. Always programmatic_tool_calling.
Mcp { allowed_tools, connection_origin, credential_id, 5 more } Tools provided by a remote MCP server.
allowed_tools: array of string or null The MCP tools the agent may call.
minItems0 maxItems2000 connection_origin: "service" or "environment" Where outbound MCP HTTP connections originate.
One of the following: "service" "environment" credential_id: string or null The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL.
minLength0 request_metadata: map[unknown] Metadata included with requests to this MCP server.
required: boolean Whether this MCP server must initialize before the first turn.
server_label: string A label used to identify the MCP server in tool calls.
minLength0 transport: McpTransport The transport used to connect to the MCP server.
One of the following: HTTP { server_url, type } Connects to an MCP server over HTTP.
server_url: string The URL of the MCP server.
minLength0 type: "http" (default: "http") The type of the object. Always http.
Stdio { args, command, cwd, 2 more } Starts an MCP server as a local process.
args: array of string Arguments passed to the MCP server command.
minItems0 maxItems2000 command: string The command used to start the MCP server.
minLength0 cwd: string The working directory used to start the MCP server.
minLength0 env_vars: array of string Environment variable names inherited from the execution environment.
minItems0 maxItems2000 type: "stdio" (default: "stdio") The type of the object. Always stdio.
type: "mcp" (default: "mcp") The type of the object. Always mcp.
WebSearch { allowed_domains, context_size, location, 2 more } Web search.
allowed_domains: array of string or null Allowed search domains, or null when the search is unrestricted.
minItems0 maxItems2000 context_size: "low" or "medium" or "high" The amount of search context made available to the model. Defaults to medium.
One of the following: "low" "medium" "high" location: object or null Approximate location used to localize search results, if provided.
city: string or null The city name.
minLength0 country: string or null The two-letter ISO country code, such as US.
minLength0 region: string or null The region or state name.
minLength0 timezone: string or null The IANA timezone, such as America/Los_Angeles.
minLength0 mode: "disabled" or "cached" or "live" The source used for web search results.
One of the following: "disabled" "cached" "live" type: "web_search" (default: "web_search") The type of the object. Always web_search.
ComputerUse { include_screenshots, type } Browser use in an OpenAI-hosted session.
include_screenshots: boolean Whether computer tool outputs include screenshots.
type: "computer_use" (default: "computer_use") The type of the object. Always computer_use.
Automations { type } Lets the agent manage its own scheduled wakeups.
type: "automations" (default: "automations") The type of the object. Always automations.
compaction: optional { async } The effective context compaction settings.
async: boolean Whether context is compacted in the background. Defaults to false.
experimental: optional { time_awareness } The effective experimental settings for the agent.
time_awareness: boolean Whether the model receives periodic current-time reminders.
agent_id: string or null The saved agent reference, or null when an inline agent is configured.
minLength0 environment: AutomationEnvironment Configuration or references used to select the execution environment.
One of the following: None { type } type: "none" (default: "none") The type of the object. Always none.
OpenAIHosted { capability_directories, container_size, desktop, 8 more } Hosted environment selection with confidential setup commands and variables omitted.
capability_directories: array of string or null Directory overrides, or null to inherit the template or creation default.
minItems0 maxItems2000 container_size: "small" or "medium" or "large" or null The configured container size, or null to use the creation default.
One of the following: "small" "medium" "large" desktop: object or null Desktop overrides, or null to inherit the template or creation default.
enabled: boolean Whether the environment provisions a desktop and browser proxy.
environment_id: string or null An existing environment reference, or null when provisioning a new environment.
minLength0 environment_template_id: string or null A template reference, or null when no template is selected.
minLength0 files: array of FileID or Inline or null File overrides, excluding contents, or null to inherit.
minItems0 maxItems2000 One of the following: FileID { file_id, path, type } A project-scoped Files API reference resolved separately for each session.
file_id: string The ID of the uploaded file.
minLength0 path: string The file’s absolute path inside the environment.
minLength0 type: "file_id" (default: "file_id") The type of the object. Always file_id.
Inline { path, size_bytes, type } Metadata for confidential inline file contents.
path: string The file’s absolute path inside the environment.
minLength0 size_bytes: integer The decoded size of the inline file in bytes.
formatint64 minimum0 type: "inline" (default: "inline") The type of the object. Always inline.
network: object or null Network overrides, or null to inherit the template or creation default.
access: "enabled" or "disabled" or "restricted" The environment’s network access mode.
One of the following: "enabled" Allows unrestricted network access.
"disabled" Disables network access.
"restricted" Applies the configured domain restrictions.
allowed_domains: array of string Domains the environment may access when network access is restricted.
minItems0 maxItems2000 packages: object or null Package overrides, or null to inherit the template or creation default.
npm: array of string npm packages installed globally in the environment.
minItems0 maxItems16384 python: array of string Python packages installed in the environment.
minItems0 maxItems16384 system: array of string System packages installed in the environment.
minItems0 maxItems16384 plugins: array of HostedPlugin or null Plugin overrides, excluding archive contents, or null to inherit.
minItems0 maxItems2000 description: string The installed plugin description.
minLength0 name: string The installed plugin name.
minLength0 type: "inline" (default: "inline") The type of the object. Always inline.
skills: array of SkillReference or Inline or null Skill overrides, excluding archive contents, or null to inherit.
minItems0 maxItems2000 One of the following: SkillReference { skill_id, type, version } A skill resolved afresh from the Skills API whenever a session starts.
skill_id: string The referenced skill ID.
minLength0 type: "skill_reference" (default: "skill_reference") The type of the object. Always skill_reference.
version: string or null The requested version selector, including latest.
minLength0 Inline { description, name, type } Safe metadata for an inline skill archive.
description: string The skill description declared in SKILL.md.
minLength0 name: string The skill name declared in SKILL.md.
minLength0 type: "inline" (default: "inline") The type of the object. Always inline.
type: "openai_hosted" (default: "openai_hosted") The type of the object. Always openai_hosted.
SelfHosted { capability_directories, environment_id, type, workspace_directory } capability_directories: array of string Directories that expose capabilities to the agent.
minItems0 maxItems2000 environment_id: string or null An existing registration, or null to create a session-owned environment.
minLength0 type: "self_hosted" (default: "self_hosted") The type of the object. Always self_hosted.
workspace_directory: string The absolute project directory in the environment.
minLength0 input: array of { content, role, type } Initial input delivered to each new session.
minItems0 maxItems2000 content: array of InputContent The content of the message.
minItems0 maxItems2000 One of the following: InputText { text, type } Text input recorded in a session item.
text: string The text supplied to the agent.
minLength0 type: "input_text" (default: "input_text") The type of the object. Always input_text.
InputImage { image_url, type } Image input recorded in a session item.
image_url: string The URL of the image supplied to the agent, which may be a base64-encoded data URL.
minLength0 type: "input_image" (default: "input_image") The type of the object. Always input_image.
role: "user" (default: "user") The role of the message author. Always user.
type: "message" (default: "message") The type of the input item. Always message.
metadata: map[string] Metadata attached to each new session.
type: "new_session" (default: "new_session") The type of the object. Always new_session.
vault_ids: array of string Vaults made available to each new session.
minItems0 maxItems2000 ExistingSession { instructions, session_id, type } instructions: string Saved instructions delivered as an automation notification.
minLength0 session_id: string The session receiving each invocation.
minLength0 type: "existing_session" (default: "existing_session") The type of the object. Always existing_session.
timezone: string The timezone used to interpret the expression.
minLength0 type: "periodic" (default: "periodic") The type of the object. Always periodic.
pause_reason: optional "target_session_failed" or null (default: "target_session_failed") Why the service paused this schedule, or null for other schedules.
OneTimeAutomation { id, created_at, created_by, 8 more } Fields shared by periodic and one-time automations.
id: string The automation ID.
minLength0 created_at: integer The creation time as a Unix timestamp in seconds.
formatint64 created_by: AutomationCreatedBy Service-recorded provenance; callers cannot supply this field.
One of the following: Developer { type } type: "developer" (default: "developer") The type of the object. Always developer.
Agent { session_id, tool_call_id, type } session_id: string The creator session, which is also the automation’s target.
minLength0 tool_call_id: string The tool call that created the automation.
minLength0 type: "agent" (default: "agent") The type of the object. Always agent.
metadata: map[string] Custom string key-value pairs attached to the automation.
name: string The automation’s display name.
minLength0 object: "agent.automation" (default: "agent.automation") Always agent.automation.
run_at: integer The Unix timestamp, in seconds, of the scheduled occurrence.
formatint64 status: "active" or "paused" or "completed" Completion means the schedule has finished, not the agent’s work.
One of the following: "active" "paused" "completed" target: AutomationTarget The session configuration or existing session receiving invocations.
One of the following: NewSession { agent, agent_id, environment, 4 more } agent: AutomationAgentConfig or null The inline agent configuration, or null when agent_id is configured.
instructions: string or null Custom instructions, or null when absent.
minLength0 model: string The requested model name.
minLength0 multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents } The configuration for creating and coordinating subagents.
enabled: boolean Whether subagent tools are enabled. Defaults to false.
max_concurrent_subagents: integer or null Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.
formatint64 minimum1 maximum4294967295 reasoning: AgentReasoning { effort, summary } The configured reasoning policy.
effort: "none" or "minimal" or "low" or 4 more or null The requested reasoning effort, or null when the model selects its own default.
One of the following: "none" "minimal" "low" "medium" "high" "xhigh" "max" summary: "concise" or "detailed" or "auto" or null The requested reasoning summary format, or null when summaries are disabled.
One of the following: "concise" Returns a concise reasoning summary when supported.
"detailed" Returns a detailed reasoning summary when supported.
"auto" Automatically selects the most detailed summary supported by the model.
service_tier: "auto" or "default" or "flex" or 3 more The configured service-tier policy.
One of the following: "auto" "default" "flex" "priority" "fast" "ultrafast" text: AgentText { format, verbosity } The configured output format and verbosity.
format: TextFormat The effective output format. Defaults to ordinary text.
One of the following: Text { type } Generates ordinary text without a structured-output constraint.
type: "text" (default: "text") The type of the object. Always text.
JSONSchema { schema, type } Constrains generated text to a JSON Schema.
schema: map[unknown] The JSON Schema that generated text must match.
type: "json_schema" (default: "json_schema") The type of the object. Always json_schema.
verbosity: "low" or "medium" or "high" The amount of text produced by the agent. Defaults to medium.
One of the following: "low" "medium" "high" tools: array of AgentTool Configured tools, excluding confidential credentials.
minItems0 maxItems2000 One of the following: Function { defer_loading, description, name, 3 more } A function defined by the application.
defer_loading: boolean Whether the function is deferred and discovered through tool search.
description: string A description of what the function does.
minLength0 name: string The name of the function.
minLength0 parameters: map[unknown] A JSON Schema object describing the function’s arguments.
type: "function" (default: "function") The type of the object. Always function.
async: optional boolean Whether the agent continues without waiting for the function result.
ProgrammaticToolCalling { enabled, type } Enables calling tools from model-generated code.
enabled: boolean Whether tools can be called from model-generated code.
type: "programmatic_tool_calling" (default: "programmatic_tool_calling") The type of the object. Always programmatic_tool_calling.
Mcp { allowed_tools, connection_origin, credential_id, 5 more } Tools provided by a remote MCP server.
allowed_tools: array of string or null The MCP tools the agent may call.
minItems0 maxItems2000 connection_origin: "service" or "environment" Where outbound MCP HTTP connections originate.
One of the following: "service" "environment" credential_id: string or null The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL.
minLength0 request_metadata: map[unknown] Metadata included with requests to this MCP server.
required: boolean Whether this MCP server must initialize before the first turn.
server_label: string A label used to identify the MCP server in tool calls.
minLength0 transport: McpTransport The transport used to connect to the MCP server.
One of the following: HTTP { server_url, type } Connects to an MCP server over HTTP.
server_url: string The URL of the MCP server.
minLength0 type: "http" (default: "http") The type of the object. Always http.
Stdio { args, command, cwd, 2 more } Starts an MCP server as a local process.
args: array of string Arguments passed to the MCP server command.
minItems0 maxItems2000 command: string The command used to start the MCP server.
minLength0 cwd: string The working directory used to start the MCP server.
minLength0 env_vars: array of string Environment variable names inherited from the execution environment.
minItems0 maxItems2000 type: "stdio" (default: "stdio") The type of the object. Always stdio.
type: "mcp" (default: "mcp") The type of the object. Always mcp.
WebSearch { allowed_domains, context_size, location, 2 more } Web search.
allowed_domains: array of string or null Allowed search domains, or null when the search is unrestricted.
minItems0 maxItems2000 context_size: "low" or "medium" or "high" The amount of search context made available to the model. Defaults to medium.
One of the following: "low" "medium" "high" location: object or null Approximate location used to localize search results, if provided.
city: string or null The city name.
minLength0 country: string or null The two-letter ISO country code, such as US.
minLength0 region: string or null The region or state name.
minLength0 timezone: string or null The IANA timezone, such as America/Los_Angeles.
minLength0 mode: "disabled" or "cached" or "live" The source used for web search results.
One of the following: "disabled" "cached" "live" type: "web_search" (default: "web_search") The type of the object. Always web_search.
ComputerUse { include_screenshots, type } Browser use in an OpenAI-hosted session.
include_screenshots: boolean Whether computer tool outputs include screenshots.
type: "computer_use" (default: "computer_use") The type of the object. Always computer_use.
Automations { type } Lets the agent manage its own scheduled wakeups.
type: "automations" (default: "automations") The type of the object. Always automations.
compaction: optional { async } The effective context compaction settings.
async: boolean Whether context is compacted in the background. Defaults to false.
experimental: optional { time_awareness } The effective experimental settings for the agent.
time_awareness: boolean Whether the model receives periodic current-time reminders.
agent_id: string or null The saved agent reference, or null when an inline agent is configured.
minLength0 environment: AutomationEnvironment Configuration or references used to select the execution environment.
One of the following: None { type } type: "none" (default: "none") The type of the object. Always none.
OpenAIHosted { capability_directories, container_size, desktop, 8 more } Hosted environment selection with confidential setup commands and variables omitted.
capability_directories: array of string or null Directory overrides, or null to inherit the template or creation default.
minItems0 maxItems2000 container_size: "small" or "medium" or "large" or null The configured container size, or null to use the creation default.
One of the following: "small" "medium" "large" desktop: object or null Desktop overrides, or null to inherit the template or creation default.
enabled: boolean Whether the environment provisions a desktop and browser proxy.
environment_id: string or null An existing environment reference, or null when provisioning a new environment.
minLength0 environment_template_id: string or null A template reference, or null when no template is selected.
minLength0 files: array of FileID or Inline or null File overrides, excluding contents, or null to inherit.
minItems0 maxItems2000 One of the following: FileID { file_id, path, type } A project-scoped Files API reference resolved separately for each session.
file_id: string The ID of the uploaded file.
minLength0 path: string The file’s absolute path inside the environment.
minLength0 type: "file_id" (default: "file_id") The type of the object. Always file_id.
Inline { path, size_bytes, type } Metadata for confidential inline file contents.
path: string The file’s absolute path inside the environment.
minLength0 size_bytes: integer The decoded size of the inline file in bytes.
formatint64 minimum0 type: "inline" (default: "inline") The type of the object. Always inline.
network: object or null Network overrides, or null to inherit the template or creation default.
access: "enabled" or "disabled" or "restricted" The environment’s network access mode.
One of the following: "enabled" Allows unrestricted network access.
"disabled" Disables network access.
"restricted" Applies the configured domain restrictions.
allowed_domains: array of string Domains the environment may access when network access is restricted.
minItems0 maxItems2000 packages: object or null Package overrides, or null to inherit the template or creation default.
npm: array of string npm packages installed globally in the environment.
minItems0 maxItems16384 python: array of string Python packages installed in the environment.
minItems0 maxItems16384 system: array of string System packages installed in the environment.
minItems0 maxItems16384 plugins: array of HostedPlugin or null Plugin overrides, excluding archive contents, or null to inherit.
minItems0 maxItems2000 description: string The installed plugin description.
minLength0 name: string The installed plugin name.
minLength0 type: "inline" (default: "inline") The type of the object. Always inline.
skills: array of SkillReference or Inline or null Skill overrides, excluding archive contents, or null to inherit.
minItems0 maxItems2000 One of the following: SkillReference { skill_id, type, version } A skill resolved afresh from the Skills API whenever a session starts.
skill_id: string The referenced skill ID.
minLength0 type: "skill_reference" (default: "skill_reference") The type of the object. Always skill_reference.
version: string or null The requested version selector, including latest.
minLength0 Inline { description, name, type } Safe metadata for an inline skill archive.
description: string The skill description declared in SKILL.md.
minLength0 name: string The skill name declared in SKILL.md.
minLength0 type: "inline" (default: "inline") The type of the object. Always inline.
type: "openai_hosted" (default: "openai_hosted") The type of the object. Always openai_hosted.
SelfHosted { capability_directories, environment_id, type, workspace_directory } capability_directories: array of string Directories that expose capabilities to the agent.
minItems0 maxItems2000 environment_id: string or null An existing registration, or null to create a session-owned environment.
minLength0 type: "self_hosted" (default: "self_hosted") The type of the object. Always self_hosted.
workspace_directory: string The absolute project directory in the environment.
minLength0 input: array of { content, role, type } Initial input delivered to each new session.
minItems0 maxItems2000 content: array of InputContent The content of the message.
minItems0 maxItems2000 One of the following: InputText { text, type } Text input recorded in a session item.
text: string The text supplied to the agent.
minLength0 type: "input_text" (default: "input_text") The type of the object. Always input_text.
InputImage { image_url, type } Image input recorded in a session item.
image_url: string The URL of the image supplied to the agent, which may be a base64-encoded data URL.
minLength0 type: "input_image" (default: "input_image") The type of the object. Always input_image.
role: "user" (default: "user") The role of the message author. Always user.
type: "message" (default: "message") The type of the input item. Always message.
metadata: map[string] Metadata attached to each new session.
type: "new_session" (default: "new_session") The type of the object. Always new_session.
vault_ids: array of string Vaults made available to each new session.
minItems0 maxItems2000 ExistingSession { instructions, session_id, type } instructions: string Saved instructions delivered as an automation notification.
minLength0 session_id: string The session receiving each invocation.
minLength0 type: "existing_session" (default: "existing_session") The type of the object. Always existing_session.
type: "once" (default: "once") The type of the object. Always once.
pause_reason: optional "target_session_failed" or null (default: "target_session_failed") Why the service paused this schedule, or null for other schedules.
Returns Examples
200 — Example
{
"id": "id",
"created_at": 0,
"created_by": {
"type": "developer"
},
"expression": "expression",
"metadata": {
"foo": "string"
},
"name": "name",
"object": "agent.automation",
"status": "active",
"target": {
"agent": {
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"agent_id": "agent_id",
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user",
"type": "message"
}
],
"metadata": {
"foo": "string"
},
"type": "new_session",
"vault_ids": [
"string"
]
},
"timezone": "timezone",
"type": "periodic",
"pause_reason": "target_session_failed"
}