Gumloop Public API
The Gumloop Public API triggers and manages flow runs, agents and sessions, an OpenAI-compatible chat/completions endpoint, Company Brain search, skills, artifacts, MCP servers, evaluations, files, teams, and organization admin.
OpenAPI Specification
openapi: 3.0.0
info:
title: Public API
version: 1.0.0
servers:
- url: 'https://api.gumloop.com/api/v1'
paths:
/start_pipeline:
post:
summary: Start flow run
description: This endpoint is used to trigger a flow run via API
operationId: startFlow
tags:
- Execution
requestBody:
required: true
description: >
In addition to the documented top-level fields, you may include any
additional inputs in the request body.
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The id for the user initiating the flow.
project_id:
type: string
description: (Optional) The id of the project within which the flow is executed.
saved_item_id:
type: string
description: The id for the saved flow.
required:
- saved_item_id
- user_id
additionalProperties:
description: >
Arbitrary input value. The property key is matched by name to
an Input node in the flow, and the entire body will be forwarded to any Webhook Input node.
example:
user_id: xxxxxxxxxxxxxx
saved_item_id: xxxxxxxxxxxxxx
recipient: recipient@gmail.com
subject: Example of an Email Subject Line
body: Example of the Text of an Email Body
topic: weekly update
responses:
'200':
description: Flow started successfully
content:
application/json:
schema:
type: object
properties:
run_id:
type: string
saved_item_id:
type: string
workbook_id:
type: string
url:
type: string
'400':
description: Bad request (missing or conflicting parameters)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (API key does not match)
'500':
description: Internal server error
security:
- bearerAuth: []
/kill_pipeline:
post:
summary: Kill flow run
description: This endpoint is used to kill a flow run and all its subflow runs.
operationId: killPipeline
tags:
- Execution
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
run_id:
type: string
description: The ID of the pipeline run to kill.
user_id:
type: string
description: The user ID. Required if project_id is not provided.
project_id:
type: string
description: The project ID. Required if user_id is not provided.
required:
- run_id
responses:
'200':
description: Pipeline killed successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
run_id:
type: string
description: The ID of the killed pipeline run.
'400':
description: Bad request (missing run_id)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (user does not have permission to kill this run)
'404':
description: Pipeline run not found
'500':
description: Internal server error
security:
- bearerAuth: []
/get_pl_run:
get:
summary: Retrieve run details
description: This endpoint can be used to poll for completion and retrieve final flow outputs. Output nodes must be used to retrieve outputs.
operationId: getAutomationRun
tags:
- Data Access
parameters:
- in: query
name: run_id
required: true
schema:
type: string
description: ID of the flow run to retrieve
- in: query
name: user_id
required: false
schema:
type: string
description: The id for the user initiating the flow. Required if project_id is not provided.
- in: query
name: project_id
required: false
schema:
type: string
description: The id of the project within which the flow is executed. Required if user_id is not provided.
responses:
'200':
description: Successful retrieval of flow run details
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The id for the user initiating the flow.
state:
type: string
enum: ['RUNNING', 'DONE', 'TERMINATING', 'FAILED', 'TERMINATED', 'QUEUED']
outputs:
type: object
description: JSON object where keys are the `output_name` parameters of your Gumloop Output nodes and the values are the values that get sent to your node.
created_ts:
type: string
format: date-time
description: Timestamp for when the flow was started.
finished_ts:
type: string
format: date-time
description: Timestamp for when the flow completed.
log:
type: array
items:
type: string
description: A list of log entries from your Gumloop flow run.
'400':
description: Bad request (missing run_id)
'404':
description: Flow run not found
security:
- bearerAuth: []
/list_workbooks:
get:
summary: List workbooks and their saved flows
operationId: listWorkbooks
tags:
- Data Access
parameters:
- in: query
name: user_id
required: false
schema:
type: string
description: The user ID for which to list workbooks. Required if project_id is not provided.
- in: query
name: project_id
required: false
schema:
type: string
description: The project ID for which to list workbooks. Required if user_id is not provided.
responses:
'200':
description: Successful retrieval of workbooks and their saved items
content:
application/json:
schema:
type: object
properties:
workbooks:
type: array
items:
type: object
properties:
workbook_id:
type: string
description: The id of the workbook.
name:
type: string
description: The name of the workbook.
description:
type: string
description: The description of the workbook.
created_ts:
type: string
format: date-time
description: Timestamp for when the workbook was created.
saved_items:
type: array
items:
type: object
properties:
saved_item_id:
type: string
description: The id of the saved flow.
name:
type: string
description: The name of the saved flow.
description:
type: string
description: The description of the saved flow.
created_ts:
type: string
format: date-time
description: Timestamp for when the saved flow was created.
description: List of workbooks and their associated saved flows
'400':
description: Bad request (missing parameters)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (API key does not match)
'500':
description: Internal server error
security:
- bearerAuth: []
/list_saved_items:
get:
summary: List saved flows
operationId: listSavedAutomations
tags:
- Data Access
parameters:
- in: query
name: user_id
required: false
schema:
type: string
description: The user ID to for which to list items. Required if project_id is not provided.
- in: query
name: project_id
required: false
schema:
type: string
description: The project ID for which to list items. Required if user_id is not provided.
responses:
'200':
description: Successful retrieval of saved items
content:
application/json:
schema:
type: object
properties:
saved_items:
type: array
items:
type: object
properties:
saved_item_id:
type: string
description: The id for the saved flow.
name:
type: string
description: The name of the saved flow.
description:
type: string
description: The description of the saved flow.
created_ts:
type: string
format: date-time
description: Timestamp for when the flow was started.
description: List of saved flows
'400':
description: Bad request (missing parameters)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (API key does not match)
'500':
description: Internal server error
security:
- bearerAuth: []
/get_inputs:
get:
summary: Retrieve input schema
operationId: getInputs
tags:
- Data Access
parameters:
- in: query
name: saved_item_id
required: true
schema:
type: string
description: The ID of the saved item for which to retrieve input schemas.
- in: query
name: user_id
required: false
schema:
type: string
description: User ID that created the flow. Required if project_id is not provided.
- in: query
name: project_id
required: false
schema:
type: string
description: Project ID that the flow is under. Required if user_id is not provided.
responses:
'200':
description: Successful retrieval of item input schemas
content:
application/json:
schema:
type: object
properties:
inputs:
type: array
items:
type: object
properties:
data_type:
type: string
enum: [string, file]
description: The type of the input, either a 'string' or a 'file'.
description:
type: string
nullable: true
description: A description of the input. Can be null if no desecription is given.
name:
type: string
description: The name of the input.
description: List of inputs for the saved item.
'400':
description: Bad request (missing parameters)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (API key does not match)
'404':
description: Saved item not found
security:
- bearerAuth: []
/get_plrun_saved_item_map:
get:
summary: Retrieve automation run history
description: This endpoint retrieves the run history for automations, either by workbook or saved item. Returns the 10 most recent runs.
operationId: getAutomationRunHistory
tags:
- Data Access
parameters:
- in: query
name: workbook_id
required: false
schema:
type: string
description: The ID of the workbook to retrieve run history for. Required if saved_item_id is not provided.
- in: query
name: saved_item_id
required: false
schema:
type: string
description: The ID of the saved item to retrieve run history for. Required if workbook_id is not provided.
- in: query
name: user_id
required: false
schema:
type: string
description: The user ID. Required if project_id is not provided.
- in: query
name: project_id
required: false
schema:
type: string
description: The project ID. Required if user_id is not provided.
responses:
'200':
description: Successful retrieval of automation run history
content:
application/json:
schema:
type: object
description: A map of saved item IDs to their recent run history, with up to 10 runs per saved item
'400':
description: Bad request (missing workbook_id or saved_item_id parameter)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (API key does not match)
'404':
description: Workbook not found
'500':
description: Internal server error
security:
- bearerAuth: []
/download_file:
post:
summary: Download file
operationId: downloadFile
tags:
- File Handling
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
file_name:
type: string
description: The name of the file to download.
run_id:
type: string
description: The ID of the flow run associated with the file.
saved_item_id:
type: string
description: The saved item ID associated with the file.
user_id:
type: string
description: Optional. The user ID associated with the flow run.
project_id:
type: string
description: Optional. The project ID associated with the flow run.
responses:
'200':
description: File downloaded successfully
'400':
description: Bad request (missing file_name or other required data)
'403':
description: Unauthorized (API key or user verification failed)
'500':
description: Internal server error (file download failed)
security:
- bearerAuth: []
/download_files:
post:
summary: Download multiple files
operationId: downloadFiles
tags:
- File Handling
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
file_names:
type: array
items:
type: string
description: An array of file names to download.
run_id:
type: string
description: The ID of the flow run associated with the files.
user_id:
type: string
description: The user ID associated with the files. Required if project_id is not provided.
project_id:
type: string
description: The project ID associated with the files. Required if user_id is not provided.
saved_item_id:
type: string
description: Optional. The saved item ID associated with the files.
responses:
'200':
description: Files downloaded successfully as a zip
content:
application/zip:
schema:
type: string
format: binary
'400':
description: Bad request (missing file_names or other required data)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (API key does not match)
'500':
description: Internal server error (file download failed)
security:
- bearerAuth: []
/upload_file:
post:
summary: Upload file
operationId: uploadFile
tags:
- File Handling
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
file_name:
type: string
description: The name of the file to be uploaded.
file_content:
type: string
format: byte
description: Base64 encoded content of the file.
user_id:
type: string
description: The user ID associated with the file. Required if project_id is not provided.
project_id:
type: string
description: The project ID associated with the file. Required if user_id is not provided.
responses:
'200':
description: File uploaded successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
file_name:
type: string
description: The name of the uploaded file.
'400':
description: Bad request (missing file or required parameters)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (API key does not match)
'500':
description: Internal server error (file upload failed)
security:
- bearerAuth: []
/upload_files:
post:
summary: Upload multiple files
operationId: uploadFiles
tags:
- File Handling
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
files:
type: array
items:
type: object
properties:
file_name:
type: string
description: The name of the file to be uploaded.
file_content:
type: string
format: byte
description: Base64 encoded content of the file.
user_id:
type: string
description: The user ID associated with the files. Required if project_id is not provided.
project_id:
type: string
description: The project ID associated with the files. Required if user_id is not provided.
responses:
'200':
description: All files uploaded successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
uploaded_files:
type: array
items:
type: string
description: Array of uploaded file names.
'207':
description: Partial success (some files failed to upload)
content:
application/json:
schema:
type: object
properties:
partial_success:
type: boolean
uploaded_files:
type: array
items:
type: string
description: Array of successfully uploaded file names.
failed_files:
type: array
items:
type: string
description: Array of file names that failed to upload.
'400':
description: Bad request (missing files or required parameters)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (API key does not match)
'500':
description: Internal server error (all file uploads failed)
security:
- bearerAuth: []
/get_audit_logs:
get:
summary: Retrieve audit logs
description: This endpoint retrieves audit logs for all users in an organization for a specified time period.
operationId: getOrganizationAuditLogs
tags:
- Organization
parameters:
- in: query
name: organization_id
required: true
schema:
type: string
description: The ID of the organization to retrieve audit logs for.
- in: query
name: user_id
required: true
schema:
type: string
description: Your user id -- you must be an organization admin to retrieve organization logs.
- in: query
name: start_time
required: true
schema:
type: string
format: date-time
description: Start timestamp for log filtering (ISO format).
- in: query
name: end_time
required: true
schema:
type: string
format: date-time
description: End timestamp for log filtering (ISO format).
- in: query
name: page
required: false
schema:
type: integer
default: 1
description: Page number for pagination.
- in: query
name: page_size
required: false
schema:
type: integer
default: 50
description: Number of records per page.
responses:
'200':
description: Successful retrieval of organization audit logs
content:
application/json:
schema:
type: object
properties:
audit_logs:
type: array
items:
type: object
properties:
event_id:
type: string
description: Unique identifier for the audit log event.
timestamp:
type: string
format: date-time
description: When the event occurred.
event_type:
type: string
description: Type of event that was logged.
user_id:
type: string
description: ID of the user who performed the action.
details:
type: string
description: Additional details about the event.
source_ip:
type: string
description: IP address from which the action was performed.
user_agent:
type: string
description: User agent information from the request.
total_count:
type: integer
description: Total number of matching audit logs.
page:
type: integer
description: Current page number.
page_size:
type: integer
description: Number of records per page.
total_pages:
type: integer
description: Total number of pages available.
'400':
description: Bad request (missing required parameters)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (user is not an organization admin)
'404':
description: Organization not found
'500':
description: Internal server error
security:
- bearerAuth: []
/manage_workspace_users:
post:
summary: Manage workspace users
description: This endpoint allows organization administrators to add or remove users from a workspace.
operationId: manageProjectUsers
tags:
- Organization
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
organization_id:
type: string
description: The ID of the organization that the workspace belongs to.
user_id:
type: string
description: Your user id -- you must be an organization admin to manage workspace users.
workspace_id:
type: string
description: The ID of the workspace to manage users for.
action:
type: string
enum: [add, remove]
description: The action to perform - either 'add' or 'remove' a user.
user_email:
type: string
description: The email address of the target user to add or remove.
is_admin:
type: boolean
description: When adding a user, specify whether they should have admin privileges (default is false).
required:
- organization_id
- user_id
- workspace_id
- action
- user_email
responses:
'200':
description: User successfully added to or removed from workspace
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
description: A success message describing the action performed.
'400':
description: Bad request (missing required parameters or invalid action)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (user is not an organization admin or workspace doesn't belong to organization)
'404':
description: Organization, workspace, or user not found
'500':
description: Internal server error
security:
- bearerAuth: []
/manage_permission_group_users:
post:
summary: Manage custom role users
description: This endpoint allows organization administrators to add or remove users from a custom role (formerly "permission group"). Adding a user to a role does not remove them from any other role they belong to.
operationId: managePermissionGroupUsers
tags:
- Organization
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
organization_id:
type: string
description: The ID of the organization that the custom role belongs to.
user_id:
type: string
description: Your user id -- you must be an organization admin to manage custom role users.
group_id:
type: string
description: The ID of the custom role to manage users for.
action:
type: string
enum: [add, remove]
description: The action to perform - either 'add' or 'remove' a user.
user_email:
type: string
description: The email address of the target user to add or remove.
required:
- organization_id
- user_id
- group_id
- action
- user_email
responses:
'200':
description: User successfully added to or removed from the custom role
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
description: A success message describing the action performed.
'400':
description: Bad request (missing required parameters or invalid action)
'401':
description: Unauthorized (missing or invalid API key)
'403':
description: Forbidden (user is not an organization admin or custom role doesn't belong to organization)
'404':
description: Organization, custom role, or user not found
'500':
description: Internal server error
security:
- bearerAuth: []
/export_data:
post:
summary: Export data
description: |
This endpoint allows enterprise organization administrators to create and initiate a comprehensive data export for their organization or specific workspaces.
The export supports four data types:
- **Workflow data** (`data_type: "workflows"`): Includes workflow runs, workbook details, user information, and other organizational data.
- **Agent data** (`data_type: "agents"`): Includes agent configurations, metadata, tools, and creator information.
- **Agent interaction data** (`data_type: "agent_interactions"`): Includes agent interaction data with timestamps, credit costs, trigger types, and message counts.
- **Credit log data** (`data_type: "credit_logs"`): Includes credit transaction history with charges, balances, categories, and user attribution.
The available `export_fields` depend on the selected `data_type`. See the field descriptions below for details.
**Scoping requirement:** For non-credit-log exports, at least one scoping parameter must be provided: `workspace_ids`, `include_all_workspaces`, `include_personal_workspaces`, or `entity_ids`. Requests that omit all scoping parameters will receive a `400` erro
# --- truncated at 32 KB (247 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gumloop/refs/heads/main/openapi/gumloop-openapi-original.yml