Gumloop Organization API
The Organization API from Gumloop — 5 operation(s) for organization.
OpenAPI Specification
openapi: 3.0.0
info:
title: Public Agents Organization API
version: 1.0.0
servers:
- url: https://api.gumloop.com/api/v1
tags:
- name: Organization
paths:
/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` error.
**Note:** Credit log exports work differently from workflow and agent exports. When `data_type` is `"credit_logs"`, the following parameters are **not applicable** and will be ignored: `export_level`, `workspace_ids`, `include_all_workspaces`, `include_personal_workspaces`, and `entity_ids`. Credit log exports are always scoped to the entire organization. Use `category_filter` to filter by credit log category.
'
operationId: exportData
tags:
- Organization
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The ID of the user requesting the export.
data_type:
type: string
enum:
- workflows
- agents
- agent_interactions
- credit_logs
default: workflows
description: 'The type of data to export. Use `"workflows"` to export workflow run data, `"agents"` to export agent configuration data, `"agent_interactions"` to export agent interaction data, or `"credit_logs"` to export credit transaction history. Defaults to `"workflows"`.
'
category_filter:
type: string
description: '**Only applicable when `data_type` is `"credit_logs"`.** Optional filter to export only credit logs matching a specific category (e.g., `"PIPELINE_RUN"`, `"AGENT_RUN"`, `"CUSTOM_NODE_RD"`, `"EXTERNAL_GUMCP_CALL"`). When omitted, all categories are included.
'
export_level:
type: string
enum:
- workspace
- organization
default: organization
description: 'The scope of the export. Use `"organization"` to export across the entire organization, or `"workspace"` to export from a single workspace (requires exactly one ID in `workspace_ids`). Defaults to `"organization"`. **Not applicable when `data_type` is `"credit_logs"`.**
'
export_fields:
type: array
items:
type: string
description: 'Array of fields to include in the export. The available fields depend on the `data_type`.
**Workflow fields** (when `data_type` is `"workflows"`):
- `workbook_id` - The workbook identifier
- `workbook_name` - The workbook name
- `workbook_created_ts` - Workbook creation timestamp
- `user_id` - The user identifier
- `user_email` - The user''s email address
- `workspace_id` - The workspace identifier
- `workspace_name` - The workspace name
- `run_id` - The flow run identifier
- `credit_cost` - Credits consumed by the run
- `pl_run_created_ts` - Flow run creation timestamp
- `pl_run_finished_ts` - Flow run completion timestamp
- `pipeline` - The full pipeline configuration (JSON)
**Agent fields** (when `data_type` is `"agents"`):
- `agent_id` - The agent identifier
- `agent_name` - The agent name
- `agent_description` - The agent description
- `agent_model` - The model used by the agent
- `agent_system_prompt` - The agent''s system prompt
- `agent_created_ts` - Agent creation timestamp
- `agent_tools` - Tools configured for the agent (JSON)
- `agent_metadata` - Additional agent metadata (JSON)
- `creator_email` - Email of the user who created the agent
- `workspace_id` - The workspace identifier
- `workspace_name` - The workspace name
**Agent interaction fields** (when `data_type` is `"agent_interactions"`):
- `interaction_id` - Unique identifier for the chat session
- `agent_id` - The agent identifier
- `agent_name` - The agent name
- `interaction_type` - Type of interaction (e.g., chat, slack, api, triggered)
- `interaction_name` - Display name of the chat session
- `trigger_type` - For triggered interactions, the specific trigger type (e.g., time_based, polling_new_record_salesforce). Null for non-triggered interactions.
- `interaction_created_ts` - Chat session creation timestamp
- `user_email` - Email of the user who initiated the chat
- `credit_cost` - Total credits consumed (LLM + tool + flow)
- `llm_credit_cost` - Credits consumed by LLM calls only
- `tool_credit_cost` - Credits consumed by tool calls
- `flow_credit_cost` - Credits consumed by pipeline runs
- `message_count` - Number of messages in the conversation
- `workspace_id` - The workspace identifier
- `workspace_name` - The workspace name
**Credit log fields** (when `data_type` is `"credit_logs"`):
- `user_email` - Email of the user associated with the credit log entry
- `permission_group_id` - Custom role ID(s) the user belongs to (semicolon-separated if multiple) (disabled by default)
- `permission_group_name` - Custom role name(s) the user belongs to (semicolon-separated if multiple) (disabled by default)
- `timestamp` - When the credit transaction occurred
- `category` - The category of the credit log (e.g., PIPELINE_RUN, AGENT_RUN)
- `type` - The specific type of credit charge
- `name` - Display name of the credit log entry
- `amount` - Number of credits charged or adjusted
- `balance` - Credit balance after the transaction
- `log_id` - Unique identifier for the credit log entry
- `project_id` - The project identifier (disabled by default)
Not all combinations of selected fields are guaranteed to produce data for every row.
'
start_date:
type: string
format: date-time
description: Start date for the export in ISO 8601 format (e.g., `2025-01-01T00:00:00Z`).
end_date:
type: string
format: date-time
description: End date for the export in ISO 8601 format (e.g., `2025-12-31T23:59:59Z`).
include_all_workspaces:
type: boolean
default: false
description: Whether to include all workspaces in the organization. When `true`, also sets `include_personal_workspaces` to `true`. **Not applicable when `data_type` is `"credit_logs"`.**
include_personal_workspaces:
type: boolean
default: false
description: Whether to include personal workspaces in the export. Ignored if `include_all_workspaces` is `true`. **Not applicable when `data_type` is `"credit_logs"`.**
workspace_ids:
type: array
items:
type: string
description: An optional array of workspace IDs to include in the export. When `export_level` is `"workspace"`, exactly one workspace ID is required. Ignored if `include_all_workspaces` is `true`. **Not applicable when `data_type` is `"credit_logs"`.**
entity_ids:
type: array
items:
type: string
description: 'An optional array of specific entity IDs to filter the export. For workflow exports (`data_type: "workflows"`), these are workbook IDs. For agent exports (`data_type: "agents"`) and agent interaction exports (`data_type: "agent_interactions"`), these are agent IDs. When provided, only data for the specified entities will be included. **Not applicable when `data_type` is `"credit_logs"`.**
'
required:
- user_id
- export_fields
- start_date
- end_date
responses:
'200':
description: Data export successfully initiated
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Indicates whether the export was successfully initiated.
data_export_id:
type: string
description: Unique identifier for the data export job. Use this with the [Get export status](/api-reference/organization/export-status) endpoint to check progress and download the completed export.
state:
type: string
enum:
- REQUESTED
description: The initial state of the export job. Will be `REQUESTED` upon creation.
created_ts:
type: string
format: date-time
description: Timestamp when the export was created (ISO 8601).
'400':
description: Bad request — missing required parameters, invalid date format, invalid `export_level` value, or missing scoping parameters (for non-credit-log exports, at least one of `workspace_ids`, `include_all_workspaces`, `include_personal_workspaces`, or `entity_ids` is required).
'401':
description: Unauthorized — missing or invalid API key.
'403':
description: Forbidden — insufficient permissions or the organization is not on the enterprise tier.
'404':
description: Organization or workspace not found.
'500':
description: Internal server error.
security:
- bearerAuth: []
/export_status:
get:
summary: Get data export status
description: 'This endpoint retrieves the status of a data export job and optionally downloads the export file (as CSV) if the export has completed successfully.
Use the `data_export_id` returned by the [Export data](/api-reference/organization/export-data) endpoint to check progress.
'
operationId: exportStatus
tags:
- Organization
parameters:
- in: query
name: user_id
required: true
schema:
type: string
description: The ID of the user requesting the export status.
- in: query
name: data_export_id
required: true
schema:
type: string
description: The unique identifier of the data export job to check (returned by the Export data endpoint).
- in: query
name: download
required: false
schema:
type: boolean
default: false
description: 'Set to `true` to download the export file directly when the export is completed. When `true` and the export state is `COMPLETED`, the response will be a CSV file download instead of JSON.
'
responses:
'200':
description: 'Export status retrieved successfully. If `download=true` and the export state is `COMPLETED`, the response body will be the CSV file.
'
content:
application/json:
schema:
type: object
properties:
data_export_id:
type: string
description: The unique identifier of the data export job.
state:
type: string
enum:
- REQUESTED
- IN_PROGRESS
- COMPLETED
- FAILED
description: 'Current state of the export job:
- `REQUESTED` — The export has been created and is queued for processing.
- `IN_PROGRESS` — The export is currently being processed.
- `COMPLETED` — The export finished successfully and is available for download.
- `FAILED` — The export encountered an error.
'
created_ts:
type: string
format: date-time
description: Timestamp when the export was created (ISO 8601).
finished_ts:
type: string
format: date-time
description: Timestamp when the export finished (ISO 8601). Only present when the state is `COMPLETED` or `FAILED`.
text/csv:
schema:
type: string
format: binary
description: CSV file content returned when `download=true` and the export state is `COMPLETED`.
'400':
description: Bad request — missing `data_export_id` parameter.
'401':
description: Unauthorized — missing or invalid API key.
'403':
description: Forbidden — insufficient permissions, the export does not belong to the requesting user, or the organization is not on the enterprise tier.
'404':
description: Data export not found, or the export file is no longer available.
'500':
description: Internal server error.
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: A personal API key or an [OAuth 2.0](/api-reference/oauth) access token. Personal API keys also require the `x-auth-key` header with your user ID.