Skip to main content
POST
/
agents
/
{agent_id}
/
sessions
cURL
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",
    "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
    }
  },
  "queue_position": null
}

Documentation Index

Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

Path Parameters

​
agent_id
string
required

ID of the agent to start a session on.

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"

​
metadata
object

Arbitrary key/value metadata attached to the session. Stored under metadata.client.

​
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
​
queue_position
integer | null

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

Example:

null