Repository Public
1# Trigger workspace agent runs23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Use the Workspace Agents API to programmatically trigger a published ChatGPT6workspace agent through API.78This endpoint is designed to integrate with workflows where an external system9needs to trigger an agent outside of the ChatGPT UI and third party10triggers offered.1112## Endpoint1314```text15POST https://api.chatgpt.com/v1/workspace_agents/{id}/trigger16GET https://api.chatgpt.com/v1/workspace_agents/{id}/runs/{run_id}17```1819`id` is the stable public API trigger identifier for the published API channel,20in a `agtch_XXX` format.2122`run_id` is the trigger run identifier returned by a beta trigger request, in an23`apirun_XXX` format.2425## Authentication2627Authenticate with a Workspace Agent access token:2829```bash30Authorization: Bearer $AGENT_ACCESS_TOKEN31```3233See [Authenticate with Workspace Agent access tokens](https://developers.openai.com/workspace-agents/authentication)34for how to provision a token.3536## Request body3738```json39{40 "conversation_key": "email_thread_abc",41 "input": "Summarize the customer escalation and recommend a response."42}43```4445### Fields4647| Field | Type | Required | Description |48| ------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |49| `input` | string | Yes | Message text passed to the agent as trigger input. |50| `conversation_key` | string | No | Caller-defined stable identifier for continuing the same agent conversation across multiple trigger events. |5152To safely retry the same trigger event, send an optional `Idempotency-Key`53header. Reuse the same key only when retrying the same event. Requests to the54same API trigger with the same key return the original accepted outcome instead55of adding a second trigger event to the queue.5657## Response5859The API durably queues the trigger event and returns `202 Accepted` with a link60to the ChatGPT conversation:6162```json63{64 "conversation_url": "https://chatgpt.com/c/123"65}66```6768The agent's response cannot currently be retrieved through the API.6970## Track run status7172Run status polling is in beta. To receive a trigger run ID, include73 `OpenAI-Beta: workspace_agent_runs=v1` when you trigger the agent.7475With the beta header, the trigger response includes `agent_trigger_run_id`:7677```json78{79 "conversation_url": "https://chatgpt.com/c/123",80 "agent_trigger_run_id": "apirun_123"81}82```8384Poll the run ID until it reaches a terminal status:8586```bash87curl https://api.chatgpt.com/v1/workspace_agents/$API_TRIGGER_ID/runs/$RUN_ID \88 -H "Authorization: Bearer $AGENT_ACCESS_TOKEN"89```9091The response describes the latest run state:9293```json94{95 "object": "workspace_agent.trigger_run",96 "id": "apirun_123",97 "status": "in_progress",98 "created_at": 1784763880,99 "agent_id": "agt_123",100 "api_trigger_id": "agtch_123",101 "conversation_url": "https://chatgpt.com/c/123",102 "error": null103}104```105106| Status | Description |107| ------------- | ---------------------------------------------------------------- |108| `queued` | The trigger was accepted and is waiting to start. |109| `in_progress` | The agent is running. |110| `suspended` | The agent is waiting for an external action or tool. |111| `completed` | The agent run completed successfully. |112| `failed` | The agent run failed. See `error.code` for the failure category. |113114`completed` and `failed` are terminal statuses. For failed runs, `error.code`115can be `dispatch_failed` or `run_failed`.116117## Example118119```bash120curl -i https://api.chatgpt.com/v1/workspace_agents/agtch_complaints_123/trigger \121 -X POST \122 -H "Authorization: Bearer $AGENT_ACCESS_TOKEN" \123 -H "Content-Type: application/json" \124 -H "OpenAI-Beta: workspace_agent_runs=v1" \125 -d '{126 "conversation_key": "email_thread_abc",127 "input": "Summarize the newest escalation and recommend next steps."128 }'129```130131Expected response:132133```text134HTTP/1.1 202 Accepted135136{137 "conversation_url": "https://chatgpt.com/c/123",138 "agent_trigger_run_id": "apirun_123"139}140```141142## Errors143144| Status | When returned |145| ------------------ | ------------------------------------------------------------------------------------------ |146| `401 Unauthorized` | The bearer credential is missing, expired, revoked, or invalid. |147| `403 Forbidden` | The token is valid but does not have permission to trigger the requested workspace agent. |148| `404 Not Found` | The trigger or run does not exist or is not visible to the caller's workspace. |149| `409 Conflict` | The trigger could not be accepted because the channel or agent is not in a runnable state. |