Gumloop Sessions API
The Sessions API from Gumloop — 4 operation(s) for sessions.
OpenAPI Specification
openapi: 3.0.0
info:
title: Public Agents Sessions API
version: 1.0.0
servers:
- url: https://api.gumloop.com/api/v1
tags:
- name: Sessions
paths:
/agents/{agent_id}/sessions:
get:
summary: List sessions
description: 'List sessions for an agent with cursor-based pagination, optional filtering, and search.
'
operationId: listSessions
tags:
- Sessions
x-codeSamples:
- lang: bash
label: cURL
source: "curl 'https://api.gumloop.com/api/v1/agents/abc123DEFghiJKL/sessions?page_size=20' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n"
- lang: python
label: Python
source: "from gumloop import Gumloop\n\nclient = Gumloop(access_token=\"YOUR_ACCESS_TOKEN\")\n\nresponse = client.sessions.list(\"abc123DEFghiJKL\")\nfor session in response.sessions:\n print(session.id, session.state)\n"
parameters:
- in: path
name: agent_id
required: true
schema:
type: string
description: ID of the agent whose sessions to list.
- in: query
name: page_size
required: false
schema:
type: integer
default: 20
minimum: 1
maximum: 100
description: Number of sessions to return per page. Defaults to `20`, maximum `100`.
- in: query
name: cursor
required: false
schema:
type: string
description: Cursor for the next page of results. Use the `next_cursor` value from a previous response.
- in: query
name: search
required: false
schema:
type: string
description: Free-text search query to filter sessions by name or content. Also accepted as `search_query`.
- in: query
name: sort_order
required: false
schema:
type: string
description: Sort order for the results (e.g. `newest` or `oldest`).
- in: query
name: type
required: false
schema:
type: string
description: Filter sessions by type (e.g. `api`, `web`, `slack`).
- in: query
name: state
required: false
schema:
type: string
enum:
- processing
- completed
- failed
- queued
- idle
description: Filter sessions by state.
- in: query
name: creator_user_id
required: false
schema:
type: string
description: Filter sessions by the user who created them.
- in: query
name: trigger_id
required: false
schema:
type: string
description: Filter sessions by the trigger that initiated them.
responses:
'200':
description: A paginated list of sessions.
content:
application/json:
schema:
type: object
properties:
sessions:
type: array
items:
type: object
properties:
id:
type: string
example: sess_xYz789AbCd
agent_id:
type: string
example: abc123DEFghiJKL
name:
type: string
nullable: true
example: Research task
type:
type: string
nullable: true
example: api
messages:
type: array
items:
type: object
description: Messages are not included in list responses. Use the retrieve session endpoint to get the full message history.
created_at:
type: string
format: date-time
nullable: true
example: '2026-05-15T14:32:00Z'
state:
type: string
nullable: true
enum:
- processing
- completed
- failed
- queued
- idle
example: completed
agent_name:
type: string
nullable: true
example: Sales research agent
creator:
type: object
nullable: true
properties:
id:
type: string
nullable: true
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
email:
type: string
nullable: true
profile_picture:
type: string
nullable: true
next_cursor:
type: string
nullable: true
description: Cursor to pass as the `cursor` query parameter to retrieve the next page. `null` when there are no more results.
example: eyJzb3J0X3ZhbHVlIjoiMjAyNi0wNS0xNVQxNDozMjowMFoiLCJpbnRlcmFjdGlvbl9pZCI6InNlc3NfeFl6Nzg5QWJDZCIsInNvcnRfYnkiOiJuZXdlc3QifQ==
examples:
paginated:
summary: First page of sessions
value:
sessions:
- id: sess_xYz789AbCd
agent_id: abc123DEFghiJKL
name: Research task
type: api
messages: []
created_at: '2026-05-15T14:32:00Z'
state: completed
agent_name: Sales research agent
creator:
id: user_2b9d71f0
first_name: Ada
last_name: Lovelace
email: ada@example.com
profile_picture: null
- id: sess_AbC123dEfG
agent_id: abc123DEFghiJKL
name: Follow-up call
type: web
messages: []
created_at: '2026-05-14T09:15:00Z'
state: completed
agent_name: Sales research agent
creator:
id: user_2b9d71f0
first_name: Ada
last_name: Lovelace
email: ada@example.com
profile_picture: null
next_cursor: eyJzb3J0X3ZhbHVlIjoiMjAyNi0wNS0xNFQwOToxNTowMFoifQ==
'401':
description: Unauthorized — missing or invalid API key.
'403':
description: Forbidden — the caller does not have read access on the agent.
'404':
description: Agent not found.
'500':
description: Internal server error.
security:
- bearerAuth: []
post:
summary: Create session
description: '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`.
### 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.
'
operationId: createSession
tags:
- Sessions
x-codeSamples:
- lang: bash
label: cURL
source: "curl -X POST 'https://api.gumloop.com/api/v1/agents/abc123DEFghiJKL/sessions' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\"input\": \"Research Acme Corp and draft a brief.\"}'\n"
- lang: python
label: Python
source: "from gumloop import Gumloop\n\nclient = Gumloop(access_token=\"YOUR_ACCESS_TOKEN\")\n\nresponse = client.sessions.create(\n \"abc123DEFghiJKL\",\n input=\"Research Acme Corp and draft a brief.\",\n)\nprint(response.session.id, response.session.state)\n"
parameters:
- in: path
name: agent_id
required: true
schema:
type: string
description: ID of the agent to start a session on.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
input:
type: string
description: 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:
type: string
description: 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:
type: object
description: Arbitrary key/value metadata attached to the session. Stored under `metadata.client`.
stream:
type: boolean
default: false
description: Must be `false` (or omitted) when calling `api.gumloop.com`. Set to `true` only when calling `ws.gumloop.com` (see the streaming section above).
responses:
'201':
description: Idle session created. Returned when the request body has no `input` — a session stub is created and no agent run is started.
content:
application/json:
schema:
type: object
properties:
session:
type: object
properties:
id:
type: string
example: sess_xYz789AbCd
agent_id:
type: string
example: abc123DEFghiJKL
messages:
type: array
items:
type: object
created_at:
type: string
format: date-time
nullable: true
example: '2026-05-15T14:32:00Z'
state:
type: string
nullable: true
enum:
- processing
- completed
- failed
- queued
- idle
example: idle
agent_name:
type: string
nullable: true
example: Sales research agent
agent_team_id:
type: string
nullable: true
example: team_4f8c92ab
agent_creator_user_id:
type: string
nullable: true
example: user_2b9d71f0
agent_icon_url:
type: string
nullable: true
example: null
agent_tools:
type: array
description: Tools available to the agent. Secret references are stripped before being returned.
items:
type: object
participants:
type: object
description: Map of participant user IDs to participant metadata.
creator:
type: object
nullable: true
description: Creator of the session. `null` when no creator is recorded.
properties:
id:
type: string
nullable: true
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
email:
type: string
nullable: true
profile_picture:
type: string
nullable: true
queue_position:
type: integer
nullable: true
description: Position in the per-agent queue. Populated only when the session was queued; otherwise `null`.
example: null
examples:
idle:
summary: Idle session created (no input)
value:
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
'202':
description: Session created and the first message was enqueued. Returned when `input` is provided. `queue_position` is set only when the session was queued behind concurrent runs.
content:
application/json:
schema:
type: object
properties:
session:
type: object
properties:
id:
type: string
example: sess_xYz789AbCd
agent_id:
type: string
example: abc123DEFghiJKL
messages:
type: array
items:
type: object
properties:
id:
type: string
nullable: true
example: msg_a1b2c3
role:
type: string
nullable: true
example: user
content:
type: string
nullable: true
example: Research Acme Corp and draft a brief.
created_at:
type: string
format: date-time
nullable: true
example: '2026-05-15T14:32:00Z'
creator_id:
type: string
nullable: true
example: user_2b9d71f0
parts:
type: array
nullable: true
items:
type: object
created_at:
type: string
format: date-time
nullable: true
example: '2026-05-15T14:32:00Z'
state:
type: string
nullable: true
enum:
- processing
- completed
- failed
- queued
- idle
example: processing
agent_name:
type: string
nullable: true
example: Sales research agent
agent_team_id:
type: string
nullable: true
example: team_4f8c92ab
agent_creator_user_id:
type: string
nullable: true
example: user_2b9d71f0
agent_icon_url:
type: string
nullable: true
example: null
agent_tools:
type: array
description: Tools available to the agent. Secret references are stripped before being returned.
items:
type: object
participants:
type: object
description: Map of participant user IDs to participant metadata.
creator:
type: object
nullable: true
description: Creator of the session. `null` when no creator is recorded.
properties:
id:
type: string
nullable: true
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
email:
type: string
nullable: true
profile_picture:
type: string
nullable: true
queue_position:
type: integer
nullable: true
description: Position in the per-agent queue. Populated only when the session was queued; otherwise `null`.
example: null
examples:
processing:
summary: Message enqueued and processing
value:
session:
id: sess_xYz789AbCd
agent_id: abc123DEFghiJKL
messages:
- id: msg_a1b2c3
role: user
content: Research Acme Corp and draft a brief.
created_at: '2026-05-15T14:32:00Z'
creator_id: user_2b9d71f0
parts: null
created_at: '2026-05-15T14:32:00Z'
state: processing
agent_name: Sales research agent
agent_team_id: team_4f8c92ab
agent_creator_user_id: user_2b9d71f0
agent_icon_url: null
agent_tools: []
participants:
user_2b9d71f0:
first_name: Ada
last_name: Lovelace
creator:
id: user_2b9d71f0
first_name: Ada
last_name: Lovelace
email: ada@example.com
profile_picture: null
queue_position: null
queued:
summary: Message queued behind concurrent runs
value:
session:
id: sess_xYz789AbCd
agent_id: abc123DEFghiJKL
messages:
- id: msg_a1b2c3
role: user
content: Research Acme Corp and draft a brief.
created_at: '2026-05-15T14:32:00Z'
creator_id: user_2b9d71f0
parts: null
created_at: '2026-05-15T14:32:00Z'
state: queued
agent_name: Sales research agent
agent_team_id: team_4f8c92ab
agent_creator_user_id: user_2b9d71f0
agent_icon_url: null
agent_tools: []
participants:
user_2b9d71f0:
first_name: Ada
last_name: Lovelace
creator:
id: user_2b9d71f0
first_name: Ada
last_name: Lovelace
email: ada@example.com
profile_picture: null
queue_position: 3
'400':
description: 'Bad request — invalid body, or `stream: true` was set on this host (use the streaming host).'
'401':
description: Unauthorized — missing or invalid API key.
'403':
description: Forbidden — the caller does not have read access on the agent.
'404':
description: Agent not found.
'409':
description: Conflict — a session with the supplied `session_id` already exists.
'429':
description: Rate limited — the agent's concurrency limit was exceeded.
'500':
description: Internal server error.
security:
- bearerAuth: []
/sessions/{session_id}:
get:
summary: Retrieve session
description: Retrieve a session by ID, including its messages, current state, agent metadata, and participants.
operationId: retrieveSession
tags:
- Sessions
x-codeSamples:
- lang: bash
label: cURL
source: "curl 'https://api.gumloop.com/api/v1/sessions/sess_xYz789AbCd' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n"
- lang: python
label: Python
source: "from gumloop import Gumloop\n\nclient = Gumloop(access_token=\"YOUR_ACCESS_TOKEN\")\n\nresponse = client.sessions.retrieve(\"sess_xYz789AbCd\")\nprint(response.session.state)\nfor message in response.session.messages:\n print(message.role, message.content)\n"
parameters:
- in: path
name: session_id
required: true
schema:
type: string
description: ID of the session to retrieve.
responses:
'200':
description: The session.
content:
application/json:
schema:
type: object
properties:
session:
type: object
properties:
id:
type: string
example: sess_xYz789AbCd
agent_id:
type: string
example: abc123DEFghiJKL
messages:
type: array
items:
type: object
properties:
id:
type: string
nullable: true
example: msg_a1b2c3
role:
type: string
nullable: true
example: user
content:
type: string
nullable: true
example: Research Acme Corp and draft a brief.
created_at:
type: string
format: date-time
nullable: true
example: '2026-05-15T14:32:00Z'
creator_id:
type: string
nullable: true
example: user_2b9d71f0
parts:
type: array
nullable: true
items:
type: object
created_at:
type: string
format: date-time
nullable: true
example: '2026-05-15T14:32:00Z'
state:
type: string
nullable: true
enum:
- processing
- completed
- failed
- queued
- idle
example: completed
agent_name:
type: string
nullable: true
example: Sales research agent
agent_team_id:
type: string
nullable: true
example: team_4f8c92ab
agent_creator_user_id:
type: string
nullable: true
example: user_2b9d71f0
agent_icon_url:
type: string
nullable: true
example: null
agent_tools:
type: array
description: Tools available to the agent. Secret references are stripped before being returned.
items:
type: object
participants:
type: object
description: Map of participant user IDs to participant metadata.
creator:
type: object
nullable: true
description: Creator of the session. `null` when no creator is recorded.
properties:
id:
type: string
nullable: true
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
email:
type: string
nullable: true
profile_picture:
type: string
nullable: true
queue_position:
type: integer
nullable: true
description: Position in the per-agent queue. Populated only when the session is currently queued; otherwise `null`.
example: null
examples:
completed:
summary: Completed session
value:
session:
id: sess_xYz789AbCd
agent_id: abc123DEFghiJKL
messages:
- id: msg_a1b2c3
role: user
content: Research Acme Corp and draft a brief.
created_at: '2026-05-15T14:32:00Z'
creator_id: user_2b9d71f0
parts: null
- id: msg_d4e5f6
role: assistant
content: Here is what I found about Acme Corp...
created_at: '2026-05-15T14:32:09Z'
creator_id: null
parts: null
created_at: '2026-05-15T14:32:00Z'
state: completed
agent_name: Sales research agent
agent_team_id: team_4f8c92ab
agent_creator_user_id: user_2b9d71f0
agent_icon_url: null
agent_tools: []
participants:
user_2b9d71f0:
first_name: Ada
last_name: Lovelace
creator:
id: user_2b9d71f0
first_name: Ada
last_name: Lovelace
email: ada@example.com
profile_picture: null
queue_position: null
'401':
description: Unauthorized — missing or invalid API key.
'403':
description: Forbidden — the caller does not have read access on the session.
'404':
description: Session not found.
'500':
description: Internal server error.
security:
- bearerAuth: []
/sessions/{session_id}/messages:
post:
summary: Send message
description: 'Append a user message to an existing session and resume the agent. The session must be in a terminal state (`idle`, `completed`, or `failed`); sending to a session that is `processing` or `queued` returns `409 interaction_not_in_terminal_state`.
### 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/sessions/{session_id}/messages
```
The response is `text/event-stream` (Server-Sent Events). With the Python SDK, `client.sessions.stream_message(session_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.
'
operationId: sendMessage
tags:
- Sessions
x-codeSamples:
- lang: bash
label: cURL
source: "curl -X POST 'https://api.gumloop.com/api/v1/sessions/sess_xYz789AbCd/messages' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\"input\": \"Now write a follow-up email.\"}'\n"
- lang: python
label: Python
source: "from gumloop import Gumloop\n\nclient = Gumloop(access_token=\"YOUR_ACCESS_TOKEN\")\n\nresponse = client.sessions.send(\n \"sess_xYz789AbCd\",\n input=\"Now write a follow-up email.\",\n)\nprint(response.session.state)\n"
parameters:
- in: path
name: session_id
required: true
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gumloop/refs/heads/main/openapi/gumloop-sessions-api-openapi.yml