SPB Git forge
spboucher.ai ↗

spb/doc-api

Public
2commits 1branches 0releases
15.7 MBsize
maindefault branch
13 days agolast push
Python 88.3% TypeScript 7.6% Shell 4.1%
3.8 KB
View source Raw Blame History

# Workspace Agents API (ChatGPT workspace agents) — trigger runs

Status: DOCUMENTED · BETA (run polling: OpenAI-Beta: workspace_agent_runs=v1) · UNVERIFIED — requires a Workspace Agent access token from a ChatGPT Business/Enterprise/Edu workspace (not a platform API key); no live call attempted. Not part of the OpenAPI spec. Sources: Trigger workspace agent runs · Authenticate with Workspace Agent access tokens · Migrate from Agent Builder (option 2: create a workspace agent from an export). Last verified: 2026-09-18 (docs only).

# Purpose

Programmatically trigger a published ChatGPT workspace agent (built in ChatGPT → Agents studio) from an external system. The event is durably queued; the agent runs inside ChatGPT and its response is not retrievable through the API (only a conversation_url).

# Authentication

  1. Admin: enable Workspace agents and Allow users to create personal access tokens (Admin → Permissions & roles).
  2. User: ChatGPT → Admin → Access tokens → create token with scope Workspace Agents.
  3. Use Authorization: Bearer $AGENT_ACCESS_TOKEN on https://api.chatgpt.com. The token can only call Workspace Agents API operations.

# Endpoints (base https://api.chatgpt.com)

Method & path Purpose Request Response
POST /v1/workspace_agents/{id}/trigger queue a trigger event; id = API trigger id of the published API channel (agtch_…) JSON {input* (string), conversation_key (string, continue the same conversation across events)}; headers Idempotency-Key (optional; same key on same trigger returns the original outcome), OpenAI-Beta: workspace_agent_runs=v1 (optional, beta) 202 Accepted {conversation_url}; with the beta header also agent_trigger_run_id (apirun_…)
GET /v1/workspace_agents/{id}/runs/{run_id} poll run status (beta) — workspace_agent.trigger_run {id, status, created_at, agent_id (agt_…), api_trigger_id (agtch_…), conversation_url, error}

Run status: queued → in_progress → (suspended waiting for an external action/tool) → completed | failed (terminal). error.code: dispatch_failed | run_failed.

Errors: 401 missing/expired/revoked/invalid token · 403 token lacks permission for that agent · 404 trigger/run not visible to the caller's workspace · 409 channel or agent not in a runnable state.

# Example (docs)

bash
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."}'
# HTTP/1.1 202 Accepted
# {"conversation_url":"https://chatgpt.com/c/123","agent_trigger_run_id":"apirun_123"}

# Relation to the platform Agents API

Workspace Agents API Agents API (/v1/agents)
Host api.chatgpt.com api.openai.com
Credential Workspace Agent access token (ChatGPT admin flow) project API key (api.agents.*)
Agent defined in ChatGPT Agents studio (natural language, connected apps) API (POST /v1/agents) or inline in a session
Output ChatGPT conversation (URL only) items/events/artifacts via API
Billing ChatGPT workspace plan API token/tool/container rates

Agent Builder workflows can be exported as Agents SDK code and pasted into the workspace-agent studio ("Please help me convert this workflow into an agent"); deterministic workflows may not migrate faithfully.