Trigger ChatGPT Workspace Agents via API from external systems

Trigger a Workspace Agent from the API

Workspace Agents let teams save repeatable work in ChatGPT: instructions, connected context, app actions, approvals, and output format. API triggers let another system start that saved workflow when work begins outside ChatGPT.

In this notebook, you send one source event, confirm the trigger was accepted, and verify the result in the agent's destination. The API starts the run. The instructions, app permissions, and approval settings control what happens next.

API-triggered runs are asynchronous. The endpoint queues the run, but it does not return the completed agent response.

What you will build

By the end, you will have a saved Workspace Agent, an API channel with an agtch_... trigger ID, and a Python trigger call that can run live against your agent.

Prerequisites

Before running the live trigger cell, you need:

You need	Use this doc
Workspace Agents enabled in a supported ChatGPT workspace, plus permission to create and share agents	ChatGPT Workspace Agents guide
A saved Workspace Agent with one destination it can write to	Create and manage Workspace Agents
An API channel on that agent and its agtch_... trigger ID	Trigger workspace agent runs
A Workspace Agent access token with the Workspace Agents scope	Authenticate with Workspace Agent access tokens
A notebook or backend environment that can send HTTPS POST requests	This notebook uses Python's standard library. No OpenAI Platform SDK is required.

One async detail matters: the HTTP request returns before the agent finishes. The destination can be any connected app or surface the agent can write to, such as a channel, document, email, or ticket.

Check the Help Center for current plan and regional availability.

Architecture

The source system decides when work starts. The Workspace Agent decides how the saved workflow runs using its instructions, context, apps, and approvals.

The backend starts the run. The agent follows the saved workflow and writes the result.

1. Write the agent instructions

The API trigger only starts the run. The Workspace Agent instructions tell the agent what to do next.

Instructions decide	App setup decides
Which destination to use	Whether the app can access that destination
What output to write	Whether the write action is available
Whether to act immediately or ask first	Whether approval is required before writing

For this demo, the instructions should be narrow: read the source event, write one update to the destination, and include the request ID so you can verify it.

Use the instructions section to make the destination, write behavior, and approval expectations clear.

Test the exact behavior in Preview before adding the API trigger. Paste a sample message with a request ID, destination, and update text. If Preview cannot write to the destination, the API trigger will not either.

2. Connect one output destination

Choose one low-risk destination the agent can write to: a channel, document, email, ticket, or another connected app. Configure the app connection and decide whether writes should require approval before testing the API trigger.

Auto-approved writes are useful for low-risk demo destinations. Riskier writes should stay approval-gated.

Auth model	Use it when	Watch for
End-user account	Each person running the agent should use their own app permissions	API-triggered workflows may need the caller to have the right app access
Agent-owned account	The workflow needs a consistent shared connection, such as a team channel, shared document, or shared inbox	Use a service account when possible. Avoid personal accounts unless you understand the risk

3. Add an API channel

Open the agent in the Workspace Agent builder. Add an API channel, save the agent, copy the trigger ID, and confirm the ID starts with agtch_.

Share the agent with the user whose access token will call the API. The trigger ID goes in the API path. It is different from the agent name.

Use this API channel ID in the trigger endpoint.

4. Configure the live call

You need two values:

Value	Where it comes from
API trigger ID	The agent's API channel. It starts with agtch_....
Workspace Agent access token	ChatGPT Admin > Access tokens, with the Workspace Agents scope.

Use a Workspace Agent access token for https://api.chatgpt.com, not an OpenAI Platform API key. The token owner must be able to run the shared agent, or the API returns 403 Forbidden.

Store the token as a secret. Do not paste it into notebook code.

For a live run, export the values before opening the notebook:

export WORKSPACE_AGENT_TRIGGER_ID="agtch_..."
export WORKSPACE_AGENT_ACCESS_TOKEN="<workspace-agent-access-token>"
export WORKSPACE_AGENT_OUTPUT_DESTINATION="output-destination"

jupyter notebook  # or jupyter lab

WORKSPACE_AGENT_OUTPUT_DESTINATION is optional. It labels the destination in the trigger input; access still comes from the agent's connected app.

5. Send one source event

Keep the first input small: a source system sends an event, and the Workspace Agent writes one update to its destination.

Map the source event into plain text before calling the trigger endpoint. The API passes the event to the agent. The agent's saved instructions, app permissions, and approval settings control the write.

Use conversation_key when multiple events should continue the same agent conversation, such as several updates for the same request.

For retries, send an Idempotency-Key header. Reuse the same key only when retrying the same source event.

6. Trigger the agent from the API

Endpoint:

POST https://api.chatgpt.com/v1/workspace_agents/{id}/trigger

Required and recommended request fields:

Location	Field	Required	Description
Path	id	Yes	API trigger ID from the agent's API channel, in agtch_... format
Header	Authorization	Yes	Bearer credential using the Workspace Agent access token
Header	Content-Type	Yes	Use application/json
Header	Idempotency-Key	Recommended	Stable key for retrying the same source event
Body	input	Yes	Message text passed to the agent as trigger input
Body	conversation_key	No	Caller-defined stable ID for continuing the same agent conversation

A 202 Accepted confirms the trigger was accepted for processing. It does not mean the agent finished. The API returns no body, no public run ID, and no final agent output.

For the first live run, look for three things: HTTP status: 202, a unique request ID, and an update in the destination that starts with Workspace Agent API demo received:.

If the trigger succeeds but nothing is written, debug the agent configuration, not the HTTP request. Usually one of these is missing: destination instructions, app permission, app authentication, or the intended approval setting.

For repeated notebook tests, keep the generated request ID and idempotency key unique. Reusing the same Idempotency-Key for the same source event can return the original accepted outcome instead of enqueueing a new run.

7. Adapt the call for a backend worker

The live call above is the minimal test. The helper below wraps the same request shape for a backend worker, scheduled job, or workflow engine.

Keep conversation_key and Idempotency-Key stable for the same source event so retries do not enqueue duplicate runs.

In production, log the source request ID, trigger ID, idempotency key, timestamp, and HTTP status. Do not log the access token or sensitive request details.

8. Verify the destination action

The API does not return the completed response, so verify the action in the agent's destination. Check the exact destination named in the trigger input or saved in the agent instructions.

The HTTP response tells you the trigger was received. Verify the actual work in the destination.

Search the configured destination for the generated request ID printed by the live trigger cell. The update should start with:

Workspace Agent API demo received: DEMO-20260618010101

At that point, the end-to-end path is working: trigger, token, sharing, instructions, app permissions, and approval behavior.

If the trigger succeeds but no output appears, check these first:

Check	What to verify
Preview	Paste the exact agent_input text and confirm the agent writes to the destination
Destination	Set WORKSPACE_AGENT_OUTPUT_DESTINATION to the exact destination name before starting the kernel
Permissions	Confirm the connected app can write to that destination during API-triggered runs
Approval	Confirm the write action is auto-approved if the demo should write automatically
Access	Confirm the token owner can run the agent and the saved API channel is active

From there, replace source_event with any backend event. The API call stays the same. The agent owner updates the instructions, destination, and approval behavior in ChatGPT.

Before rollout, run a small test matrix:

Test	Expected result
Happy path	Agent writes Workspace Agent API demo received: <request_id> to the configured destination
Missing request ID	Agent asks for a request ID and does not write an ambiguous update
Duplicate retry with same idempotency key	API returns the original accepted outcome instead of enqueueing a second trigger event
Token from unshared user	API returns 403 Forbidden
Wrong trigger ID	API returns 404 Not Found
Agent or destination not runnable	API returns 409 Conflict

Error handling

The trigger endpoint can return:

Status	What it means	What to do
202 Accepted	Request accepted for processing	Verify the result in the configured destination
401 Unauthorized	Token is missing, expired, revoked, invalid, or the wrong credential type	Create a ChatGPT Workspace Agent access token from Admin > Access tokens with the Workspace Agents scope. Do not use an OpenAI Platform API key
403 Forbidden	The token is valid but cannot trigger this agent	Share the agent with the caller or use a token from an allowed user
404 Not Found	The trigger ID does not exist or is not visible to the caller	Confirm the agtch_ ID from the API channel
409 Conflict	The agent or API channel is not runnable	Save/publish the agent and confirm the API channel is active
202 Accepted, but no output appears	The trigger succeeded, but the agent did not write to the destination	Check instructions, app authentication, destination permissions, and write-approval settings

For transient network failures, retry with the same Idempotency-Key for the same source event. For a different source event, generate a new idempotency key.

Production checklist

Before expanding beyond a pilot, lock down four things:

Area	Check
Auth	Store and rotate the access token. Use a token owner that makes run attribution clear.
Access	Share the agent only with allowed users or groups. Confirm the connected app can write to the destination.
Behavior	Make destination, output format, and approval behavior explicit in the agent instructions.
Operations	Include source event IDs, monitor non-202 responses, and watch for missing output.

Auto-approve only low-risk writes. Keep sensitive writes approval-gated until the workflow is reviewed with the business owner.

When to use this pattern

Use API triggers when a business-owned Workspace Agent should do the work, but another system starts it.

Use this pattern when	Use another approach when
A non-technical owner should maintain the workflow instructions.	The caller needs the completed answer in the HTTP response.
Work starts from a form, ticket, CRM record, scheduled job, or backend event.	The source system needs low-latency synchronous behavior.
The result can be written to a connected app, channel, document, or email.	There is no durable destination for the agent output.
Instructions and approval settings can safely control the write behavior.	The workflow is high-impact and lacks review, audit, or rollback paths.

That is the ownership split: business teams refine the agent in ChatGPT, while engineering keeps the source-system trigger stable.

Adapt this pattern

Use the same pattern when work starts outside ChatGPT but should run through a reusable Workspace Agent:

Workflow	Source event	Agent output
Meeting follow-up	Meeting recording or transcript is ready	Action items and follow-up draft
Calendar-driven prep	Google Calendar event or upcoming-meeting schedule is found	Briefing document or prep summary
Inbound lead qualification	CRM lead or form submission	Account summary and sales task
Support escalation	High-priority ticket is created	Escalation summary and next steps
Employee support	Helpdesk ticket is opened	Triage answer or escalation route
Weekly reporting	Scheduled job finds new records	Summary document or team update

Start with one narrow workflow, one clear source event, and one output destination. After the agent behaves consistently, add more destinations, richer context, or additional approval-gated actions.

Further reading

• Building workspace agents in ChatGPT to complete repeatable, end-to-end work
• ChatGPT Workspace Agents for Enterprise and Business
• Trigger workspace agent runs
• Authenticate with Workspace Agent access tokens