How to Trigger a ChatGPT Workspace Agent via API

A practical field guide from Automation Ace.

Short answer: to trigger a ChatGPT workspace agents run via API, add an API channel to the agent in ChatGPT, publish it, and copy its trigger ID (it starts with agtch_). Create a Workspace Agent access tokens with the Workspace Agents scope in ChatGPT Admin, then send POST https://api.chatgpt.com/v1/workspace_agents/{id}/trigger with Authorization: Bearer <token> and a JSON body containing input (and optionally conversation_key). The API queues the run and returns 202 Accepted with a conversation_url; add the header OpenAI-Beta: workspace_agent_runs=v1 to also get an agent_trigger_run_id you can poll for status.

Details come from OpenAI's trigger runs documentation and related coverage at the time of writing. Run status polling was in beta, so confirm current fields before you build.

Short answer

1. Add an API channel to the workspace agent, publish, and copy the agtch_ trigger ID.
2. Create a Workspace Agent access token (Workspace Agents scope).
3. POST {"input": "..."} to the trigger URL with the bearer token.
4. Add OpenAI-Beta: workspace_agent_runs=v1 to get a run ID.
5. Save the run ID and conversation URL; the agent's answer is not returned by the API.
6. Have the agent deliver results through its own tools, and track run status.

What you are triggering

Workspace agents are shared agents that teams build inside ChatGPT on Business and Enterprise plans. An agent has instructions, tools and connected apps, and channels that decide how it is reached: the ChatGPT channel (where you can also add schedules), Slack, and an API channel. The API channel is what lets a CRM, help desk, form, script, or automation platform start a run.

For agents in general, see AI agents 101; for where workspace agents fit among platforms, see where to build AI agents.

Before you start

• A plan with workspace agents and the feature enabled by a workspace admin.
• Access token permission: an admin must allow personal access tokens for Workspace Agents.
• A published agent that the token's user can use.
• A secret store for the token: your server's secrets, CI, or automation platform.

Step 1: Add an API channel and publish

1. Open the agent in the workspace agent builder and go to its channels.
2. Add an API channel and save.
3. Copy the trigger ID. It should start with agtch_; this is the {id} in the URL.
4. Publish the draft. Changes to API triggers and schedules only go live after publishing.

Step 2: Create a Workspace Agent access token

1. In ChatGPT Admin, open Access tokens.
2. Create a token and select the Workspace Agents scope.
3. Copy it into your secret store.

These tokens only work for Workspace Agents API operations. OpenAI Platform API keys, and tokens created for other scopes, are not accepted. Workspace owners and admins can revoke tokens from the same page.

Step 3: Send the trigger request

curl -X POST "https://api.chatgpt.com/v1/workspace_agents/$TRIGGER_ID/trigger" \
  -H "Authorization: Bearer $WORKSPACE_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: workspace_agent_runs=v1" \
  -d '{
        "input": "New enterprise lead: Pat Lee, Prospect Co (40 seats). Research the company and draft a first reply for the account owner.",
        "conversation_key": "lead-crm_123"
      }'

Step 4: Read the 202 response

202 Accepted
{
  "conversation_url": "https://chatgpt.com/...",     // may be null
  "agent_trigger_run_id": "apirun_..."               // only with the OpenAI-Beta header
}

• 202 means queued, not finished. The agent runs in the background.
• conversation_url opens the run's conversation in ChatGPT. It can be null, so do not depend on it.
• agent_trigger_run_id (format apirun_...) is returned only with the beta header. Use it to check status; see how to monitor workspace agent runs by tracking run status.
• The agent's answer is not returned by the API at the time of writing.

Examples in Node and Python

// Node.js 18+. Keep the trigger ID and token in a secret store.
const res = await fetch(
  `https://api.chatgpt.com/v1/workspace_agents/${process.env.WA_TRIGGER_ID}/trigger`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.WA_TOKEN}`,
      "Content-Type": "application/json",
      "OpenAI-Beta": "workspace_agent_runs=v1",
    },
    body: JSON.stringify({
      input: `Support ticket #${ticket.id}: ${ticket.subject}\n\n${ticket.body}`,
      conversation_key: `ticket-${ticket.id}`,   // same ticket, same conversation
    }),
  }
);

if (res.status === 202) {
  const data = await res.json();
  await saveRun({ ticketId: ticket.id, runId: data.agent_trigger_run_id,
                  conversationUrl: data.conversation_url, status: "queued" });
} else {
  console.error(res.status, await res.text());   // 401, 403, 404, 409 ...
}

# Python 3 with requests
import os, requests

r = requests.post(
    f"https://api.chatgpt.com/v1/workspace_agents/{os.environ['WA_TRIGGER_ID']}/trigger",
    headers={
        "Authorization": f"Bearer {os.environ['WA_TOKEN']}",
        "OpenAI-Beta": "workspace_agent_runs=v1",
    },
    json={"input": "Summarize yesterday's escalations and post the summary to #support-leads."},
    timeout=30,
)
if r.status_code == 202:
    body = r.json()
    print(body.get("agent_trigger_run_id"), body.get("conversation_url"))
else:
    print(r.status_code, r.text)

No-code? See how to trigger a workspace agent from Zapier, Make, or n8n.

Writing a good input

• Lead with the job: “Research this lead and draft a reply,” then the data.
• Label the fields (Name, Company, Message) so the agent can find them.
• Include IDs and links back to the source record.
• Say where results go if the agent should post them somewhere specific.
• Leave out secrets and personal data the agent does not need.
• Treat inbound text as untrusted: customer messages can contain instructions aimed at the agent; keep the agent's own instructions and permissions tight.

Using conversation_key

conversation_key is a value you choose that stays stable across related triggers, such as ticket-4821 or an email thread ID. Reusing it keeps those triggers in one agent conversation, so a follow-up email on the same thread has the earlier context. Leave it out when each trigger is independent.

Getting results out of the agent

Because the API does not return the agent's output, design where the result goes:

• Agent tools: instruct the agent to post to Slack, update a CRM record, or write to a sheet with the apps it is connected to.
• The conversation: share conversation_url with the person who needs to review the run.
• Run status: poll the run ID to know when it completed or failed, then check the destination.

Pairing patterns: how to pair an AI agent with your existing automations.

Errors

Community reports at the time of writing also linked some persistent 409s to workspace settings or credit balances, so check with your workspace admin if a published agent keeps returning 409.

Security checklist

• Keep the token in a secret store; never in code, prompts, or shared automations.
• Use a token whose user has access only to the agents it needs.
• Limit the agent's connected apps and actions; require approval for sending, paying, or deleting.
• Deduplicate triggers so a retried webhook does not start two runs; see why a webhook fires twice.
• Revoke tokens when people leave or integrations change.

Framework: permissions, approvals, and audit trails for AI agents.

Workspace Agents API vs the OpenAI Platform API

Anthropic offers a similar pattern for Claude Code cloud agents; see how to trigger Claude Code agents via API. For the general design, see how to trigger an AI agent from an API or webhook.

Frequently asked questions

How do I trigger a ChatGPT workspace agent via API?

Add an API channel to the agent, publish it, and copy its agtch_ trigger ID. Create a Workspace Agent access token with the Workspace Agents scope in ChatGPT Admin, then POST a JSON body with input to https://api.chatgpt.com/v1/workspace_agents/{id}/trigger with Authorization: Bearer and the token.

What does the workspace agent trigger API return?

It queues the run and returns 202 Accepted with a conversation_url, which can be null. If you send the OpenAI-Beta: workspace_agent_runs=v1 header, it also returns an agent_trigger_run_id you can use to check run status. The agent’s output is not returned by the API.

Can I use an OpenAI API key to trigger a workspace agent?

No. The Workspace Agents API uses Workspace Agent access tokens created in ChatGPT Admin with the Workspace Agents scope. OpenAI Platform API keys are not accepted.

What is conversation_key in the workspace agent API?

It is an optional value you define that stays the same across related triggers, such as a ticket or email thread ID. Reusing it keeps those triggers in one agent conversation so later runs have earlier context.

Why does my workspace agent trigger return 409?

A 409 means the channel or agent is not in a runnable state, for example an unpublished draft or a disabled API channel or agent. Community reports also linked some persistent 409s to workspace settings or credits, so check with your admin.