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. When 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).
Streaming 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}/sessions
The 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
Path Parameters
ID of the agent to start a session on. Also accepts the reserved aliases gumball and analytics.
Body
The first user message for the session. Also accepted as message for backwards compatibility. When omitted, an idle session is created with no messages.
"Research Acme Corp and draft a brief."
Caller-supplied session ID. When omitted, the server generates one. If provided and the ID already exists, the request returns 409 session_already_exists.
"sess_xYz789AbCd"
Arbitrary key/value metadata attached to the session. Stored under metadata.client.
Must be false (or omitted) when calling api.gumloop.com. Set to true only when calling ws.gumloop.com (see the streaming section above).
