API integration guide

Interactive chat uses the OpenAI Platform Responses API and the secret OPENAI_API_KEY. The model is set with OPENAI_MODEL; if you don't set it, a documented full-size default (gpt-4.1) is used, and Administration → Settings shows which. Set it explicitly in production. OPENAI_RESEARCH_MODEL optionally sets the model for web research. Supervision runs use the ChatGPT Workspace Agents API and the secrets PROJECT_STEWARD_API_TOKEN and PROJECT_STEWARD_API_TRIGGER_ID. They never share secrets: the Workspace Agent API does not use OPENAI_API_KEY.

Add each value as a server-side secret in Lovable Cloud (Cloud → Secrets). Never paste a secret into chat, code, or a browser. PROJECT_STEWARD_API_TRIGGER_ID must look like agtch_….

The app sends POST /v1/workspace_agents/{trigger id}/trigger with a bearer token, the OpenAI-Beta header workspace_agent_runs=v1, a unique Idempotency-Key, and a body of conversation_key and input. Only HTTP 202 means accepted. The app stores the submitted input, the conversation link and the run id, then polls GET /v1/workspace_agents/{trigger id}/runs/{run id} until completed or failed.

The API exposes the run's status but not the agent's response, so the app shows a status and a link, never a reply.

Replies are generated from the project's authorised data using a versioned instruction set that is recorded with each reply. Proposed actions (up to five per reply) are validated against the fixed list of allowed kinds and saved as separate pending approvals; they are never executed automatically. Structured drafts are saved for review and never become records unless a person selects them.

Chat replies are not streamed, and the Workspace Agent cannot be used as an interactive chat.