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
GET  https://api.chatgpt.com/v1/workspace_agents/{id}/runs/{run_id}

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

run_id is the trigger run identifier returned by a beta trigger request, in an apirun_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 key return the original accepted outcome instead of adding a second trigger event to the queue.

Response

The API durably queues the trigger event and returns 202 Accepted with a link to the ChatGPT conversation:

{
  "conversation_url": "https://chatgpt.com/c/123"
}

The agent’s response cannot currently be retrieved through the API.

Track run status

With the beta header, the trigger response includes agent_trigger_run_id:

{
  "conversation_url": "https://chatgpt.com/c/123",
  "agent_trigger_run_id": "apirun_123"
}

Poll the run ID until it reaches a terminal status:

curl https://api.chatgpt.com/v1/workspace_agents/$API_TRIGGER_ID/runs/$RUN_ID \
  -H "Authorization: Bearer $AGENT_ACCESS_TOKEN"

The response describes the latest run state:

{
  "object": "workspace_agent.trigger_run",
  "id": "apirun_123",
  "status": "in_progress",
  "created_at": 1784763880,
  "agent_id": "agt_123",
  "api_trigger_id": "agtch_123",
  "conversation_url": "https://chatgpt.com/c/123",
  "error": null
}

completed and failed are terminal statuses. For failed runs, error.code can be dispatch_failed or run_failed.

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" \
  -H "OpenAI-Beta: workspace_agent_runs=v1" \
  -d '{
    "conversation_key": "email_thread_abc",
    "input": "Summarize the newest escalation and recommend next steps."
  }'

Expected response:

HTTP/1.1 202 Accepted

{
  "conversation_url": "https://chatgpt.com/c/123",
  "agent_trigger_run_id": "apirun_123"
}

Errors