Create session

curl -X POST 'https://api.gumloop.com/api/v1/agents/abc123DEFghiJKL/sessions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"input": "Research Acme Corp and draft a brief."}'

{
  "session": {
    "id": "sess_xYz789AbCd",
    "agent_id": "abc123DEFghiJKL",
    "name": "Incognito Chat",
    "incognito": true,
    "provenance": null,
    "messages": [],
    "created_at": "2026-05-15T14:32:00Z",
    "state": "idle",
    "agent_name": "Sales research agent",
    "agent_team_id": "team_4f8c92ab",
    "agent_creator_user_id": "user_2b9d71f0",
    "agent_icon_url": null,
    "agent_tools": [],
    "participants": {},
    "creator": {
      "id": "user_2b9d71f0",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com",
      "profile_picture": null
    },
    "usage": {
      "credit_cost": null,
      "tool_credit_cost": null,
      "flow_credit_cost": null,
      "input_tokens": null,
      "cached_input_tokens": null,
      "cache_write_input_tokens": null,
      "output_tokens": null,
      "reasoning_tokens": null
    }
  },
  "queue_position": null
}

POST

agents

{agent_id}

sessions

curl -X POST 'https://api.gumloop.com/api/v1/agents/abc123DEFghiJKL/sessions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"input": "Research Acme Corp and draft a brief."}'

{
  "session": {
    "id": "sess_xYz789AbCd",
    "agent_id": "abc123DEFghiJKL",
    "name": "Incognito Chat",
    "incognito": true,
    "provenance": null,
    "messages": [],
    "created_at": "2026-05-15T14:32:00Z",
    "state": "idle",
    "agent_name": "Sales research agent",
    "agent_team_id": "team_4f8c92ab",
    "agent_creator_user_id": "user_2b9d71f0",
    "agent_icon_url": null,
    "agent_tools": [],
    "participants": {},
    "creator": {
      "id": "user_2b9d71f0",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com",
      "profile_picture": null
    },
    "usage": {
      "credit_cost": null,
      "tool_credit_cost": null,
      "flow_credit_cost": null,
      "input_tokens": null,
      "cached_input_tokens": null,
      "cache_write_input_tokens": null,
      "output_tokens": null,
      "reasoning_tokens": null
    }
  },
  "queue_position": null
}

What happens without input, and which agent IDs work?

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).

How do incognito sessions work?

Set 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?

Send the optional 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?

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

Authorization

string

header

required

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

X-Gumloop-MCP-Token

string

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

agent_id

string

required

ID of the agent to start a session on. Also accepts the reserved aliases gumball and analytics.

Body

application/json

input

string

The first user message for the session. Also accepted as message for backwards compatibility. When omitted, an idle session is created with no messages.

Example:

"Research Acme Corp and draft a brief."

session_id

string

Caller-supplied session ID. When omitted, the server generates one. If provided and the ID already exists, the request returns 409 session_already_exists.

Example:

"sess_xYz789AbCd"

name

string

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}.

Maximum string length: 256

Example:

"Turn-on request #4821"

metadata

object

Caller-supplied key/value metadata, stored under metadata.client. Not verified client attribution.

incognito

boolean

default:false

Request incognito on either creation host, with or without input. Agent enforcement overrides false. A role-denied request returns 403 feature_restricted.

Example:

true

stream

boolean

default:false

Must be false (or omitted) when calling api.gumloop.com. Set to true only when calling ws.gumloop.com (see the streaming section above).

Response

Idle session created. Returned when the request body has no input — a session stub is created and no agent run is started.

session

object

Show child attributes

queue_position

integer | null

Position in the per-agent queue. Populated only when the session was queued; otherwise null.

Example:

null

Core concepts

Agents

Sessions

Skills

Artifacts

MCP

Browser profiles

Personal wiki

Evaluations

Organization evaluations

Brain

Teams

Models

File operations

Enterprise organization

Authorizations

Headers

Path Parameters

Body

Response