Trigger ChatGPT Workspace Agents via API from external systems
A notebook for triggering a saved ChatGPT Workspace Agent from an external API, verifying the async run in its destination.
Why it matters
Enable external systems to programmatically start saved ChatGPT Workspace Agent workflows, allowing backend services to trigger automated agent runs that execute predefined instructions, access connected apps, and write outputs to designated destinations without manual intervention.
Outcomes
What it gets done
Send API POST requests with source events to trigger asynchronous agent runs
Map external system events into agent input messages with conversation continuity
Authenticate API calls using Workspace Agent access tokens with proper scopes
Configure agent destinations and approval workflows for automated writes to channels, documents, or tickets
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/oai-workspace-agents-api-trigger | bash Steps
Steps in the chain
Overview
Trigger a Workspace Agent from the API
A notebook for triggering a saved ChatGPT Workspace Agent from an external API - async request queuing, idempotent retries, and verifying the actual result in the agent's connected destination. Use it when a business-owned agent should do the work but another system starts it - not when the caller needs a synchronous answer or the workflow lacks review and rollback paths.
What it does
This notebook triggers a saved ChatGPT Workspace Agent from an external system via API, so another backend can start a repeatable workflow - instructions, connected context, app actions, approvals, and output format - that was configured inside ChatGPT. The trigger is asynchronous: the endpoint queues the run and returns before the agent finishes, with no completed response in the HTTP body, so success has to be verified by checking the agent's actual output destination (a channel, document, email, or ticket).
By the end you have a saved Workspace Agent, an API channel with an agtch_... trigger ID, and a working Python trigger call. Prerequisites: Workspace Agents enabled with permission to create and share them, a saved agent with one writable destination, an API channel and its trigger ID, and a Workspace Agent access token scoped for Workspace Agents (not an OpenAI Platform API key). The architecture splits ownership cleanly: the source system decides when work starts, while the agent's own instructions, connected apps, and approval settings decide how the saved workflow runs and what gets written.
Setup runs eight steps. Write narrow agent instructions - read the source event, write one update to the destination, include the request ID for verification - and test the exact behavior in Preview first, since if Preview can't write to the destination, the API trigger won't either. Connect one low-risk output destination, choosing between an end-user account (each caller uses their own app permissions) or an agent-owned service account (a consistent shared connection like a team channel), and decide whether writes need approval before testing. Add an API channel in the Workspace Agent builder, save, and copy the agtch_... trigger ID - distinct from the agent's name. Configure the live call with the trigger ID and a Workspace Agent access token, exported 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
Send one source event as plain text, using conversation_key to continue the same agent conversation across multiple events and an Idempotency-Key header to make retries of the same source event safe rather than duplicative. The actual trigger is a POST to https://api.chatgpt.com/v1/workspace_agents/{id}/trigger with the trigger ID in the path, a bearer token and application/json content type in headers, and the message text in the body's input field; a 202 Accepted confirms the request was queued, not that the agent finished - there's no body, run ID, or final output in the response. The same request shape adapts directly into a backend worker, scheduled job, or workflow engine, keeping conversation_key and Idempotency-Key stable per source event and logging the request ID, trigger ID, and HTTP status without ever logging the access token. Verification means searching the configured destination for the generated request ID; if the trigger succeeds but nothing appears, the fix is in the agent configuration (destination instructions, app permission, authentication, or approval setting), not the HTTP request itself.
The trigger endpoint's possible responses map directly to fixes: 401 Unauthorized means using a proper Workspace Agent access token instead of a Platform API key; 403 Forbidden means sharing the agent with the caller; 404 Not Found means confirming the agtch_ ID; 409 Conflict means the agent or channel isn't published/active; and a 202 with no visible output means checking instructions, app auth, and approval settings in that order. A production checklist locks down four areas before scaling past a pilot: rotating and clearly attributing the access token, sharing the agent only with allowed users, making destination/output/approval behavior explicit in instructions, and logging source event IDs while monitoring non-202 responses - auto-approving only genuinely low-risk writes and keeping anything sensitive approval-gated until reviewed with the business owner.
This pattern fits when a business-owned agent should do the work but another system starts it - a form, CRM record, scheduled job, or backend event - and the result can land in a durable connected destination; it does not fit when the caller needs the completed answer synchronously in the HTTP response, or the workflow is high-impact without review, audit, or rollback paths. The same pattern generalizes across several source-event-to-agent-output workflows: a ready meeting recording producing action items and a follow-up draft, an upcoming calendar event producing a briefing document, a new CRM lead or form submission producing an account summary and sales task, a high-priority ticket producing an escalation summary, a helpdesk ticket producing a triage answer or escalation route, and a scheduled job finding new records to produce a summary or team update. The recommended path is starting with one narrow workflow, one source event, and one destination, then expanding once the agent behaves consistently.
When to use - and when NOT to
Use it when a non-technical owner should maintain the workflow's instructions in ChatGPT while engineering keeps only the trigger stable, and the caller doesn't need a synchronous answer. Use a different approach when the source system needs low-latency synchronous behavior, there's no durable output destination, or the workflow is high-impact without established review and rollback paths.
Inputs and outputs
Input is a source event mapped to plain text plus the trigger ID, access token, and optional conversation/idempotency keys. Output is a queued run confirmed by a 202 Accepted, with the actual result verified in the agent's connected destination rather than in the API response.
Integrations
It calls the Workspace Agents API (api.chatgpt.com) using Python's standard library with no OpenAI Platform SDK required, and the agent itself connects to whatever destination app (channel, document, email, ticketing system) its instructions target.
Who it's for
Engineering teams wiring an external system (CRM, ticketing, scheduler) to trigger a business-owned ChatGPT Workspace Agent, while leaving the workflow's actual instructions and approval behavior owned by a non-technical business user.
Source README
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
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.