Create session
Create a new session for an agent. When input is provided, the message is enqueued and the agent begins processing — the response returns 202 with the session in processing or queued state.
What happens without input, and which agent IDs work?
What happens without input, and which agent IDs work?
input is omitted, an idle session stub is created and the response returns 201.agent_id also accepts the reserved aliases gumball and analytics, which resolve to your personal Gumball and analytics agents (created on first use).How do incognito sessions work?
How do incognito sessions work?
incognito: true with or without input on either creation host. Agent enforcement takes precedence, even if you omit the flag or send false. Without enforcement, requesting incognito requires the Incognito tasks permission; a denied request returns 403 feature_restricted.Unnamed incognito sessions use Incognito Chat, including sessions created with input. A supplied name is kept. Incognito does not save message content for history or search, but metadata and temporary message caches can remain.How do I record which MCP client created a session?
How do I record which MCP client created a session?
X-Gumloop-MCP-Token header on either creation host to record verified external client attribution. It supplements Authorization; it does not replace it. Token requirements and HTTP 400 errors are listed below.Session responses include nullable provenance, separate from unverified caller metadata stored under metadata.client. provenance.product is recognized from the OAuth redirect origin, not a supplied client name or User-Agent. Older sessions, requests without the header, and internal Gumloop tokens return provenance: null. Older grants and unrecognized origins can have product: null within a provenance object.How do I stream the response?
How do I stream the response?
api.gumloop.com only serves the non-streaming response above. To stream agent output as it’s produced, send the same request body (with stream: true) to the streaming host instead:POST https://ws.gumloop.com/api/v1/agents/{agent_id}/sessionsThe response is text/event-stream (Server-Sent Events). With the Python SDK, client.sessions.stream(agent_id, input="...") routes to ws.gumloop.com automatically and yields parsed StreamEvent objects.If you send stream: true to api.gumloop.com by mistake, the response is a 400 whose body contains the correct streaming host so you can retry against it.Authorizations
A personal API key or an OAuth 2.0 access token. Personal API keys also require the x-auth-key header with your user ID.
Headers
Optional Gumloop OAuth access token for verified external MCP attribution. Send the token value, without a Bearer prefix. It must have the same subject as the authenticated caller and an audience for this deployment. Invalid or mismatched tokens return HTTP 400 on both creation hosts.
Path Parameters
Body
Optional display name for the session. Leading and trailing whitespace is removed before the 1-256 character limit is applied, so an empty or whitespace-only value is rejected. A name you supply is kept; an unnamed incognito session defaults to Incognito Chat, while other unnamed sessions can receive an automatic title. Rename the session later with PATCH /sessions/{session_id}.
256"Turn-on request #4821"