Trigger workspace agent runs

Use the Workspace Agents API to programmatically trigger a published ChatGPT workspace agent through API.

This endpoint is designed to integrate with workflows where an external system needs to trigger an agent outside of the ChatGPT UI and third party triggers offered.

Endpoint

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

id is the stable public API trigger identifier for the published API channel, in a agtch_XXX format.

Authentication

Authenticate with a Workspace Agent access token:

Authorization: Bearer $AGENT_ACCESS_TOKEN

See Authenticate with Workspace Agent access tokens for how to provision a token.

Request body

{
  "conversation_key": "email_thread_abc",
  "input": "Summarize the customer escalation and recommend a response."
}

Fields

To safely retry the same trigger event, send an optional Idempotency-Key header. Reuse the same key only when retrying the same event. Requests to the same API trigger with the same idempotency key return the original accepted outcome instead of enqueueing a second trigger event.

Response

The API durably queues the trigger event and returns 202 Accepted with no response body. It does not return a public run ID, and the agent response cannot currently be retrieved through the API. Support for retrieving agent responses is coming soon.

Example

curl -i https://api.chatgpt.com/v1/workspace_agents/agtch_complaints_123/trigger \
  -X POST \
  -H "Authorization: Bearer $AGENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "email_thread_abc",
    "input": "Summarize the newest escalation and recommend next steps."
  }'

Expected response:

HTTP/1.1 202 Accepted

Errors