# API Reference
Source: https://docs.apigene.ai/api-reference
Apigene REST API reference documentation
## Overview
Use the Apigene REST API to manage specs, interactions, MCP apps, agents, skills, workflows, tasks, contexts, organizations, and tenants.
## Authentication
Most endpoints require a Bearer token. See [API Authentication](/api-reference/api-authentication) for details.
## Explore endpoints
Browse the endpoint groups in the sidebar, or start with common areas:
Upload, list, update, and delete OpenAPI specifications
List apps, search actions, and execute MCP actions
Create and manage specialized agents
Create, run, and resume agent workflows
Upload and manage agent skills
Check API health and version
# Agent Create
Source: https://docs.apigene.ai/api-reference/agent/agent-create
post /api/agent/create
Create a new agent.
Args:
agent_data: The agent data to create
current_user: The current authenticated user
tenant: The tenant database
Returns:
Agent: The created agent
Raises:
HTTPException(400): If input validation fails
HTTPException(403): If trying to create public agent without APIGENE tier
HTTPException(409): If agent with same name already exists
HTTPException(500): If database operation fails or other error occurs
# Agent Delete
Source: https://docs.apigene.ai/api-reference/agent/agent-delete
delete /api/agent/delete/{agent_id}
Delete an agent.
Args:
agent_id: The ID of the agent to delete
current_user: The current authenticated user
tenant: The tenant database
Returns:
dict: Confirmation message
Raises:
HTTPException(400): If input validation fails
HTTPException(404): If agent not found
HTTPException(500): If database operation fails or other error occurs
# Agent Get
Source: https://docs.apigene.ai/api-reference/agent/agent-get
get /api/agent/get/{agent_id}
Get a specific agent by ID.
Args:
agent_id: The ID of the agent to retrieve
current_user: The current authenticated user
tenant: The tenant database
Returns:
Agent: The agent details
Raises:
HTTPException(400): If input validation fails
HTTPException(404): If agent not found
HTTPException(500): If database operation fails or other error occurs
# Agent Get By Name
Source: https://docs.apigene.ai/api-reference/agent/agent-get-by-name
get /api/agent/get_by_name
Get a specific agent by name.
Args:
name: The name of the agent to retrieve
current_user: The current authenticated user
tenant: The tenant database
Returns:
Agent: The agent details
Raises:
HTTPException(400): If input validation fails
HTTPException(404): If agent not found
HTTPException(500): If database operation fails or other error occurs
# Agent Update
Source: https://docs.apigene.ai/api-reference/agent/agent-update
put /api/agent/update/{agent_id}
Update an existing agent.
Args:
agent_id: The ID of the agent to update
agent_data: The updated agent data
current_user: The current authenticated user
tenant: The tenant database
Returns:
Agent: The updated agent
Raises:
HTTPException(400): If input validation fails
HTTPException(404): If agent not found
HTTPException(403): If trying to change to public agent without APIGENE tier
HTTPException(409): If new name conflicts with existing agent
HTTPException(500): If database operation fails or other error occurs
# Agents List
Source: https://docs.apigene.ai/api-reference/agent/agents-list
get /api/agent/list
List agents visible to the current user.
Includes the user's own agents (private and public) and org-shared
(public) agents. Other users' private agents are omitted.
Args:
current_user: The current authenticated user
tenant: The tenant database
agent_type: Optional filter by agent type
Returns:
List[Agent]: List of agents
Raises:
HTTPException(400): If input validation fails
HTTPException(500): If database operation fails or other error occurs
# API Authentication
Source: https://docs.apigene.ai/api-reference/api-authentication
Start making requests to the Apigene API
Through our API, you can build white label applications that let users interact with their favorite applications from their AI assistants.
API Keys are used to authenticate to your [Apigene](http://app.apigene.ai) account.
To create an API key.
1. Access your [Apigene](http://app.apigene.ai) dashboard
2. Navigate to **Settings**
3. Select the **Organization** tab
4. Click **Generate API key** to generate your Apigene API key
Ensure to copy and store your API key in a safe location as it can only be viewed from the dashboard once.
### HTTP Header: Bearer Authentication
All requests must be authenticated via bearer token in your request HTTP header in the following format:
```bash theme={null}
Authorization: Bearer
```
# Get Audit Logs
Source: https://docs.apigene.ai/api-reference/audit/audit-logs
get /api/audit/audit-logs
Get audit logs for the tenant with optional filtering
Returns:
List of audit log entries with metadata
# Get Resource Audit History
Source: https://docs.apigene.ai/api-reference/audit/resource-audit-history
get /api/audit/audit-logs/resource/{resource_type}/{resource_id}
Get complete audit history for a specific resource
Args:
resource_type: Type of resource (application, agent, mcp_server, context)
resource_id: ID of the resource
Returns:
Complete audit history for the resource
# Clear Tenant Cache
Source: https://docs.apigene.ai/api-reference/cache/clear-tenant-cache
post /api/cache_clear
Clear all cache entries for the authenticated tenant.
Returns:
Dictionary with operation result and statistics
# Delete Cache Key
Source: https://docs.apigene.ai/api-reference/cache/delete-cache-key
delete /api/cache/key
Delete cache key(s) for the authenticated tenant.
Can delete either a specific key or multiple keys matching a pattern.
Args:
key: The specific cache key to delete (mutually exclusive with pattern)
pattern: Pattern to match keys for deletion (supports wildcards, e.g., "spec:*", "*brief*")
(mutually exclusive with key)
Returns:
Dictionary with operation result
# Get Cache Key
Source: https://docs.apigene.ai/api-reference/cache/get-cache-key
get /api/cache/key
Get the value of a specific cache key for the authenticated tenant.
Args:
key: The cache key to retrieve
Returns:
Dictionary with cache key value, expiry time, and metadata
# Get Tenant Cache Keys
Source: https://docs.apigene.ai/api-reference/cache/get-tenant-cache-keys
get /api/cache/keys
Get all cache keys for the authenticated tenant.
Args:
pattern: Optional key pattern filter (supports wildcards, e.g., "spec:*", "*brief*")
Defaults to "*" to get all keys
Returns:
Dictionary with list of cache keys and metadata
# Context Type Create
Source: https://docs.apigene.ai/api-reference/context-type/context-type-create
post /api/context-type
Endpoint to create a new context type associated with the authenticated tenant.
Args:
context_type (ContextTypeCreate): The request body containing the context type definition.
Returns:
ContextType: The created context type object.
Raises:
HTTPException 400: If input validation fails
HTTPException 409: If the context type creation fails due to a runtime error.
# Context Type Delete
Source: https://docs.apigene.ai/api-reference/context-type/context-type-delete
delete /api/context-type/{context_type_id}
Endpoint to delete a context type by its ID.
Args:
context_type_id (str): The unique identifier of the context type to delete.
Returns:
dict: A confirmation message indicating the context type was deleted.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the context type with the given ID is not found.
HTTPException 500: If a runtime error occurs during deletion.
# Context Type Get
Source: https://docs.apigene.ai/api-reference/context-type/context-type-get
get /api/context-type/{context_type_id}
Endpoint to retrieve a context type by its unique ID.
Args:
context_type_id (str): The ID of the context type to retrieve.
Returns:
ContextType: A `ContextType` model instance representing the requested context type.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the context type with the specified ID does not exist.
HTTPException 500: If database operation fails
# Context Type List
Source: https://docs.apigene.ai/api-reference/context-type/context-type-list
get /api/context-type
Endpoint to list all context types associated with the current tenant.
Args:
Returns:
List[ContextType]: A list of all `ContextType` model instances stored under the tenant.
Raises:
HTTPException 500: If an error occurs while retrieving context types from the database.
# Context Type List Defaults
Source: https://docs.apigene.ai/api-reference/context-type/context-type-list-defaults
get /api/context-type/defaults
Endpoint to list available default/ready-made context types.
This returns the predefined context types from the seed data file without installing them.
Args:
None
Returns:
List[ContextTypeCreate]: List of available default context types.
Raises:
HTTPException 500: If an error occurs while loading the defaults.
# Context Type Update
Source: https://docs.apigene.ai/api-reference/context-type/context-type-update
put /api/context-type/{context_type_id}
Endpoint to update an existing context type by its ID.
Args:
context_type_id (str): The unique identifier of the context type to update.
context_type_update (ContextTypeCreate): The updated context type data.
Returns:
ContextType: The updated context type object.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the context type with the given ID does not exist.
HTTPException 500: If a runtime error occurs during the update process.
# Context Create
Source: https://docs.apigene.ai/api-reference/context/context-create
post /api/context
Endpoint to create a new context associated with the authenticated tenant.
Args:
context (ContextCreate): The request body containing the context definition.
Returns:
Context: The created context object.
Raises:
HTTPException 400: If input validation fails
HTTPException 409: If the context creation fails due to a runtime error.
# Context Delete
Source: https://docs.apigene.ai/api-reference/context/context-delete
delete /api/context/{context_id}
Endpoint to delete a context by its ID.
Args:
context_id (str): The unique identifier of the context to delete.
Returns:
dict: A confirmation message indicating the context was deleted.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the context with the given ID is not found.
HTTPException 500: If a runtime error occurs during deletion.
# Context Get
Source: https://docs.apigene.ai/api-reference/context/context-get
get /api/context/{context_id}
Endpoint to retrieve a context by its unique ID.
Args:
context_id (str): The ID of the context to retrieve.
Returns:
Context: A `Context` model instance representing the requested context.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the context with the specified ID does not exist.
HTTPException 500: If database operation fails
# Context List
Source: https://docs.apigene.ai/api-reference/context/context-list
get /api/context
Endpoint to list all active contexts associated with the current tenant.
Note: Only returns active contexts and does not include the description field.
Args:
Returns:
List[ContextListItem]: A list of all active `ContextListItem` model instances (without description).
Raises:
HTTPException 500: If an error occurs while retrieving contexts from the database.
# Context Search
Source: https://docs.apigene.ai/api-reference/context/context-search
get /api/context/search
Endpoint to search contexts with flexible filtering options and smart word-based matching.
Note: Only returns contexts matching the criteria and does not include the description field.
Args:
query (Optional[str]): Search query to match against name, summary, type, and description.
Splits into words and matches if ANY word is found.
type (Optional[str]): Filter contexts by specific type.
status (Optional[str]): Filter by status (default: "active").
max_results (int): Maximum number of results to return (default: 5).
Returns:
List[ContextListItem]: A list of `ContextListItem` model instances matching the search criteria,
sorted by relevance score (number of matching words).
Raises:
HTTPException 500: If an error occurs while retrieving contexts from the database.
Examples:
- /context/search?query=keyword - Search for "keyword" in name, summary, type
- /context/search?type=Skill - Filter by type "Skill"
- /context/search?query=api&type=Tool - Search for "api" within "Tool" type
- /context/search?status=disabled&max_results=10 - Get top 10 disabled contexts
# Context Update
Source: https://docs.apigene.ai/api-reference/context/context-update
put /api/context/{context_id}
Endpoint to update an existing context by its ID.
Args:
context_id (str): The unique identifier of the context to update.
context_update (ContextCreate): The updated context data.
Returns:
Context: The updated context object.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the context with the given ID does not exist.
HTTPException 500: If a runtime error occurs during the update process.
# Create a generative UI template for an agent
Source: https://docs.apigene.ai/api-reference/generative-ui-templates/generative-ui-template-create
post /api/generative-ui-templates/{agent_name}
# Delete a generative UI template
Source: https://docs.apigene.ai/api-reference/generative-ui-templates/generative-ui-template-delete
delete /api/generative-ui-templates/{agent_name}/{template_id}
# Get a generative UI template by id
Source: https://docs.apigene.ai/api-reference/generative-ui-templates/generative-ui-template-get
get /api/generative-ui-templates/{agent_name}/{template_id}
# List generative UI templates for an agent
Source: https://docs.apigene.ai/api-reference/generative-ui-templates/generative-ui-template-list
get /api/generative-ui-templates/{agent_name}
# Update a generative UI template
Source: https://docs.apigene.ai/api-reference/generative-ui-templates/generative-ui-template-update
put /api/generative-ui-templates/{agent_name}/{template_id}
# Sync template with GitHub
Source: https://docs.apigene.ai/api-reference/github-sync/github-sync
post /api/ui-templates/github/sync/{api_name}/{template_id}
Sync template with GitHub repository.
# Connect template to GitHub repository
Source: https://docs.apigene.ai/api-reference/github-sync/github-sync-connect
post /api/ui-templates/github/connect/{api_name}/{template_id}
Connect a template to a GitHub repository for syncing.
# Disconnect template from GitHub
Source: https://docs.apigene.ai/api-reference/github-sync/github-sync-disconnect
delete /api/ui-templates/github/disconnect/{api_name}/{template_id}
Disconnect a template from GitHub repository.
# Get GitHub sync history
Source: https://docs.apigene.ai/api-reference/github-sync/github-sync-history
get /api/ui-templates/github/history/{api_name}/{template_id}
Get commit history for synced template.
# Get GitHub sync status
Source: https://docs.apigene.ai/api-reference/github-sync/github-sync-status
get /api/ui-templates/github/status/{api_name}/{template_id}
Get sync status for a template.
# App Execute Action
Source: https://docs.apigene.ai/api-reference/gpt-public/app-execute-action
post /api/gpt_public/app_execute_action
Triggers an interaction for a custom GPT model using the provided input and operation ID. Returns the GPT-generated response.
# App Get Actions
Source: https://docs.apigene.ai/api-reference/gpt-public/app-get-actions
get /api/gpt_public/app_get_actions
List the available actions for a given app.
# Apps List
Source: https://docs.apigene.ai/api-reference/gpt-public/apps-list
get /api/gpt_public/apps_list
Returns Custom GPT's full instructions. GPT must call this at the start of each session, before any other action. Response JSON: {task, operations_list} where operations_list lists actions for app_execute_action.
# Apps Search Actions
Source: https://docs.apigene.ai/api-reference/gpt-public/apps-search-actions
get /api/gpt_public/apps_search_actions
Search across all agentic metadata for the most relevant actions based on the query parameters.
# Get Gpt Public Openapi
Source: https://docs.apigene.ai/api-reference/gpt-public/get-gpt-public-openapi
get /api/openapi
Returns a filtered OpenAPI specification that only includes endpoints with the specified operation IDs.
Parameters:
request (Request): The HTTP request object representing the incoming request.
Returns:
dict: A dictionary representing the filtered OpenAPI specification.
Raises:
HTTPException: If no paths are found with the specified operation IDs.
# Gpt Create
Source: https://docs.apigene.ai/api-reference/gpt/gpt-create
post /api/gpt/create
Endpoint to create a new GPT instance using a provided payload of GPT metadata and configuration.
Args:
payload (GPT): The GPT configuration payload including name, description, APIs, category, and more.
Returns:
GPT: The newly created GPT instance.
# Gpt Create All
Source: https://docs.apigene.ai/api-reference/gpt/gpt-create-all
post /api/gpt/create_all
Endpoint to create GPTs for all available APIs associated with the current tenant.
Args:
Returns:
dict: A summary message indicating the number of successful and failed GPT creation attempts.
# Gpt Create From Api
Source: https://docs.apigene.ai/api-reference/gpt/gpt-create-from-api
post /api/gpt/create_from_api
Endpoint to create a GPT instance from a given API name.
Generates GPT metadata, description, and instructions based on the API's OpenAPI specification.
Args:
api_name (str): The unique name of the API from which to generate the GPT.
Returns:
dict: The created GPT metadata.
# Gpt Delete
Source: https://docs.apigene.ai/api-reference/gpt/gpt-delete
delete /api/gpt/{genai_app}/delete
Endpoint to delete a specific GPT instance by name for the current tenant.
Args:
genai_app (str): The unique name identifier of the GPT to be deleted.
Returns:
dict: A message confirming the deletion of the GPT instance.
# Gpt Generate Token
Source: https://docs.apigene.ai/api-reference/gpt/gpt-generate-token
post /api/gpt/{genai_app}/generate_token
Endpoint to generate a new access token for a specified GPT instance.
Any previously generated token for the same GPT and organization will be deleted and replaced.
Args:
genai_app (str): The name of the GPT for which the token is to be generated.
Returns:
dict: A dictionary containing the generated token, token ID, GPT name, and associated organization ID.
# Retrieve Custom GPT Details
Source: https://docs.apigene.ai/api-reference/gpt/gpt-get
get /api/gpt/{genai_app}/get
This endpoint retrieves the details of a specified custom GPT model based on the provided GPT name. It fetches the GPT's instructions, description, and accessible APIs.
# Gpt Read Token
Source: https://docs.apigene.ai/api-reference/gpt/gpt-read-token-id
get /api/gpt/{genai_app}/read_token
Endpoint to reade the access token associated with a given GPT instance.
Args:
genai_app (str): The name of the GPT whose token is to be revoked.
Returns:
dict: A dictionary containing the generated token, token ID, GPT name, and associated organization ID.
# redirect the shorten url to full authorization url
Source: https://docs.apigene.ai/api-reference/gpt/gpt-redirect-to-authorization
get /api/gpt/redirect/{token}
Endpoint to redirect a shortened tokenized URL to its corresponding full authorization URL.
Args:
token (str): The shortened tokenized url.
Returns:
RedirectResponse: A redirect to the original, full authorization URL.
# Gpt Revoke Token
Source: https://docs.apigene.ai/api-reference/gpt/gpt-revoke-token
post /api/gpt/{genai_app}/revoke_token
Endpoint to revoke the access token associated with a given GPT instance.
Args:
genai_app (str): The name of the GPT whose token is to be revoked.
Returns:
dict: A message indicating that the token has been successfully revoked.
# Gpt Update
Source: https://docs.apigene.ai/api-reference/gpt/gpt-update
post /api/gpt/update
Endpoint to update an existing GPT instance's description and associated APIs.
Args:
payload (GPT): The updated GPT configuration payload.
Returns:
dict: A message indicating success, failure, or if no changes were detected.
# Gpts List
Source: https://docs.apigene.ai/api-reference/gpt/gpts-list
get /api/gpts/list
Endpoint to list GPTs based on inclusion flags for private and public GPTs.
Args:
include_private_gpts (bool): Whether to include private GPTs in the response.
include_public_gpts (bool): Whether to include public GPTs in the response.
tenant (Tenant): Tenant dependency injection for accessing database operations.
Returns:
List[dict]: A list of GPT details.
# Get Activity Timeline
Source: https://docs.apigene.ai/api-reference/interaction/get-activity-timeline
post /api/interaction/activity-timeline
Histogram of interaction counts over a rolling window, grouped by time bucket and HTTP status class.
Uses the first action's status_code in actions_result. Members see only their own interactions.
# Get App Insights
Source: https://docs.apigene.ai/api-reference/interaction/get-app-insights
get /api/interaction/insights/{app_name}
Get comprehensive insights and analytics for a specific application (agent).
This endpoint analyzes all interactions for the given app_name and provides:
- Performance metrics (avg, median, P95, P99 durations)
- Cache effectiveness metrics
- Success/error rate analysis
- Usage patterns and trends
- User engagement metrics
- Response size analysis
- Time-based insights (peak hours, growth trends)
- Health score and recommendations
Parameters:
- app_name: Name of the application/agent to analyze
- current_user: Current user for authentication
- tenant: Tenant database instance
Returns:
- AppInsightsResponse with comprehensive analytics
Raises:
- HTTPException(404): If no interactions found for the app_name
- HTTPException(401): If the user is not authorized
# Get Interaction Detail
Source: https://docs.apigene.ai/api-reference/interaction/get-interaction-detail
get /api/interaction/{interaction_id}
Get detailed interaction data by ID.
This endpoint returns the full interaction data including request/response details.
Use this endpoint when you need to view the complete interaction information.
Parameters:
- interaction_id: Unique identifier of the interaction.
- current_user: Current user for authentication (required for org membership).
Returns:
- Full interaction data including request/response details.
- For admins: returns any interaction.
- For members: returns only interactions that belong to the member user.
Raises:
- HTTPException(404): If the interaction is not found.
- HTTPException(403): If the user is not authorized to view this interaction (members can only view their own).
- HTTPException(401): If the user is not authorized.
# Get Summary
Source: https://docs.apigene.ai/api-reference/interaction/get-summary
post /api/interaction/summary
Endpoint to retrieve summarized interaction counts over a specified date range, grouped by daily, weekly, or monthly intervals.
Optionally filters by API titles and supports flexible time granularity in results.
Args:
request (SummaryRequest): The request body containing filter options:
- start_date (datetime): Start date of the summary range.
- end_date (datetime): End date of the summary range.
- api_title (List[str], optional): List of API titles to filter by.
- time_frame (str, optional): Time granularity - 'daily', 'weekly', or 'monthly'.
Returns:
dict: A dictionary mapping time buckets (daily/weekly/monthly) to counts of interactions,
either grouped by API title or as a total count.
Example Response:
{
"2024-04-01": {"API A": 12, "API B": 8},
"2024-04-02": {"API A": 9, "API B": 5}
}
# Interaction Create
Source: https://docs.apigene.ai/api-reference/interaction/interaction-create
post /api/interaction/create
Create an interaction.
This endpoint allows you to create an interaction with the specified data.
Parameters:
- data: Input data for the interaction.
- api_key: API key for authentication.
Returns:
- List of action results.
Raises:
- HTTPException(401): If the provided API key is invalid.
# Record Mcp Tool
Source: https://docs.apigene.ai/api-reference/interaction/interaction-record-mcp-tool
post /api/interaction/record-mcp-tool
Record a native MCP tool call from apigene-copilot for interaction history.
Called by the copilot after each MCP tool execution so that tool usage
appears in the same interaction store as API actions (create_interaction).
# List Interactions
Source: https://docs.apigene.ai/api-reference/interaction/list-interactions
post /api/interaction/list
List interactions metadata (optimized for table display).
This endpoint returns only metadata for interactions to improve performance.
Use /interaction/{interaction_id} to get full interaction details.
Parameters:
- request_body: Request body containing optional filters for querying interactions.
- api_name: Name of the API (optional).
- page: Page number for pagination (default: 1).
- limit: Maximum number of interactions per page (default: 50).
- sort_by: Field to sort interactions by (optional).
- sort_order: Sorting order ('asc' or 'desc') (default: 'asc').
- current_user: Current user for authentication (required for org membership).
Returns:
- List of interaction metadata (without large response data).
- For admins: returns all interactions.
- For members: returns only interactions that belong to the member user.
Raises:
- HTTPException(401): If the user is not authorized.
# Mcp Create From Api
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-create-from-api
post /api/mcp-server/create_from_api
Create a new MCP server from an existing API specification.
This endpoint locates the API by name, fetches its details, and creates a valid
MCP server of APIGENE type with the API's information. The MCP server name is
automatically set to the API title, enabled is set to true, and global_spec
is derived from the API data.
Args:
request: The request containing only the API name
current_user: The current authenticated user
tenant: The tenant database
Returns:
dict: The created MCP server information
Raises:
HTTPException(404): If the API specification is not found
HTTPException(409): If an MCP server with the same name already exists
HTTPException(500): If an error occurs during creation
# Mcp Server Create
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-server-create
post /api/mcp-server/create
Create a new MCP server.
Args:
mcp_server_data: The MCP server data to create
current_user: The current authenticated user
tenant: The tenant database
Returns:
MCPServer: The created MCP server
Raises:
HTTPException(400): If input validation fails
HTTPException(403): If trying to create public server without APIGENE tier
HTTPException(409): If MCP server with same name already exists
HTTPException(500): If database operation fails or other error occurs
# Mcp Server Delete
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-server-delete
delete /api/mcp-server/delete/{server_id}
Delete an MCP server.
Args:
server_id: The ID of the MCP server to delete
current_user: The current authenticated user
tenant: The tenant database
Returns:
dict: Confirmation message
Raises:
HTTPException(400): If input validation fails
HTTPException(404): If MCP server not found
HTTPException(500): If database operation fails or other error occurs
# Mcp Server Get
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-server-get
get /api/mcp-server/get/{server_id}
Get a specific MCP server by ID.
Args:
server_id: The ID of the MCP server to retrieve
current_user: The current authenticated user
tenant: The tenant database
Returns:
MCPServer: The MCP server details
Raises:
HTTPException(400): If input validation fails
HTTPException(404): If MCP server not found
HTTPException(500): If database operation fails or other error occurs
# Mcp Server Login
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-server-login
post /api/mcp-server/login/{server_id}
Start an OAuth login for the current user on a native MCP server.
Discovers OAuth metadata, registers the client if needed, and returns an
authorization URL. Completing the flow stores a gateway token so Copilot
and agents in Cursor / Claude can use the new credentials.
# Mcp Server Logout
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-server-logout
post /api/mcp-server/logout/{server_id}
Clear the current user's MCP OAuth token for a native MCP server.
Deletes only this user's stored token (Mongo + Redis) and drops cached
MCP clients so Copilot and the MCP gateway both re-authorize on next use.
Idempotent: succeeds when no token is stored.
# Mcp Server Refresh Tools
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-server-refresh-tools
post /api/mcp-server/refresh-tools/{server_id}
Manually refresh tools cache for a native MCP server.
Only works for native servers (public/private), not Apigene servers.
Args:
server_id: The ID of the MCP server
current_user: The current authenticated user
tenant: The tenant database
Returns:
Dict with refresh status and tool count
Raises:
HTTPException(404): If MCP server not found
HTTPException(400): If server is Apigene type
HTTPException(511): If OAuth required
HTTPException(500): If refresh fails
# Mcp Server Update
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-server-update
put /api/mcp-server/update/{server_id}
Update an existing MCP server.
Args:
server_id: The ID of the MCP server to update
mcp_server_data: The updated MCP server data
current_user: The current authenticated user
tenant: The tenant database
Returns:
MCPServer: The updated MCP server
Raises:
HTTPException(400): If input validation fails
HTTPException(404): If MCP server not found
HTTPException(403): If trying to change to public server without APIGENE tier
HTTPException(409): If new name conflicts with existing server
HTTPException(500): If database operation fails or other error occurs
# Mcp Server Update Tools Cache
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-server-update-tools-cache
post /api/mcp-server/update-tools-cache/{server_id}
Update tools cache for an MCP server from frontend client.
This endpoint accepts tools directly from the frontend MCP client.
Args:
server_id: The ID of the MCP server
tools_data: Request body containing list of tools
current_user: The current authenticated user
tenant: The tenant database
Returns:
Dict with update status and tool count
Raises:
HTTPException(404): If MCP server not found
HTTPException(400): If server is Apigene type or invalid input
HTTPException(500): If update fails
# Mcp Servers List
Source: https://docs.apigene.ai/api-reference/mcp-server/mcp-servers-list
get /api/mcp-server/list
List all MCP servers for the current tenant.
Args:
current_user: The current authenticated user
tenant: The tenant database
server_type: Optional filter by server type
enabled_only: Only return enabled servers
Returns:
List[MCPServer]: List of MCP servers
Raises:
HTTPException(400): If input validation fails
HTTPException(500): If database operation fails or other error occurs
# Get Skill
Source: https://docs.apigene.ai/api-reference/mcp/get-skill
get /api/mcp/get_skill
Get a specific skill by its id for the specified agent.
Returns the skill metadata (without content) for the specified skill id if the agent has access to it.
# Get Skill Content
Source: https://docs.apigene.ai/api-reference/mcp/get-skill-content
get /api/mcp/get_skill_content
Get the full SKILL.md content for a specific skill.
This is used when an agent activates a skill and needs the full content.
# List Skills
Source: https://docs.apigene.ai/api-reference/mcp/list-skills
get /api/mcp/list_skills
List all skill metadata available for the specified agent.
Returns a list of skill metadata (without content) that the agent has access to.
Args:
detail_level: "summary" returns only id, name, description (70-90% fewer tokens).
"full" returns all metadata fields. Default: "full".
# App Execute Action
Source: https://docs.apigene.ai/api-reference/mcp/mcp-app-execute-action
post /api/mcp/app_execute_action
Triggers an interaction for a custom MCP model using the provided input and operation ID. Returns the MCP-generated response.
# App Get Action Details
Source: https://docs.apigene.ai/api-reference/mcp/mcp-app-get-action-details
get /api/mcp/app_get_action_details
Get complete details for one or more actions by their operationIds.
Returns the full schema, parameters, and documentation for the specified actions.
This endpoint is used after discovering actions via list_actions or search_actions with detail_level='summary'.
Supports fetching multiple actions in a single call by passing comma-separated operationIds.
# App Get Actions
Source: https://docs.apigene.ai/api-reference/mcp/mcp-app-get-actions
get /api/mcp/app_get_actions
List the available actions for a given app.
Supports detail_level parameter for optimized token usage:
- 'summary': Returns only operationId and description (70-90% fewer tokens)
- 'full': Returns complete action details with schemas (default)
# Get App Config
Source: https://docs.apigene.ai/api-reference/mcp/mcp-appconfig
get /api/mcp/appconfig
Get aggregated app configuration including CSP policies from all templates.
This endpoint aggregates CSP configuration from all templates associated with the
app's APIs and MCPs. For agents, it collects CSP from templates for all APIs in
agent_info.apis and APIs from agent_info.mcps. For MCP servers, it collects CSP
from templates for the single api_name.
Args:
genai_app: The name of the GenAI app
app_type: The type of app ('agent' or 'mcp')
Returns:
AppConfigResponse with aggregated CSP configuration and template count
# Apps List
Source: https://docs.apigene.ai/api-reference/mcp/mcp-apps-list
get /api/mcp/apps_list
Returns list of available apps with their metadata.
By default (include_action_summaries=true), includes lightweight action summaries for each app.
This provides a complete discovery view in a single call with 70-90% token savings compared to calling list_actions separately.
Set include_action_summaries=false if you only need app names without actions.
The max_action_summary parameter limits the number of actions per app, with a hint added when there are more.
# Apps Search Actions
Source: https://docs.apigene.ai/api-reference/mcp/mcp-apps-search-actions
get /api/mcp/apps_search_actions
Search across all agentic metadata for the most relevant actions based on the query parameters.
Supports detail_level parameter for optimized token usage:
- 'summary': Returns only operationId and description (70-90% fewer tokens)
- 'full': Returns complete action details with schemas (default)
# Create Skill
Source: https://docs.apigene.ai/api-reference/mcp/mcp-create-skill
post /api/mcp/create_skill
Create a new skill and optionally add it to the specified agent.
Only agents can create skills via MCP; the new skill is created in the tenant and
automatically added to the agent's skills list so the agent can use it.
# Get Context
Source: https://docs.apigene.ai/api-reference/mcp/mcp-get-context
get /api/mcp/get_context
Get a specific context by its id for the specified agent.
Returns the full context data for the specified context id if the agent has access to it.
# Get Instructions
Source: https://docs.apigene.ai/api-reference/mcp/mcp-get-instructions
get /api/mcp/get_instructions
Returns the formatted agent instructions for the specified GenAI app.
This includes the app description, internal guidelines, and list of available apps with their capabilities.
# List Contexts
Source: https://docs.apigene.ai/api-reference/mcp/mcp-list-contexts
get /api/mcp/list_contexts
List all context names available for the specified agent.
Returns a list of context names that the agent has access to.
# Official Mcp Server Create
Source: https://docs.apigene.ai/api-reference/official-mcp-server/official-mcp-server-create
post /api/official-mcp-server
Endpoint to create a new official MCP server.
Args:
server (OfficialMCPServerCreate): The request body containing the server definition.
Returns:
OfficialMCPServer: The created official MCP server object.
Raises:
HTTPException 400: If input validation fails
HTTPException 409: If the server creation fails due to duplicate name or runtime error.
# Official Mcp Server Delete
Source: https://docs.apigene.ai/api-reference/official-mcp-server/official-mcp-server-delete
delete /api/official-mcp-server/{server_id}
Endpoint to delete an official MCP server.
Args:
server_id: The ID of the official MCP server to delete
Returns:
dict: Success message with deletion count
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the server is not found
HTTPException 500: If an error occurs while deleting the server.
# Official Mcp Server Get
Source: https://docs.apigene.ai/api-reference/official-mcp-server/official-mcp-server-get
get /api/official-mcp-server/{server_id}
Endpoint to retrieve an official MCP server by ID.
Args:
server_id: The ID of the official MCP server
Returns:
OfficialMCPServer: The official MCP server object.
Raises:
HTTPException 404: If the server is not found.
HTTPException 500: If an error occurs while retrieving the server.
# Official Mcp Server List
Source: https://docs.apigene.ai/api-reference/official-mcp-server/official-mcp-server-list
get /api/official-mcp-server
Endpoint to list all official MCP servers.
Args:
name: Optional filter by server name
domain: Optional filter by domain
Returns:
List[OfficialMCPServer]: A list of all official MCP server objects.
Raises:
HTTPException 500: If an error occurs while retrieving servers from the database.
# Official Mcp Server Update
Source: https://docs.apigene.ai/api-reference/official-mcp-server/official-mcp-server-update
put /api/official-mcp-server/{server_id}
Endpoint to update an existing official MCP server.
Args:
server_id: The ID of the official MCP server to update
server (OfficialMCPServerUpdate): The request body containing the fields to update.
Returns:
OfficialMCPServer: The updated official MCP server object.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the server is not found
HTTPException 409: If update fails due to duplicate name or runtime error.
# Org Add User
Source: https://docs.apigene.ai/api-reference/org/org-add-user
post /api/org/add_user/
Endpoint for an organization admin to add a new user to their organization.
Args:
user_data (UserCreate): The new user information including email, name, role, and org_name.
Returns:
dict: A success message confirming the user was added to the organization.
Raises:
HTTPException 404:
- If the organization database is not found.
- If the `org_name` in user data doesn't match the admin's org.
- If organization details are not initialized.
HTTPException 409:
- If the user already exists globally.
- If the user is already a member of the organization.
HTTPException 500:
- If any unexpected error occurs during the user addition process.
# Apply OnPrem License
Source: https://docs.apigene.ai/api-reference/org/org-apply-license
post /api/org/apply_license
OnPrem only: apply a signed license JWT to the current organization. Clears the trial once a valid, non-expired token bound to this org is stored.
# Org Create
Source: https://docs.apigene.ai/api-reference/org/org-create
post /api/org/create/
# Org Delete
Source: https://docs.apigene.ai/api-reference/org/org-delete
delete /api/org/delete/{org_name}
Endpoint to delete an organization and all its associated data.
This operation is restricted to root-level users only.
Note: In production, organizations should be deleted via Clerk webhooks.
This endpoint is primarily for administrative/testing purposes.
Args:
org_name (str): The name (or ID) of the organization to delete.
Returns:
dict: A success message confirming the organization deletion.
Raises:
HTTPException 404: If the deletion fails due to the organization not existing or an internal error.
# Org Generate Token
Source: https://docs.apigene.ai/api-reference/org/org-generate-token
post /api/org/{org_name}/generate_token
Endpoint for organization admins to generate an access token scoped to their organization.
Args:
org_name (str): The name (or ID) of the organization for which the token is being generated.
expiry_duration (Optional[int]): Token expiry duration in seconds. If not provided, uses default expiry.
Returns:
dict: A dictionary containing the `org_token`.
Raises:
HTTPException 403: If the current user is not authorized to manage the specified organization.
# Org Get Details
Source: https://docs.apigene.ai/api-reference/org/org-get-details
get /api/org/details/{org_name}
Endpoint to retrieve full organization details, including metadata and member information.
Access is restricted to organization admins.
Args:
org_name (str): The name (or ID) of the organization to retrieve details for.
Returns:
dict: A dictionary containing organization details and an array of member metadata.
Raises:
HTTPException 403: If the user is not authorized to manage the specified organization.
HTTPException 404: If the organization or its details do not exist.
# Org Remove User
Source: https://docs.apigene.ai/api-reference/org/org-remove-user
delete /api/org/remove_user/{username}
Endpoint for organization admins to remove a user from their organization.
Args:
username (str): The email of the user to be removed from the organization.
Returns:
dict: A message confirming successful removal of the user.
Raises:
HTTPException 404:
- If the organization or the specified user is not found.
HTTPException 409:
- If the user does not belong to the organization.
HTTPException 500:
- If an internal error occurs during the removal process.
# Org Settings Update
Source: https://docs.apigene.ai/api-reference/org/org-settings-update
post /api/org/settings/update
# Retrieve Organization settings
Source: https://docs.apigene.ai/api-reference/org/retrieve-organization-settings
get /api/org/settings
Retrieves organization settings. Secrets (model_registry API keys, openlegacy.api_key, and industry_marketplace.token) are returned as last4 by default. Pass include_secrets=true to receive full secrets: org admins receive all of them, while members receive model_registry credentials only (needed to run models and tools) with integration tokens still redacted.
# Skill Create
Source: https://docs.apigene.ai/api-reference/skill/skill-create
post /api/skill
Endpoint to create a new skill associated with the authenticated tenant.
Args:
skill (SkillCreate): The request body containing the skill definition.
Returns:
Skill: The created skill object.
Raises:
HTTPException 400: If input validation fails
HTTPException 409: If the skill creation fails due to a runtime error.
# Skill Delete
Source: https://docs.apigene.ai/api-reference/skill/skill-delete
delete /api/skill/{skill_id}
Endpoint to delete a skill by its ID.
Args:
skill_id: The unique identifier of the skill to delete.
Returns:
dict: A confirmation message indicating the skill was deleted.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the skill with the given ID is not found.
HTTPException 500: If a runtime error occurs during deletion.
# Skill Get
Source: https://docs.apigene.ai/api-reference/skill/skill-get
get /api/skill/{skill_id}
Endpoint to retrieve a skill by its unique ID.
Args:
skill_id: The ID of the skill to retrieve.
include_optional_files: If true (default), include scripts, references, and assets.
Set to false for a lighter response when only SKILL.md metadata/content is needed.
Returns:
Skill: A Skill model instance representing the requested skill.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the skill with the specified ID does not exist.
HTTPException 500: If database operation fails
# Skill Get File
Source: https://docs.apigene.ai/api-reference/skill/skill-get-file
get /api/skill/{skill_id}/file
Return a single optional file from scripts/, references/, or assets/.
Use for progressive disclosure (load files on demand per Agent Skills spec).
# Skill List
Source: https://docs.apigene.ai/api-reference/skill/skill-list
get /api/skill
Endpoint to list all skills associated with the current tenant.
Note: Returns all skills (both active and disabled) and does not include the content field.
Returns:
List[SkillListItem]: A list of all skill list items (without content).
Raises:
HTTPException 500: If an error occurs while retrieving skills from the database.
# Skill Search
Source: https://docs.apigene.ai/api-reference/skill/skill-search
get /api/skill/search
Endpoint to search skills with flexible filtering options.
Args:
query: Search query to match against name and description
status: Filter by status (default: "active")
max_results: Maximum number of results to return (default: 5)
Returns:
List[SkillListItem]: A list of skill list items matching the search criteria
# Skill Update
Source: https://docs.apigene.ai/api-reference/skill/skill-update
put /api/skill/{skill_id}
Endpoint to update an existing skill by its ID.
Args:
skill_id: The unique identifier of the skill to update.
skill_update: The updated skill data.
Returns:
Skill: The updated skill object.
Raises:
HTTPException 400: If input validation fails
HTTPException 404: If the skill with the given ID does not exist.
HTTPException 500: If a runtime error occurs during the update process.
# Skill Upload
Source: https://docs.apigene.ai/api-reference/skill/skill-upload
post /api/skill/upload
Endpoint to upload and create a skill from a SKILL.md file.
Args:
file (UploadFile): The SKILL.md file to upload.
Returns:
Skill: The created skill object.
Raises:
HTTPException 400: If file validation fails
HTTPException 409: If the skill creation fails.
# Skill Validate
Source: https://docs.apigene.ai/api-reference/skill/skill-validate
post /api/skill/validate
Endpoint to validate skill content against the Agent Skills specification.
Args:
content: The SKILL.md content to validate
skill_name: Optional expected skill name for validation
Returns:
SkillValidationResponse: Validation result with errors and warnings
# Spec Clone
Source: https://docs.apigene.ai/api-reference/spec/spec-clone
post /api/spec/{api_name}/clone
Clone a spec to create a private copy.
Creates a complete copy of the spec including:
- Spec document (spec, examples, llm_summary, agentic_metadata, etc.)
- Spec configuration (security_info, operations_state, common_parameters)
The cloned spec will be tenant-specific (not global) and independent.
All metadata (created_by, created_at, updated_at) will be updated.
Parameters:
- api_name (str): The name of the source spec to clone.
- payload (SpecClonePayload): Payload containing clone_api_title.
Returns:
- dict: Dictionary containing api_name of the cloned spec.
Raises:
- HTTPException(400): If clone_api_title validation fails (invalid characters or exceeds 100 characters).
- HTTPException(404): If the source spec is not found.
- HTTPException(409): If the clone_api_title already exists.
- HTTPException(500): If an error occurs while cloning the spec.
# Spec Create Agentic Metadata
Source: https://docs.apigene.ai/api-reference/spec/spec-create-agentic-metadata
post /api/spec/{api_name}/create_agentic_metadata
Create agentic metadata for the specified spec.
Parameters:
- api_name (str): The name of the spec to re-index.
Returns:
- dict: confirmation message or error detail.
Raises:
- HTTPException(500): If an error occurs while re-indexing the functions.
# Spec Create From File
Source: https://docs.apigene.ai/api-reference/spec/spec-create-from-file
post /api/spec_from_file/
Create spec from uploaded file.
# Spec Create From Url
Source: https://docs.apigene.ai/api-reference/spec/spec-create-from-url
post /api/spec_from_url/
# Spec Delete
Source: https://docs.apigene.ai/api-reference/spec/spec-delete
delete /api/spec/{api_name}
Delete a spec by its API name.
Deletes the spec identified by its API name. Requires authentication.
Parameters:
- api_name (str): The name of the spec to delete.
Returns:
- dict: A confirmation message if the spec is deleted successfully.
Raises:
- HTTPException(404): If the spec with the provided API name is not found.
- HTTPException(500): If an error occurs while deleting the spec.
# Spec Get
Source: https://docs.apigene.ai/api-reference/spec/spec-get
get /api/spec/{api_name}
Get information about a specific spec. security_info and shared_security_info are omitted by default. Pass include_security=true as an org admin to receive those fields.
# Spec Get Agentic Metadata
Source: https://docs.apigene.ai/api-reference/spec/spec-get-agentic-metadata
get /api/spec/{api_name}/agentic_metadata
Create agentic metadata for the specified spec.
Parameters:
- api_name (str): The name of the spec to re-index.
Returns:
- list: Filtered agentic metadata entries where the corresponding operation is enabled.
Raises:
- HTTPException(500): If an error occurs while re-indexing the functions.
# Spec Get Agentic Metadata Common Parameteres
Source: https://docs.apigene.ai/api-reference/spec/spec-get-agentic-metadata-common-parameteres
get /api/spec/{api_name}/agentic_metadata_common_parameteres
Get agentic metadata common parameteres for the specified spec.
Parameters:
- api_name (str): The name of the spec to re-index.
Returns:
- dict: confirmation message or error detail.
Raises:
- HTTPException(500): If an error occurs while re-indexing the functions.
# Spec Get Schema
Source: https://docs.apigene.ai/api-reference/spec/spec-get-schema
get /api/spec/{api_name}/schema
Get a specific spec schema.
Retrieves the schema of a spec identified by its API name.
Parameters:
- api_name (str): The name of the spec to retrieve information for.
- current_user (dict): The current user making the request. Retrieved using dependency injection.
Returns:
- The OpenAPI spec in JSON format
Raises:
- HTTPException(404): If the spec with the provided API name is not found.
- HTTPException(500): If an error occurs while fetching the spec information.
# Spec Get Shared Security
Source: https://docs.apigene.ai/api-reference/spec/spec-get-shared-security
get /api/spec/{api_name}/shared-security
Get shared_security_info for a public (global) API.
Only Apigene organization can call this endpoint.
# Spec Insights
Source: https://docs.apigene.ai/api-reference/spec/spec-insights
get /api/spec/{api_name}/insigths
List spec insights for the specified spec.
Retrieves a list of operations for the specified spec identified by its API name.
Parameters:
- api_name (str): The name of the spec to list operations for.
- current_user (AuthUser): The current user making the request. Retrieved using dependency injection.
Returns:
- List[dict]: List of operations or error detail.
Raises:
- HTTPException(500): If an error occurs while listing operations.
# Spec Operation Examples
Source: https://docs.apigene.ai/api-reference/spec/spec-operation-examples
post /api/spec/{api_name}/operation_examples
Generate examples for a specific operation of the specified spec.
Generates examples for a specific operation of the specified spec identified by its API name.
Optionally specify the operation name, count, and index.
Parameters:
- api_name (str): The name of the spec to generate examples for.
examples for.
- payload (SpecExamplePayload): Payload containing operation name, count, and index flags.
- current_user (AuthUser): The current user making the request. Retrieved using dependency injection.
Returns:
- dict: Examples or error detail.
Raises:
- HTTPException(500): If an error occurs while generating the examples.
# Spec Operation Schema
Source: https://docs.apigene.ai/api-reference/spec/spec-operation-schema
post /api/spec/{api_name}/operation_schema
Returns the spec for a given operation.
Parameters:
- api_name (str): The name of the spec to list operations for.
- operation_name(str): The name of the operation to get the spec for.
- current_user (dict): The current user making the request. Retrieved using dependency injection.
Returns:
- List[dict]: List of operations or error detail.
Raises:
- HTTPException(500): If an error occurs while listing operations.
# Spec Operations
Source: https://docs.apigene.ai/api-reference/spec/spec-operations
get /api/spec/{api_name}/operations
List operations for the specified spec.
Retrieves a list of operations for the specified spec identified by its API name.
Parameters:
- api_name (str): The name of the spec to list operations for.
- current_user (dict): The current user making the request. Retrieved using dependency injection.
Returns:
- List[dict]: List of operations or error detail.
Raises:
- HTTPException(500): If an error occurs while listing operations.
# Spec Reindex
Source: https://docs.apigene.ai/api-reference/spec/spec-reindex
post /api/spec/{api_name}/reindex
Re-index the specified spec's functions.
Re-indexes the functions of the specified spec identified by its API name.
Optionally specify whether to drop the existing index.
Parameters:
- api_name (str): The name of the spec to re-index.
- payload (SpecReindexPayload): Payload containing the drop flag.
- current_user (AuthUser): The current user making the request. Retrieved using dependency injection.
Returns:
- dict: Re-indexing confirmation message or error detail.
Raises:
- HTTPException(500): If an error occurs while re-indexing the functions.
# Spec Reindex Status
Source: https://docs.apigene.ai/api-reference/spec/spec-reindex-status
get /api/spec/{task_id}/reindex_status
Retrieve the status of a re-indexing task.
Checks the status of the specified re-indexing task identified by the task_id.
Parameters:
- task_id (str): The ID of the task to retrieve the status for.
- current_user (AuthUser): The current user making the request. Retrieved using dependency injection.
Returns:
- dict: Task status and additional information.
Raises:
- HTTPException(404): If the task ID is not found.
# Spec Reindex Status Active
Source: https://docs.apigene.ai/api-reference/spec/spec-reindex-status-active
get /api/spec/{api_name}/reindex_status/active
Check if there's an active re-indexing task for the specified spec.
Checks for an active re-indexing task using the unique_id pattern (api_name + org_id).
Parameters:
- api_name (str): The name of the spec to check for active reindex tasks.
- current_user (AuthUser): The current user making the request. Retrieved using dependency injection.
Returns:
- dict: Task status and additional information if an active task is found, None otherwise.
# Spec Scopes
Source: https://docs.apigene.ai/api-reference/spec/spec-scopes
get /api/spec/{api_name}/available_scopes
List available scopes for the specified spec.
Retrieves a list of available scopes for the specified spec identified by its API name.
Parameters:
- api_name (str): The name of the spec to list operations for.
- current_user (dict): The current user making the request. Retrieved using dependency injection.
Returns:
- List[dict]: List of scopes or error detail.
Raises:
- HTTPException(500): If an error occurs while listing operations.
# Spec Set Shared Security
Source: https://docs.apigene.ai/api-reference/spec/spec-set-shared-security
put /api/spec/{api_name}/shared-security
Set shared_security_info for a public (global) API.
Only Apigene organization can call this endpoint.
When turning ON, current tenant security_info is copied to global.
# Spec Summary
Source: https://docs.apigene.ai/api-reference/spec/spec-summary
post /api/spec/{api_name}/summary
# Spec Update
Source: https://docs.apigene.ai/api-reference/spec/spec-update
post /api/spec/{api_name}/update
Update a spec with new information.
Updates an existing spec with new information provided in the payload.
Parameters:
- api_name (str): The name of the spec to update.
- payload (SpecInfo): The new information to update the spec with.
- current_user (dict): The current user making the request. Retrieved using dependency injection.
Returns:
- dict: A confirmation message if the spec is updated successfully.
Raises:
- HTTPException(500): If an error occurs while updating the spec.
# Spec Update Agentic Metadata
Source: https://docs.apigene.ai/api-reference/spec/spec-update-agentic-metadata
put /api/spec/{api_name}/update_agentic_metadata
Update agentic metadata for the specified spec.
Parameters:
- api_name (str): The name of the spec to update.
- agentic_metadata (dict): The metadata to be written.
Returns:
- dict: Confirmation message or error detail.
Raises:
- HTTPException(500): If an error occurs while updating the metadata.
# Spec Use Cases
Source: https://docs.apigene.ai/api-reference/spec/spec-use-cases
post /api/spec/{api_name}/use_cases
# Specs List
Source: https://docs.apigene.ai/api-reference/spec/specs-list
get /api/specs
List all available specs.
Retrieves a list of all available spec names or detailed information about each spec.
security_info secret values are never returned on list responses; the
security_info field is omitted entirely. Use
GET /spec/{api_name}?include_security=true (org admin) to load credentials.
security_info_configured and shared_security_info are retained for readiness UIs.
Parameters:
- current_org (AuthOrg): The current org making the request. Retrieved using dependency injection.
- include_all (bool, optional): Flag to include detailed information about each spec. Defaults to False.
Returns:
- Union[List[str], List[SpecInfo]]: A list of spec names or detailed information about each spec.
Raises:
- HTTPException(500): If an error occurs while fetching the specs.
# Get Platform Version Endpoint
Source: https://docs.apigene.ai/api-reference/system/get-platform-version-endpoint
get /api/platform/version
# Get Version
Source: https://docs.apigene.ai/api-reference/system/get-version
get /api/version
# Health Check
Source: https://docs.apigene.ai/api-reference/system/health-check
get /api/health
Health check endpoint with diagnostic information
# Task Background Run
Source: https://docs.apigene.ai/api-reference/task/task-background-run
post /api/task/{task_id}/background_run
# Task Create
Source: https://docs.apigene.ai/api-reference/task/task-create
post /api/task
Create a scheduled command for the current organization and user.
# Task Delete
Source: https://docs.apigene.ai/api-reference/task/task-delete
delete /api/task/{task_id}
# Task Generate
Source: https://docs.apigene.ai/api-reference/task/task-generate
post /api/task/generate
Legacy task generation from API specs — removed for scheduled commands.
# Task Get
Source: https://docs.apigene.ai/api-reference/task/task-get
get /api/task/{task_id}
# Task Get Scheduled Runs Results
Source: https://docs.apigene.ai/api-reference/task/task-get-scheduled-runs-results
get /api/task/{task_id}/scheduled_runs_results
# Task List
Source: https://docs.apigene.ai/api-reference/task/task-list
get /api/task
List scheduled commands visible to the current user.
Includes all commands owned by the user (any state), plus public commands.
# Task Update
Source: https://docs.apigene.ai/api-reference/task/task-update
put /api/task/{task_id}
# Delete a UI template
Source: https://docs.apigene.ai/api-reference/ui-templates/ui-template-delete
delete /api/ui-templates/{api_name}/{template_id}
Delete a UI template by ID.
Args:
api_name: API name to determine which database to use (global or tenant)
template_id: Unique identifier for the template
Returns:
UITemplateDeleteResponse indicating success
Raises:
HTTPException 404: If template not found
# Get a UI template by ID
Source: https://docs.apigene.ai/api-reference/ui-templates/ui-template-get
get /api/ui-templates/{api_name}/{template_id}
Get a UI template by ID with CSP configuration from database.
Database is determined from the template_id (format: {api_name}::{operation_id}::{type}).
The api_name URL parameter is ignored for DB routing.
CSP Configuration:
- Only uses manually configured CSP stored in the database (csp_config or ui_meta.csp)
- If no CSP is configured, returns empty CSP (self-contained, no external resources)
- All CSP fields are always included (empty arrays as placeholders when not needed)
Args:
api_name: API name (ignored, kept for URL compatibility)
template_id: Unique identifier for the template
Returns:
UITemplateResponse with template ID, HTML content, and CSP configuration (all fields included)
Raises:
HTTPException 404: If template not found
# Set a UI template as the default for its operation
Source: https://docs.apigene.ai/api-reference/ui-templates/ui-template-set-default
put /api/ui-templates/{api_name}/{template_id}/set-default
Set a UI template as the default for its operation.
This will unset is_default for all other templates in the same operation,
then set is_default=true for the specified template.
Args:
api_name: API name to determine which database to use (global or tenant)
template_id: Unique identifier for the template
Returns:
UITemplateSetDefaultResponse indicating success
Raises:
HTTPException 404: If template not found
# Create or update a UI template
Source: https://docs.apigene.ai/api-reference/ui-templates/ui-template-upsert
put /api/ui-templates/{api_name}/{template_id}
Create or update a UI template by ID.
If the template exists, it will be updated. Otherwise, a new template is created.
Templates are stored in the same database as the corresponding spec (global or tenant).
Args:
api_name: API name to determine which database to use (global or tenant)
template_id: Unique identifier for the template (client-provided)
data: Request body containing HTML content
Returns:
UITemplateActionResponse with the template ID and action performed
# List all APIs with their templates
Source: https://docs.apigene.ai/api-reference/ui-templates/ui-templates-list-all
get /api/ui-templates
List all APIs with all their templates grouped by API name.
Args:
detailed: If True, returns full template data including HTML. If False, returns summary only.
Returns:
AllAPITemplatesResponse (if detailed=True) or AllAPITemplatesSummaryResponse (if detailed=False)
with all APIs and their templates grouped by API name
# List all UI templates for an API
Source: https://docs.apigene.ai/api-reference/ui-templates/ui-templates-list-by-api
get /api/ui-templates/{api_name}
List all UI templates for a specific API/application.
Args:
api_name: API name (also used as application_id for search)
detailed: If True, returns full template data including HTML. If False, returns summary only.
Returns:
UITemplateListResponse (if detailed=True) or UITemplateSummaryListResponse (if detailed=False)
with list of all templates for the API
# List UI templates for an operation
Source: https://docs.apigene.ai/api-reference/ui-templates/ui-templates-list-by-operation
get /api/ui-templates/{api_name}/operations/{operation_id}
List all UI templates for a specific operation.
Args:
api_name: API name (also used as application_id for search)
operation_id: Operation ID to filter templates
Returns:
UITemplateListResponse with list of templates for the operation
# Retrieve User settings
Source: https://docs.apigene.ai/api-reference/user/retrieve-user-settings
get /api/user/settings
This endpoint retrieves a user settings configuration.
# Settings Update
Source: https://docs.apigene.ai/api-reference/user/settings-update
post /api/user/settings/update
Endpoint to update user-specific settings.
Compares the provided settings with existing stored settings for the authenticated user.
If changes are detected, the settings are updated accordingly. If no settings exist,
a new settings record is created for the user.
Args:
payload (Settings): A `Settings` object containing updated user preferences or values.
Returns:
dict: A confirmation message indicating whether the settings were updated or skipped.
Raises:
HTTPException 500: If a runtime error occurs during update.
# User Me
Source: https://docs.apigene.ai/api-reference/user/user-me
get /api/user/me
Endpoint to retrieve information about the currently authenticated user.
Returns user metadata including email, name, role, organization info, trial expiration, onboarding status,
and enabled features based on the organization's tier.
Args:
Returns:
UserInfo: A dictionary containing user and organization-specific metadata.
# User Signup
Source: https://docs.apigene.ai/api-reference/user/user-signup
post /api/user/signup/
Endpoint for user registration.
This endpoint allows users to sign up by providing necessary user data.
Upon successful registration, a new user is created and added to the database.
Self-service signup with org_name creates an Admin user and provisions the organization.
Parameters:
- user_data: UserCreate - Data required to create a new user.
Returns:
- dict: A dictionary containing a success message upon successful user creation.
# User Token
Source: https://docs.apigene.ai/api-reference/user/user-token
post /api/user/token
Endpoint to obtain an access token for authentication.
Authenticates the user via form-encoded credentials (`username` and `password`) and returns a bearer token.
This token can be used in the `Authorization` header for accessing protected endpoints.
Args:
form_data (OAuth2PasswordRequestForm): Includes `username` (email) and `password` as form fields.
Returns:
Token: An access token in bearer format.
Raises:
HTTPException 401: If the username or password is invalid.
HTTPException 500: If token creation fails due to internal error.
# Create a workflow for an agent
Source: https://docs.apigene.ai/api-reference/workflow/workflow-create
post /api/workflows/{agent_name}
# Delete a workflow
Source: https://docs.apigene.ai/api-reference/workflow/workflow-delete
delete /api/workflows/{agent_name}/{workflow_id}
# Get a workflow by id
Source: https://docs.apigene.ai/api-reference/workflow/workflow-get
get /api/workflows/{agent_name}/{workflow_id}
# List workflows for an agent
Source: https://docs.apigene.ai/api-reference/workflow/workflow-list
get /api/workflows/{agent_name}
# Run a stored workflow by id
Source: https://docs.apigene.ai/api-reference/workflow/workflow-run
post /api/workflows/{agent_name}/{workflow_id}/run
# Get a persisted HITL workflow run by id
Source: https://docs.apigene.ai/api-reference/workflow/workflow-run-get
get /api/workflows/{agent_name}/runs/{run_id}
# Get a workflow run by id (full detail, no checkpoint)
Source: https://docs.apigene.ai/api-reference/workflow/workflow-run-history-get
get /api/workflows/runs/{run_id}
Return a persisted workflow run for history/share detail views. Checkpoint data is omitted. Non-admins may only read their own runs.
# Resume a waiting_human workflow run (starter only)
Source: https://docs.apigene.ai/api-reference/workflow/workflow-run-resume
post /api/workflows/{agent_name}/runs/{run_id}/resume
# Workflow run activity histogram by status
Source: https://docs.apigene.ai/api-reference/workflow/workflow-runs-activity-timeline
post /api/workflows/runs/activity-timeline
Dense histogram over a rolling window (default 7 days), bucketed by time and run status. Admins see org-wide counts; members see only their own runs. Empty buckets are filled with zeros.
# List workflow run history (org-wide, summary projection)
Source: https://docs.apigene.ai/api-reference/workflow/workflow-runs-history-list
post /api/workflows/runs/list
Paginated workflow history. Admins see all; members see their own runs.
Returns summary rows (no steps/inputs/result/checkpoint). Prefer `agent_display_name` / `workflow_name` for UI labels.
# List runs for a workflow
Source: https://docs.apigene.ai/api-reference/workflow/workflow-runs-list
get /api/workflows/{agent_name}/{workflow_id}/runs
List runs for a specific agent workflow. Prefer POST /api/workflows/runs/list for org-wide history.
This endpoint returns stored runs for the workflow (checkpoint omitted).
# Update a workflow
Source: https://docs.apigene.ai/api-reference/workflow/workflow-update
put /api/workflows/{agent_name}/{workflow_id}
# Changelog
Source: https://docs.apigene.ai/changelog
Latest product updates and announcements for Apigene
End-user facing changes across Copilot, Agents, Workflows, and MCP Gateway since Apigene 5.0. Internal, infra, and CI-only releases are omitted.
## Agent zip export and import, and Design Agent Mock Mode
Move an agent between organizations as a `.zip` bundle, or design against a mock API when the real system is not ready yet.
### What's new
* **Agent bundle** — On **Versions**, **Export .zip** downloads the draft (instructions, skills, contexts, OpenAPI apps, MCP servers, workflows, and UI templates — not credentials). A published version can be downloaded from its row menu. On **Agents**, **Import** uploads a bundle: missing apps are created and indexed; existing apps are reused as they are. If the agent name already exists, update the draft (owners only) or create a copy
* **Mock Mode** — In Design Agent, choose **Mock Mode** (alongside **Create** and **Extend**). Describe a system that does not exist yet; Copilot provisions a mock application, builds an agent on it, and offers **Try in chat**. The session is available when a mock service is configured
* **Model catalog** — Built-in pickers include GPT-6 (Astra, Sol, Luna), Claude Opus 5.5 / Fable 5.1 / Sonnet 5, Grok 4.7, and Gemini 3.8 Flash
### Improvements
* Light-mode status and live/draft badge contrast
* Version compare reads older to newer
* Use case proposal cards fit a full idea on screen, with app icons on chips
* Tool calls show agent display names; RTL chevrons flip correctly
* Settings section cards match application tabs
* Marketplace **Try Now** waits for spec reindex before creating the agent
* Switching **Live** / **Design** refreshes home when the thread was started there
* Mock Mode setup shows elapsed time
## Live and Design workspaces, and Try Now with demo apps
Switch the sidebar between chatting (**Live**) and building agents (**Design**). Marketplace **Try Now** can provision demo applications so the agent is ready to run.
### What's new
* **Live / Design** — Toggle **Live** and **Design** in the sidebar. **Live** is chat, **Tasks**, and personal settings. **Design** groups **Build** (Agents, Applications, Skills, Context), **Monitor** (Actions, Workflows, Insights), and **Admin**. Members and phones stay in Live
* **Try Now** — On a marketplace plugin, **Try Now** installs (or reuses) the agent, can prepare recommended demo applications, connects the agent to Copilot, and opens chat in **Live**. First-time setup shows a progress sheet; click the spinning button to reopen it
* **Generative UI in chat** — Tool groups that render a UI stay expanded; workflow runs that show generative UI are not folded into the collapsed group
### Improvements
* Light theme contrast
* On mobile, the composer stays in view and mention/model pickers open as sheets
* Multi-line paste no longer doubles newlines
* Organization members can use models configured in org settings
* Failed API calls keep request and response data in **Actions** (when recording is on)
## Localization
Copilot is localized. Choose a language under **Settings → Personal → Language** (including Hebrew with RTL and Japanese). The preference is stored on your user.
## Side-by-side model comparison
Run the same prompt against two models in chat (organization opt-in).
### What's new
* **Model comparison** — Admins enable it under **Settings → Organization → Advanced → Model comparison**
* **Compare** — In chat, pick a second model and send. Chat as many turns as you need, then conclude for a review. Each comparison doubles token spend and may execute tools twice
## Agent Marketplace and sidebar navigation
Install industry agents from a private GitHub marketplace, and open core pages from the left nav.
### What's new
* **Agent Marketplace** — On **Agents**, browse and install agents from a Claude-plugin marketplace repo. Admins point the gallery at GitHub under **Settings → Organization → Agent Marketplace**
* **Sidebar** — **Agents**, **Tasks**, **Applications**, **Skills**, and **Context** are in the left navigation (not only the app menu)
### Improvements
* Shared agents stay read-only for non-creators
## Design Agent Create and Extend
Design Agent (Agent Builder) splits into creating a new agent versus extending an existing draft.
### What's new
* **Create** — Define a new agent's instructions, apps, and behavior
* **Extend** — Add a skill, workflow, or UI to the draft; **Publish** stays explicit
* **Draft chip** — Extend shows **Draft** as soon as a skill, workflow, or UI is added
### Improvements
* Create workflows from Copilot or MCP. The **New workflow** form is no longer on the agent **Workflows** tab — open a workflow there to **Edit** the graph
## Draft and live agent versions
Edit an agent without changing what chat and MCP run until you publish.
### What's new
* **Draft vs live** — **Save** updates the draft. Chat and the runtime MCP URL keep using the published **live** version
* **Publish** — On the agent's **Versions** tab, publish the draft (optional note) to create a numbered version and point live at it
* **Version history** — Compare draft to live, inspect a snapshot, restore a version into draft, or switch live to an earlier version (the MCP URL stays the same)
* **Live and Draft chips** — Agent cards and the editor show the live version (`vN`) and a **Draft** chip when unpublished changes exist
* **Design MCP** — `https://app.apigene.ai/agent/{name}/design/mcp` reads and writes the draft (skills, workflows, templates). The usual `/agent/{name}/mcp` URL stays on live
* **Owner-only edits** — Viewers of a shared agent can use the live agent but do not see design or mutation tools
### Improvements
* Agents list is no longer limited to the first 50 agents
## Native MCP login/logout and OS-aware shortcuts
Sign in to a native MCP server as yourself, and see the right modifier key for your OS.
### What's new
* **Login / Logout** — On the MCP dashboard, server detail, or @mention picker, complete OAuth in a popup or log out to switch accounts. Tokens are per user and apply to Copilot and the MCP gateway
* **OS-aware shortcuts** — Shortcut labels show `Ctrl` on Windows and `⌘` on macOS
### Improvements
* Native MCP tool lists follow pagination so servers with many tools are fully cached
## Paste screenshots into chat
Attach a screenshot from the clipboard without saving it first.
### What's new
* **Paste screenshot** — With the chat input focused, press `⌘V` / `Ctrl+V` to attach a clipboard image (screen capture, copied image, or a file copied from Finder / Explorer)
## Mention picker columns, skill zip upload, and workflow help
Find agents, MCP servers, and tools faster, upload a full skill folder, and look up workflow node docs on the graph.
### What's new
* **Mention picker columns** — Type `@` to browse **Agents**, **MCP**, and **Tools** in separate columns
* **Skill folder zip** — **Upload Skill** accepts a `.zip` of an Agent Skills folder (`SKILL.md` at the root or in a wrapper folder), not only a single `SKILL.md`
* **Workflow help** — Open in-app help from the graph or a run for node types, expressions, and limits
* **Extra HTTP headers** — Admins add per-provider request headers under **Settings → Organization → Model Settings** (for example `anthropic-workspace-id`)
### Improvements
* Hide or show the workflow mini map; clearer node inspector
* Agent Builder shortcut on the Agents page appears when creating a new agent
* Chat Agents list updates when an agent is renamed or deleted
## Visual workflow editing, URL-safe agent names, and host-screen Actions
Edit agent workflows on the graph (opt-in), create a workflow from the Agents page, and inspect 3270-style host screens in Actions.
### What's new
* **Visual workflow editor** — On an agent's **Workflows** tab, open a workflow and click **Edit** to add, connect, and inspect steps on the graph. **Save** compiles and stores the draft; **View** leaves edit mode and discards unsaved changes
* **New workflow** — Create a named workflow from the list (starts with a Set values step). You can still author or update graphs from Copilot chat or MCP
* **URL-safe agent names** — New agent names are lowercase kebab-case (`support-agent`). Spaces and underscores become hyphens as you type
* **Terminal response tab** — When an action response includes a host/terminal screen (`screenText`), Actions and shared action views show a **Terminal** tab with the rendered screen
### Improvements
* Agent and MCP pickers in chat show connection status, sort more consistently, and keep the MCP status panel above the tools list
* Mermaid diagrams in chat auto-fit to the message so large charts stay readable
* Postman collection import reports clearer conversion errors (including collections with comments or stray quotes)
* Insights user charts merge duplicate accounts that share the same email
## Install Hub projects as apps, Hub auth options, and Builder Hub skills
Bring OpenLegacy Hub contracts into Copilot as applications, choose how the org authenticates to Hub, and let Agent Builder wire a Hub-ready agent with a scoped skill.
### What's new
* **Install from OpenLegacy Hub** — On **Applications → Install Application**, choose **OpenLegacy Hub**, search projects, and install a project's OpenAPI as an application (shows method count, last updated, and an **Installed** badge)
* **Hub authentication** — Under **Settings → Organization → Open Legacy**, choose **API Key** (`x-api-key`) or **Bearer token** (`Authorization: Bearer`)
* **Test connection** — Verify the Hub URL and credential before saving; unsaved form values are used, and last-4 credentials reuse the stored secret
* **Hub skills in Agent Builder** — When you accept a use case that includes Hub projects, Builder attaches the **ol-hub** app and provisions a project-scoped skill with contract, method, and flow IDs so the agent can run Hub test flows without a discovery loop
### Improvements
* Hub project picker in Agent Builder includes contract methods as context for use-case proposals
* Clearer Hub connection errors when the server URL or credential cannot reach Hub
## OpenLegacy Hub in Agent Builder, scoped apps, and chat history fixes
Connect OpenLegacy Hub from org settings, pick Hub projects in Agent Builder, and keep Copilot mode and thread titles in sync as you move between chats.
### What's new
* **OpenLegacy Hub** — Under **Settings → Organization → Open Legacy**, enable the Hub, set the Hub Server URL and API key, and optionally **Use in Agent Builder**
* **Hub projects in Agent Builder** — Hub projects appear in the Apps picker; selecting a project includes contract methods as read-only context for use-case proposals
* **Builder app scope** — Limit Agent Builder recommendations to the apps (and Hub projects) you selected for that thread
* **Expandable use-case summaries** — Open a proposal on the card to read the full summary without leaving chat
### Improvements
* Historic threads restore Copilot vs Agent Builder mode without a UI flash
* Sidebar chat history updates when a thread is renamed or the list changes
* Clearer agent delete confirmation (localized title and button)
* Organization settings sections use consistent icons and borders
## Collapsed tool calls in chat
Long sequences of tool use no longer fill the transcript with one card per call.
### Improvements
* **Collapsed tool calls** — Consecutive tool invocations in a message collapse into a compact group; expand to inspect an individual call
* Same collapse behavior in public/shared chat views
## Outbound proxy, OpenRouter/Bedrock model control, and application filtering
Route integration calls through a corporate HTTP proxy, choose which OpenRouter and Bedrock models appear in Copilot, filter large application specs, and enforce stricter Agent Builder validation.
### What's new
* **Outbound HTTP proxy** — Admins set an org-wide proxy URL under **Settings → Organization → Outbound network**; all outbound API calls from integrations and actions use it (leave empty for direct egress)
* **OpenRouter model visibility** — Enable or disable individual OpenRouter models in org settings, including models fetched live from your OpenRouter account
* **Bedrock model visibility** — Same per-model toggles for Amazon Bedrock; the model list is loaded from your AWS account instead of a fixed catalog
* **Metadata filters** — On an application's **Metadata** tab, filter agentic metadata by **type** and **priority rating** (1–10) in addition to search
* **Operations filters** — On **Operations**, filter by HTTP method, path prefix, and tags when managing large OpenAPI specs
### Improvements
* **Agent Builder validation** — Creating an agent requires both a **description** and **instructions**; name (64), description (300), and instructions (4,000) character limits match the API
* **Insights date ranges** — Custom start/end dates in Insights include the full selected UTC days (fixes edge cases with absolute date windows)
## Insights exports, chat drag-and-drop, and a cleaner sidebar
Pick custom date ranges and export charts from Insights, attach files by dropping them into chat, and navigate with a collapsible sidebar and smoother page transitions.
### What's new
* **Custom date ranges in Insights** — Choose an absolute start and end date (not only presets); Agents analytics respects the same window
* **Chart export** — Download Insights charts as CSV, PNG, or SVG, with summary stats on chart cards
* **Drag-and-drop attachments** — Drop files onto the chat input to attach them
* **Collapsible sidebar** — Collapse the nav to icon mode; chat thread groups can expand/collapse and remember your preference
* **Richer image generation** — Generate images with OpenAI GPT image models and DALL·E options (model, size, and quality)
### Improvements
* **Built-in tools cleanup** — Unused default tools (NanoBanana image, 3D/animation, HTTP, web content) are hidden from @ mentions and workflows
* **Cleaner chat display** — Mention prefixes are stripped from user messages when viewing and copying
* **Smoother navigation** — Light transition when moving between pages; consistent page headers across the app
* **Deep-linkable tabs** — Agent editor and Insights tabs stay in sync with the URL
* **Workflow inspector** — Clearer node summaries without duplicated metadata
## Per-user credentials, unified Insights, and Agent Builder in the nav
Let each teammate connect their own API secrets, find analytics under Insights, and open Agent Builder from the sidebar.
### What's new
* **Per-user app credentials** — On an application's **Security** tab, set **Credential scope** to **Per-user** (Basic / Bearer / API key). Each person connects their own secret via **Connect** / **Clear credentials** (or the connect-credentials link from chat)
* **Org-shared vs per-user** — Keep org-wide shared secrets when you want one key for everyone; switch to per-user when each member must use their own
* **Agents tab in Insights** — Org rollup of agent performance (volume, success rate, duration, errors) plus drill-down into a single agent
* **Agent Builder in navigation** — Open Agent Builder from the main sidebar and user menu (next to New Chat)
### Improvements
* **Insights replaces Dashboard** — Conversations, Workflows, Actions, and Agents analytics live under **Insights** (the separate Dashboard page is gone)
* **RTL-aware chat** — Hebrew and Arabic messages, chips, and input align correctly (auto LTR/RTL)
* **Reasoning duration** — Elapsed time shown while the model is thinking
* **Chat polish** — Message actions appear on hover; clearer model-selector loading; Chat / Agent Builder mode control stays in a consistent place
## LLM cost dashboard, model visibility, and Exa web search
Estimate chat spend, control which models appear in selectors, configure Exa for web search, and apply OnPrem licenses.
### What's new
* **LLM cost on Dashboard** — Conversations tab shows estimated spend over time, by model, by provider, and by user (toggle cost vs tokens)
* **Workflow analytics on Dashboard** — Workflows tab with KPIs, runs over time, success rate, duration, failures by step, and breakdowns by agent / user / workflow
* **Date range presets** — Quick ranges on the Dashboard date picker
* **Model visibility** — Per-provider **Models** menu in org settings to show or hide models in the Copilot selector
* **Custom model IDs** — Add provider-specific model IDs so they appear alongside built-in options
* **Exa (Web Search)** — Configure an Exa API key under organization model providers for web search / content tools
* **OnPrem license apply** — Self-hosted admins paste a signed license token in **Settings → Organization** (`POST /api/org/apply_license`)
### Improvements
* Clearer trial and license messaging for self-hosted installs
## Map loops, richer expressions, and workflow polish
Iterate arrays with clear loop/done ports, and write more expressive workflow formulas.
### What's new
* **`apigene.map` loop / done** — Loop body on the first output; **done** arm receives the collected items array (n8n-style Loop Over Items)
* **Nullish coalescing (`??`)** — Prefer defaults only when a value is `null` (unlike `||`, which also skips `0` / `""` / `false`)
* **`find` and `filter_by`** — Look up or filter array objects by field in workflow expressions
* **Flatter `set` assignments** — Assignment lists accept a simpler flat array shape when authoring workflows
### Improvements
* Clearer map edge labels and inspector hints in the workflow graph
* Light-theme consistency across Copilot UI
* More reliable simulation step indexing and feedback
## Workflow History and run simulation replay
Review past workflow runs like Actions history — filter, share, and replay step-by-step on the graph.
### What's new
* **Workflows history** — New **Workflows** nav item with org-wide run history (admins see all; members see their own)
* **Run detail** — Inputs, step traces, and result with copy/share; default **Simulation** opens the graph replay for the recorded run
* **Activity timeline** — Last-7-days histogram by run status with brush-to-filter (same pattern as Actions)
* **Workflow Recording** — Organization setting: **Full**, **Headers only**, or **Disabled** (HITL approval checkpoints still persist when disabled so resume works)
* **Share links** — Share a run via `/workflow-history/share/{run_id}` with the same detail + simulation UI
### Improvements
* Real non-dry-run executions are persisted when a workflow id is present (not only approval waits)
* Display names for agent and workflow in the history table and detail view
* Dry runs are never written to history
## Workflow dry-run, outputs, and richer run insights
Simulate workflows before going live, shape final results with an output node, and inspect each step more clearly.
### What's new
* **Dry-run / simulation** — Run a workflow without side effects to validate logic, see step status on the graph, and review inputs and outputs in the inspector
* **Output node (`apigene.output`)** — Define the final structured result of a workflow run
* **On-error handling** — Configure how workflows respond when a step fails
* **Richer expressions** — Inline object and array literals and improved nesting in workflow expressions
* **MCP** — `run_workflow` supports `dry_run` and optional step data in results
### Improvements
* Copy and download workflow run results as JSON
* Step tracing, elapsed time, and result size in the workflows UI
* Resizable workflow inspector and clearer run status visualization
## Approvals, LLM steps, and parallel joins
Pause for human approval, call an LLM inside a workflow, and join parallel branches before continuing.
### What's new
* **Human-in-the-loop approvals** — Pause a run for review, then approve or reject and resume from Copilot or MCP (`resume_workflow`)
* **LLM node (`apigene.llm`)** — Call a language model as a first-class workflow step
* **Join node (`apigene.join`)** — Wait for parallel branches and continue with combined results
* **Richer conditions** — More string operators for `if` / expression logic
### Improvements
* Clearer graph UI for approved, rejected, and waiting nodes
* Better workflow compile and lint error messages
## Agent workflows and chat pinning
Build, lint, and run multi-step agent workflows from Copilot and MCP, and keep important chats pinned.
### What's new
* **Workflows on agents** — Create and manage workflows from a dedicated Workflows tab
* **Workflow graph editor** — Design steps visually with improved layout and node tooling
* **Workflow linting** — Catch compile issues early with actionable hints
* **MCP workflow tools** — Author, run, and manage workflows from MCP clients
* **Pin chat threads** — Pin important conversations in the sidebar
* **Dashboard analytics** — Conversation analytics on the dashboard
### Improvements
* Clearer message timestamps in chat
* More reliable interactive / streaming app handling in chat
## Chat layout fix
### Fixes
* Empty chat is centered again (layout no longer stretches when there are no messages)
## Interactive apps in chat and safer secrets
### What's new
* **Interactive apps in chat** — Richer in-conversation app experiences alongside assistant replies
### Improvements
* Interaction history masks sensitive values
* Application / spec APIs no longer return stored security secrets in list and update responses
## Tasks, chat search, and app secrets
Schedule and run tasks from Copilot, find threads faster, and manage provider secrets more safely.
### What's new
* **Tasks** — Create, schedule, and run tasks from the product navigation and task management UI
* **Model per task** — Choose which chat model a task uses
* **Thread search and filters** — Search and filter conversations in the sidebar
* **Provider secret management** — Clearer handling of secrets for application / provider configuration
### Improvements
* Faster chat loading and paginated thread history
* “Run now” for tasks no longer times out behind long-running proxies
* Task names must be unique within the organization
* MCP lists can include tool details when needed
## Agent skills download and clearer errors
### What's new
* **Download agent skills** — Export an agent's skill harness as a downloadable package from the agent editor
### Improvements
* Friendlier error screens with **Try again** and **Go home** instead of the default crash page
## Chat file handling and prompt input
### Improvements
* More reliable file handling in chat and the prompt input
* More responsive prompt input layout on smaller screens
## Use-case proposals and app server URL
### What's new
* **Use-case proposals in chat** — Prompt input can surface suggested use cases to get started faster
* **Server URL selection** — Choose and validate the application server URL in app settings
### Improvements
* Smoother loading behavior on the audit logs page
## Chat commands, follow-ups, and audit coverage
Save reusable chat prompts, control follow-up suggestions, and see more sensitive activity in audit.
### What's new
* **Chat commands (prompt presets)** — Save, pick, and reuse prompts from the chat input, including agent selection
* **Follow-up suggestions** — Toggle suggested follow-up prompts in chat settings
* **Personal settings snapshots** — Manage settings snapshots from personal settings
* **Broader audit logging** — Audit entries for API token generation and organization settings changes
### Improvements
* Interaction / action views handle redacted request bodies safely
* Organizations can control when interaction bodies are recorded
* Prompt commands are sorted by name for easier browsing
## Chat message queue, skills download, and clearer model errors
Keep typing while the assistant works, download skill docs, and get clearer Bedrock feedback.
### What's new
* **Message queue** — Queue follow-up messages while a chat response is still running
* **Download `SKILL.md`** — Export skill documentation from the skills table
* **More file types in chat** — Broader file support in the prompt input
* **LLM checks on install** — Installing an application checks that a model provider is configured
### Improvements
* Clearer Bedrock chat errors and filtering of unavailable / end-of-life models
* Agent icons display correctly in the tool picker and selected-agent list
* Better reindexing status feedback on application metadata
## Keycloak authentication
### What's new
* **Keycloak auth provider** — Sign in with Keycloak for deployments that use enterprise IdP authentication
## Reasoning support and new models
### What's new
* **Model reasoning** — Copilot supports generic model reasoning with configurable reasoning effort
* **Fable 5** — Fable 5 available as a chat model option
## Mock execution for API actions
Test applications without hitting live APIs.
### What's new
* **Mock execution mode** — Generate mock API responses for interactions when mock mode is enabled
* **Optional LLM fallback for mocks** — Prefer schema-based mocks by default; optionally fall back to an LLM when examples are insufficient
* **Force reindex** — Force an application reindex when refreshing agentic metadata
## Skills upload UX and branding polish
### Improvements
* Tabbed skill upload dialog with clearer file mapping
* More consistent branding and localization across Copilot
## Apigene 5.0 — org models, skill registry, and self-serve auth
First 5.x release: tenant-scoped models, discoverable skills, and Apigene-native sign-in.
### What's new
* **Org-scoped model credentials** — LLM keys come from **Settings → Models** per organization (no shared global `OPENAI_API_KEY` on the API)
* **Amazon Bedrock & Microsoft Foundry** — Configure Bedrock (including API-key auth) and Azure / Microsoft Foundry providers with clearer validation
* **Skill registry** — Find and install skills from the skill registry in Agent Builder
* **Apigene authentication** — Native Apigene sign-in adapter and sign-in UI (alongside existing providers)
* **Self-service organizations** — Admins can create an organization during signup
* **GPT-5.5** — GPT-5.5 available in the model list
### Improvements
* Searchable model picker with collapsible providers
* Clearer organization settings layout with sticky save for unsaved changes
# Welcome to Apigene
Source: https://docs.apigene.ai/index
Build powerful AI applications with natural language API interactions
## What is Apigene?
Apigene is an AI-powered platform that enables you to interact with APIs and services using natural language. Instead of writing code or making manual API calls, simply describe what you want to accomplish, and Apigene's AI Copilot executes the necessary actions.
## Key Features
Interact with multiple applications using natural language conversations
Connect AI assistants like Claude Desktop and Cline to Apigene using the Model Context Protocol
Install and configure API integrations from OpenAPI specifications
Create specialized AI assistants with custom instructions and capabilities
Manage reusable context items for consistent AI interactions
Monitor conversations, agents, workflows, and action analytics
Track and analyze all API calls executed by Copilot
Track system changes and configuration activities
Configure your workspace, preferences, and integrations
## Quick Start
Add API integrations by uploading OpenAPI specifications or connecting to API endpoints.
[Learn about Applications →](/user-guide/applications)
Set up authentication for your applications to enable API calls.
[Configure Applications →](/user-guide/applications#security-configuration)
Begin interacting with your applications using natural language in Copilot.
[Get Started with Copilot →](/user-guide/copilot)
Build specialized agents for common workflows and tasks.
[Create Agents →](/user-guide/agents)
## Popular Use Cases
### Development Workflows
* Automate GitHub issue creation and management
* Trigger CI/CD pipelines
* Deploy applications
* Monitor application logs
### Customer Support
* Create and manage support tickets in Jira
* Send notifications to Slack channels
* Query knowledge bases
* Update customer records in CRM
### Data Operations
* Query databases and APIs
* Generate reports and analytics
* Export data to various formats
* Sync data between systems
### Marketing & Sales
* Manage email campaigns
* Post to social media
* Track analytics and metrics
* Update CRM records
## Platform Components
### Copilot
The conversational AI interface where you interact with applications using natural language. Copilot understands your intent, selects the right tools, and executes API calls on your behalf.
[Explore Copilot →](/user-guide/copilot)
### MCP Gateway
Connect external AI assistants and chatbots to Apigene using the Model Context Protocol (MCP). Enable tools like Claude Desktop, Cline, or any MCP-compatible client to discover and execute actions across your integrated applications.
[Learn about MCP Gateway →](/user-guide/mcp-gateway/mcp-gateway-overview)
### Applications
API integrations based on OpenAPI specifications. Each application provides tools that Copilot can use to interact with external services.
[Learn about Applications →](/user-guide/applications)
### Agents
Specialized AI assistants configured with specific instructions, tools, and behaviors. Agents enable consistent, reusable workflows.
[Create Agents →](/user-guide/agents)
### Context
Reusable pieces of information that provide consistent data, instructions, or knowledge across conversations.
[Manage Context →](/user-guide/context)
### Insights
Analytics about your usage — conversations and LLM cost, agent performance, workflow health, and API action volume.
[View Insights →](/user-guide/insights)
### Actions
Detailed logs of all API calls executed by Copilot, including request/response data and performance metrics.
[Review Actions →](/user-guide/actions)
### Audit Logs
Comprehensive records of system-level changes and configuration activities for compliance and security.
[Check Audit Logs →](/user-guide/audit)
## Getting Help
### Documentation
Browse our comprehensive user guides and API reference documentation to learn about all features.
### Support
Contact our support team at [support@apigene.ai](mailto:support@apigene.ai) for assistance.
### API Reference
Explore our API documentation to integrate Apigene into your applications.
[View API Reference →](/api-reference/api-authentication)
## Next Steps
Start with our user-facing documentation
Integrate Apigene into your applications
Follow our getting started guide
Learn from real-world examples
# Actions
Source: https://docs.apigene.ai/user-guide/actions
Monitor and analyze API calls executed by Copilot
## Overview
Actions are the individual API calls that Copilot executes on your behalf. The Actions page provides a comprehensive log of all API interactions, allowing you to monitor, debug, and analyze your application usage.
![Actions page listing recent API interactions]()
## What Are Actions?
Every time Copilot interacts with an application, it creates an action record that includes:
* **Request details**: What was sent to the API
* **Response data**: What the API returned
* **Performance metrics**: How long the call took
* **Status information**: Success or failure
* **User context**: Who initiated the action
How much of the request/response body is stored depends on your organization's **Interaction Recording** policy (full bodies, headers only, or disabled). See [Settings](/user-guide/settings#interaction-recording-organization). Failed calls still keep the outbound request and a structured error response when full recording is on.
## Accessing Actions
In the **Design** workspace, open **Monitor → Actions**.
## Action List View
### Information Displayed
Each action in the list shows:
**Timestamp**
* When the action was executed
* Formatted as date and time
* Sortable and filterable
**User ID**
* Which user initiated the action
* Links to user details
* Filter by specific users
**Application**
* Which API was called
* Application name and title
* Quick access to application settings
**User Input**
* The original request that triggered the action
* Natural language query from Copilot
* Context about why the action was taken
**Duration**
* How long the API call took
* Measured in milliseconds
* Performance indicator
**Status Code**
* HTTP response code (200, 404, 500, etc.)
* Color-coded for quick identification
* **Green**: Success (2xx)
* **Yellow**: Client errors (4xx)
* **Red**: Server errors (5xx)
**Cache Status**
* Whether the response was cached
* Improves performance for repeated queries
* Reduces API calls
## Search and Filter
### Search Actions
Use the search bar to find specific actions:
* Search by user ID
* Search by application name
* Search by user input text
* Search by API operation
* Real-time filtering as you type
### Advanced Filters
Click the **Filters** button to access advanced filtering:
**Resource Type**
* Filter by application/API
* Select specific applications
* View all or narrow down
**Action Type**
* Filter by HTTP method (GET, POST, PUT, DELETE)
* Focus on specific operation types
**Status Code**
* Success (2xx)
* Client errors (4xx)
* Server errors (5xx)
* Custom status codes
**Date Range**
* Start date
* End date
* View actions within specific timeframes
* Useful for auditing and analysis
**User Filter**
* Filter by specific user IDs
* See actions from particular team members
* Audit individual user activity
### Applying Filters
1. Click **Filters** button
2. Configure your filter criteria
3. Click **Apply** to filter results
4. Click **Clear** to reset all filters
## Activity Timeline
Click **Last 7 days** (or **7d** on mobile) to show an **activity timeline** above the actions table. The timeline summarizes API activity over the past week so you can spot spikes, errors, or unusual patterns before drilling into individual rows.
The timeline refreshes when you reload actions or change filters.
## Compare Actions
Use **Compare** to diff two action records side by side:
1. Click **Compare** in the toolbar to enter compare mode
2. Select **exactly two rows** in the table (checkboxes appear in compare mode)
3. Click **View diff** to open a fingerprint comparison (earlier vs later by timestamp)
Compare mode is useful when debugging regressions — for example, the same API call that succeeded yesterday but fails today. Exit compare mode with **Cancel**.
You can compare at most two actions at a time. Uncheck one row before selecting a third.
## Action Details
Click on any action to view complete details:
### Overview Information
**Action Summary**
* Unique action ID
* Timestamp (precise date and time)
* User who executed it
* Application used
* Status code with indicator
### Request Details
**HTTP Method**
* GET, POST, PUT, DELETE, PATCH, etc.
* Shows the type of operation
**Endpoint URL**
* Full API endpoint that was called
* Path parameters included
* Query parameters visible
**Request Headers**
* All headers sent with the request
* Authentication headers
* Content-Type, Accept, etc.
**Request Body**
* Payload sent to the API
* Formatted JSON/XML
* Copy to clipboard functionality
### Response Details
**Response Status**
* HTTP status code
* Status message
* Success/failure indicator
**Response Headers**
* Headers returned by the API
* Content-Type, Cache-Control, etc.
* Rate limit information if available
**Response Body**
* Full response from the API
* Formatted and syntax-highlighted
* Expandable/collapsible sections
* Copy to clipboard functionality
When the response includes a host/terminal screen (`screenText` — typical of 3270-style or MCP host sessions), a **Terminal** tab appears next to the raw and processed views. It renders the screen text, input fields, and cursor so you can inspect the host UI without reading the JSON payload. The same tab is available on shared action links.
If your organization uses **Headers only** interaction recording, request and response **bodies are redacted**. You still see headers and payload size metadata. If recording is **Disabled**, new actions are not stored. Admins configure this under [Settings → Organization → Interaction Recording](/user-guide/settings#interaction-recording-organization).
**Response Size**
* Raw response size in bytes/KB/MB
* Content size after processing
* Performance indicator
### Performance Metrics
**Duration Breakdown**
* Total request duration
* Network time
* Processing time
* Response parsing time
**Cache Information**
* Whether response was cached
* Cache hit/miss
* Cache expiry information
## Action Management
### Refresh Actions
Click the **Refresh** button to:
* Load latest actions
* Update the list
* Check for new activity
### Pagination
Navigate through large action lists:
* **Items per page**: Choose 10, 20, 50, or 100 entries
* **Previous/Next**: Navigate between pages
* **Page indicator**: Shows current page and total pages
### Export Actions
Export action data for analysis:
1. Apply filters to narrow down actions
2. Click export button (if available)
3. Choose format (CSV, JSON)
4. Download the file
## Understanding Status Codes
### Success Codes (2xx) - Green
**200 OK**
* Request succeeded
* Response body contains requested data
**201 Created**
* Resource successfully created
* Response includes new resource details
**204 No Content**
* Request succeeded
* No response body
### Client Error Codes (4xx) - Yellow
**400 Bad Request**
* Invalid request format
* Missing required parameters
* Check request body and parameters
**401 Unauthorized**
* Authentication failed
* Check credentials in application settings
* Token may have expired
**403 Forbidden**
* Authentication succeeded but access denied
* Check account permissions
* Verify required scopes
**404 Not Found**
* Resource doesn't exist
* Check resource ID
* Verify endpoint URL
**429 Too Many Requests**
* Rate limit exceeded
* Wait before retrying
* Review rate limit policies
### Server Error Codes (5xx) - Red
**500 Internal Server Error**
* API server error
* Not your fault
* Retry later or contact API provider
**502 Bad Gateway**
* Gateway/proxy error
* Temporary issue
* Retry after a moment
**503 Service Unavailable**
* API temporarily down
* Scheduled maintenance or outage
* Check API status page
## Use Cases
### Debugging
**Identify Failures**
1. Filter by error status codes (4xx, 5xx)
2. Review failed actions
3. Check request details
4. Identify the root cause
5. Fix configuration or parameters
**Reproduce Issues**
1. Find the failing action
2. Copy request details
3. Test manually or in Copilot
4. Verify the fix
### Performance Analysis
**Slow Requests**
1. Sort by duration (longest first)
2. Identify slow endpoints
3. Review request complexity
4. Consider optimization strategies
**Cache Effectiveness**
1. Filter by cached actions
2. Calculate cache hit ratio
3. Identify cacheable patterns
4. Optimize caching strategy
### Security Auditing
**Access Review**
1. Filter by date range
2. Review which APIs were called
3. Check for unusual patterns
4. Verify proper access controls
**User Activity**
1. Filter by specific users
2. See what actions they performed
3. Audit for compliance
4. Review sensitive operations
### Usage Tracking
**Application Usage**
1. Group by application
2. Count actions per application
3. Identify most-used APIs
4. Optimize or expand integrations
**Pattern Analysis**
1. Review common user inputs
2. Identify frequent operations
3. Create agents for common tasks
4. Improve automation
## Best Practices
### Regular Monitoring
**Daily Review**
* Check for error spikes
* Monitor performance trends
* Verify authentication status
* Review unusual activity
**Weekly Analysis**
* Generate usage reports
* Identify optimization opportunities
* Review new integrations
* Clean up failed configurations
### Error Management
**Immediate Action on Errors**
1. Set up alerts for critical failures
2. Review 401/403 errors immediately (auth issues)
3. Investigate 5xx errors with API provider
4. Document and fix 4xx errors
**Error Prevention**
* Test integrations before production use
* Validate credentials regularly
* Monitor rate limits
* Keep application configurations updated
### Performance Optimization
**Identify Bottlenecks**
* Find consistently slow endpoints
* Review large response sizes
* Optimize query parameters
* Consider pagination for large datasets
**Leverage Caching**
* Identify cacheable operations
* Review cache hit rates
* Adjust cache strategies
* Balance freshness vs performance
## Troubleshooting
### Actions Not Appearing
**Possible Causes**
* No actions have been executed yet
* Filters are too restrictive
* Date range excludes all actions
* Page needs refresh
**Solutions**
* Execute some actions in Copilot first
* Clear all filters
* Expand date range
* Click Refresh button
### Can't See Action Details
**Possible Causes**
* Insufficient permissions
* Action data was purged
* Network connectivity issue
**Solutions**
* Check user permissions
* Verify action ID is correct
* Refresh the page
* Contact administrator if needed
### Filters Not Working
**Possible Causes**
* Invalid filter criteria
* No actions match filters
* Filter syntax error
**Solutions**
* Try simpler filters first
* Verify data exists in selected range
* Clear and reapply filters
* Use search instead
## Privacy and Data Retention
### Data Stored
Actions store:
* Request and response metadata
* User information
* Timestamps and performance metrics
* Status codes and errors
### Data Security
* All action data is encrypted
* Access controlled by user permissions
* Sensitive data can be masked
* Compliant with data regulations
### Data Retention
* Actions are retained based on your plan
* Historical data for analysis and auditing
* Export before retention period expires
* Automatic cleanup of old data
## Integration with Other Features
### Insights Analytics
Actions feed into [Insights](/user-guide/insights):
* Daily action usage charts
* Success/failure rates
* User activity graphs
* Application usage breakdown
### Audit Logs
System-level changes create audit logs:
* Application configuration changes
* Agent modifications
* Security updates
* User management
### Context Items
Actions can inform context creation:
* Common API patterns
* Frequent data access
* Usage-based recommendations
* Automation opportunities
## Next Steps
* [View analytics](/user-guide/insights) to understand usage patterns
* [Configure applications](/user-guide/applications) to reduce errors
* [Check audit logs](/user-guide/audit) for system changes
* [Use Copilot](/user-guide/copilot) to execute more actions
# Agent Builder
Source: https://docs.apigene.ai/user-guide/agent-builder
Create and configure AI agents through Design Agent (Create, Extend, or Mock Mode)
## Overview
**Design Agent** (documented here as Agent Builder) is a dedicated Copilot mode for designing, listing, inspecting, and configuring agents. Use it when you want to **define** an agent as a resource — instructions, applications, MCP servers, skills, and setup — rather than simply **chat** with one.
Chat mode is for having a conversation (optionally with one agent selected via `@`). Design Agent is for agent management: **Create** a new agent, **Extend** an existing draft with skills, workflows, or UI, or **Mock Mode** to stand up a mock API and an agent on top of it.
![Agent Builder mode home screen]()
## Chat vs Agent Builder
| | **Chat** | **Design Agent** |
| ------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Purpose** | Ask questions, run tools, use an agent in conversation | Create and configure agents |
| **Agent selection** | Pick one agent via `@` to shape behavior | **Create** a new agent, **Extend** an existing draft, or **Mock Mode** for a system that does not exist yet |
| **Tools available** | Application tools, workflows, MCP actions | Builder tools (search apps, generate instructions, create agent, etc.) |
| **Best for** | "Read my email", "Summarize this doc" | "Build me a support agent for Slack and Jira" |
If you ask in **Chat** to create an agent, list your agents, or inspect full agent configuration, Copilot will suggest switching to **Design Agent** and show a one-click shortcut card.
## Switching to Agent Builder
### From the Design workspace
Switch the sidebar to **Design**, then open **Design Agent** (top of the Design sidebar). Choose **Create**, **Extend**, or **Mock Mode** depending on whether you are defining a new agent, adding to an existing draft, or designing against a mock API.
Organization members and phones stay in **Live** and do not see Design Agent.
### From the home screen
On a **new chat** (home), use the **Live** / **Design** toggle:
1. **Live** (Chat) — default conversational mode
2. **Design** — agent creation and management mode (**Create**, **Extend**, or **Mock Mode**)
The message input border turns blue in Design Agent so you can tell which mode you are in at a glance.
The Live / Design toggle is in the sidebar for admins on desktop. From an ongoing Live thread, use the in-chat Design Agent shortcut card, or switch to **Design** and start a new Design Agent session.
### From an ongoing chat
When Copilot detects agent-management intent (create, list, clone, inspect config, compare agents), it can show a **Design Agent** shortcut card in the thread. Choose **Create** or **Extend** without leaving the conversation context. Use **Mock Mode** from the Design Agent session toggle when the backend API is not available yet.
You can also open **Build → Agents** in the Design workspace (`/agents`, `/agent/new`, `/agent/[id]`) for the full agent editor UI.
## What Agent Builder can do
Agent Builder uses specialized tools to help you end-to-end:
* **Discover applications** — search APIs and MCP servers, browse a preloaded catalog of installed and official integrations
* **OpenLegacy Hub** — when Hub is enabled, include Hub projects in app scope; Builder can provision a Hub skill and attach **ol-hub** when you build from those projects (see [OpenLegacy Hub](/user-guide/openlegacy))
* **Generate and refine instructions** — AI-drafted system prompts based on your use case
* **Skills** — search your org library and [skills.sh](https://skills.sh), propose skills to attach, and wait for your approval before creating the agent
* **Create and update agents** — name, optional display name, description, instructions, applications, MCP servers, contexts, and skills
* **Extend an existing agent** — add a skill, workflow, or generative UI to the draft (publish remains a separate step)
* **Clone agents** — start from an existing agent as a template
* **Mock a missing system** — in **Mock Mode**, provision a mock application and an agent that uses it
* **Validate configuration** — check names, instructions, and attachments before saving
* **Present results** — after creation, shows an agent card and setup instructions for connecting to Claude, Cursor, ChatGPT, and other MCP clients
## Recommended workflow
Agent Builder follows a guided flow. You do not need to memorize tool names — describe what you want in natural language.
### 1. Describe the agent
Start with a short brief, for example:
```
Build an agent that triages GitHub issues and posts summaries to Slack.
```
Agent Builder may ask **2–3 clarifying questions** about purpose, capabilities, and required integrations before proceeding.
### 2. Discover integrations
It searches your installed applications and official catalog, and recommends APIs (OpenAPI integrations) or native MCP servers as appropriate. Install native servers first via [Native MCP Servers](/user-guide/mcp-servers) when needed.
### 3. Optional: attach skills
If your use case maps to reusable workflows (SEO, code review, deploy runbooks, etc.), Agent Builder can:
1. Search your org **Skills** library and the public registry
2. Show an interactive **skill proposals** card (1–5 matches)
3. Wait for you to install, select, or skip — it never auto-installs without your choice
Skipped skills do not block agent creation.
Agent Builder (and Chat) can also show a **use case proposals** card when you ask for suggested workflows across apps — review the proposals before acting on them. See [Copilot → Use Case Proposals](/user-guide/copilot#use-case-proposals).
If **Use in Agent Builder** is on for [OpenLegacy Hub](/user-guide/openlegacy), Hub projects appear in the Apps picker. Selecting a project includes contract methods as read-only context. When you **Build** a use case that includes Hub projects, Agent Builder attaches the **ol-hub** application and provisions a project-scoped skill so the agent can run Hub test flows without rediscovering methods each turn.
### 4. Generate instructions
Agent Builder drafts a structured system prompt (role, guidelines, boundaries) and can refine it based on your feedback.
### 5. Validate and create
Configuration is validated before the agent is created:
* **Name** — required; up to 64 characters; lowercase kebab-case (`support-agent`). Spaces and underscores become hyphens
* **Display name** — optional; up to 64 characters; shown in chat and cards instead of `name`
* **Description** — required; up to 300 characters; short summary of what the agent does
* **Instructions** — required; up to 4,000 characters; system prompt / behavior
* Valid application, MCP, skill, and context references (OpenAPI-backed MCP proxies must be attached as **APIs**, not native MCP servers)
Agent Builder prompts for a description and instructions if either is missing.
### 6. Review setup
Immediately after creation:
* An **agent details card** appears in chat (click through to the edit page)
* An **agent setup** card shows how to connect the agent to external AI clients via MCP
### Mock Mode (system does not exist yet)
When the API is not available yet, switch the Design Agent session to **Mock Mode** (next to **Create** and **Extend**). Describe the domain and the job the agent should own. Agent Builder models a mock REST application, registers it, indexes it, creates the agent, and shows a setup card with elapsed time.
* Ask at most a couple of clarifying questions; provisioning then runs in the browser (typically one to three minutes)
* After success, **Try in chat** opens **Live** with a starter prompt
* You can also attach existing applications to the same agent when you name them
* **Mock Mode** appears only when a mock service is configured for the deployment. If it is missing, the session stays on **Create**
## Agent naming guidelines
Agent Builder enforces concise, URL-safe names:
* **2–3 words** recommended (e.g. `dev-assistant`, `support-bot`); hard limit **64 characters**
* Lowercase letters, numbers, and hyphens only (`support-agent`). Spaces and underscores become hyphens as you type
* Avoid long compound names like `dev-flow-assistant-github-jira`
* **Description** (max 300 characters) and **instructions** (max 4,000 characters) are both required at creation time
## Example prompts
**Create from scratch**
```
Create an agent that helps our sales team query Salesforce and draft follow-up emails.
```
**Clone and adapt**
```
Clone my support-bot agent and add Gmail so it can read customer threads.
```
**List and inspect**
```
List my agents and show which applications each one uses.
```
**Skills-focused**
```
Build a PR review agent. Search for skills related to code review and attach the best match.
```
**OpenLegacy Hub**
```
Build an agent for the Hub projects in this thread that can run contract test flows.
```
**Mock Mode**
```
Mock a fleet-maintenance system with vehicles and work orders, then build an agent that lists overdue jobs.
```
## After Agent Builder creates an agent
Fine-tune in the **Agents** editor:
* **Instructions** — edit the system prompt directly
* **Applications** — attach or remove OpenAPI integrations
* **MCP Servers** — native MCP attachments
* **Skills** — org skills library
* **Context** — reusable knowledge items
* **Generative UI** — visual templates for MCP App results (after the agent is saved)
* **Workflows** — create, visually edit, run, and simulate graphs
* **Versions** — publish draft changes to live, compare, restore snapshots, and export a `.zip` bundle
* **Setup** — live and design MCP URLs, per-tool toggles, and managed setup export
See [Agents](/user-guide/agents) for the full editor reference. Saving in the editor updates **draft**; [publish](/user-guide/agents#draft-live-and-version-history) when chat and the runtime MCP URL should use the change.
## Best practices
**Be specific about integrations**
* Name the systems you need (Slack, Jira, Gmail) so Builder picks the right apps
**Answer clarifying questions**
* Short answers upfront save back-and-forth later
**Use Chat for testing**
* After creation, switch to **Live**, start a new chat, and mention the agent with `@` to try it in a real conversation
**Iterate in the editor**
* Agent Builder gets you to a strong first version; use the Agents page for precise tool and instruction tweaks
* After the first save, further edits stay in **draft** until you **Publish** on the Versions tab — chat and the runtime MCP URL keep using live
## Troubleshooting
### I do not see the Design Agent toggle
* Switch the sidebar to **Design** (admins, desktop). Members and phones stay in **Live**
* Open **Design Agent** from the Design sidebar, or use the **Design Agent** shortcut card in a Live thread
### I do not see Mock Mode
* Switch to **Design** and open **Design Agent** on a **new chat** (the session toggle is locked after the first message)
* Mock Mode needs a mock service on the deployment. If it is not configured, the item is disabled and Copilot stays on **Create**
### Agent Builder created an agent but tools fail in Chat
* Open the agent in **Agents** → **Applications** / **MCP Servers** and confirm integrations are attached
* Configure **Security** credentials for each application
* Test with `@agent-name` in a fresh Chat thread
### Skills were skipped — can I add them later?
Yes. Open the agent → **Skills** tab, or browse the [Skills](/user-guide/skills) library and attach from there.
### Hub projects are missing from the Apps picker
* Enable **Use in Agent Builder** under **Settings → Organization → Open Legacy** and confirm **Test connection** succeeds
* See [OpenLegacy Hub](/user-guide/openlegacy) for install, Builder wiring, and troubleshooting
## Next steps
* [Agents](/user-guide/agents) — edit instructions, tools, generative UI, setup export, and `.zip` import/export
* [Skills](/user-guide/skills) — org skill library and registry
* [OpenLegacy Hub](/user-guide/openlegacy) — connect Hub, install projects, and build Hub-ready agents
* [Copilot](/user-guide/copilot) — use your agent in Chat mode
* [MCP Gateway](/user-guide/mcp-gateway/mcp-gateway-overview) — connect agents to external AI clients
# Agents
Source: https://docs.apigene.ai/user-guide/agents
Create and manage AI agents with specialized capabilities
## Overview
Agents are specialized AI assistants that can be configured with specific instructions, tools, and behaviors. They enable you to create focused, reusable AI workflows tailored to particular tasks or domains.
![Agents list with Create Agent card and MCP URLs]()
Open an agent to edit instructions, applications, skills, context, generative UI, workflows, and setup:
![Agent detail page showing Instructions tab for CI Bottleneck Analyzer]()
## What Are Agents?
Think of agents as expert assistants with:
* **Custom instructions**: Define how the agent should behave and respond
* **Specific tools**: Select which applications and APIs the agent can access
* **Consistent behavior**: Agents follow the same instructions every time
* **Shareable knowledge**: Make agents available across your organization
## Key Features
### Custom Instructions
Define exactly how your agent should operate:
* Personality and tone
* Domain expertise
* Response format
* Decision-making guidelines
### Tool Selection
Control which capabilities your agent has:
* Select specific applications
* Choose individual API operations
* Configure MCP servers access
* Set tool usage policies
### Visibility Control
Manage who can use your agents:
* **Private**: Only visible to you
* **Public**: Available to your entire organization
* Easy visibility toggle
### Version Control
Edit in **draft**, then **publish** when chat and MCP should pick up the change:
* **Save** writes the draft only — live stays on the last published version
* **Publish** (Versions tab) creates a numbered version and points live at it
* Compare, restore a snapshot into draft, or switch live to an earlier version without changing the MCP URL
## Creating an Agent
You can create agents in two ways:
1. **[Agent Builder](/user-guide/agent-builder)** (recommended) — conversational workflow in Copilot that discovers apps, drafts instructions, proposes skills, validates, and creates the agent
2. **Agents page** — manual form at **Agents** → **+ New Agent**
For most users, start in Agent Builder and refine in the editor afterward.
### Step 1: Navigate to Agents
1. Switch the sidebar to **Design** and open **Build → Agents**
2. Click the **+ New Agent** card
3. You'll see the agent creation form
### Step 2: Configure Basic Information
**Agent Name**
* Use lowercase kebab-case: letters, numbers, and hyphens only (for example `github-bot`, `support-agent`)
* Spaces and underscores are converted to hyphens as you type
* Maximum 64 characters; keep it short so MCP URLs stay readable
**Display Name** (Optional)
* Friendly label shown in chat, agent cards, and pickers (up to 64 characters)
* Leave empty to show the kebab-case name
* MCP URLs and `@` mentions still use the agent **name**
**Agent Description** (Optional)
* Explain the agent's purpose
* Describe what it's good at
* Helps team members understand when to use it
### Step 3: Write Instructions
This is where you define your agent's behavior. Good instructions include:
**Role Definition**
```
You are an expert GitHub repository manager who helps developers with code reviews and issue management.
```
**Capabilities**
```
You can:
- Create and update GitHub issues
- Review pull requests
- Search code repositories
- Manage project boards
```
**Guidelines**
```
When responding:
- Be concise and technical
- Always include relevant GitHub links
- Use markdown formatting
- Provide code examples when helpful
```
**Example Complete Instructions**
```
You are a customer support agent specializing in technical troubleshooting.
Your role is to:
1. Understand customer issues clearly
2. Search the knowledge base for solutions
3. Create support tickets for unresolved issues
4. Follow up with customers promptly
Guidelines:
- Always be polite and empathetic
- Ask clarifying questions when needed
- Provide step-by-step solutions
- Escalate complex issues to human agents
- Use bullet points for clarity
When creating tickets:
- Include all relevant customer information
- Tag with appropriate priority level
- Add reproduction steps if provided
```
### Step 4: Select Tools
Choose which applications and tools your agent can access:
**Applications (APIs)**
* Attach OpenAPI integrations installed in your workspace
* Each application exposes actions the agent can call
**MCP Servers**
* Attach [native MCP servers](/user-guide/mcp-servers) (not OpenAPI→MCP bridges — use Applications for those)
* Configure per-agent in the applications / MCP attachments area
* Install servers first from the MCP dashboard, official catalog, or registry
**Per-tool toggles (Setup tab)**
* Enable or disable individual MCP gateway tools for this agent (e.g. `list_skills`, `run_action`, `get_context`)
* Disabled tools are hidden from the agent at runtime
* Useful for least-privilege agents that should only call specific operations
**Default Toolkit**
* Enable to give access to all configured applications
* Good for general-purpose agents
* Simpler to manage
**Custom Tool Selection**
* Select specific applications only
* More precise control
* Better for specialized agents
### Step 5: Set Visibility
**Private Agent**
* Only you can see and use it
* Perfect for personal workflows
* Test agents before sharing
**Public Agent**
* Available to your entire organization
* Appears in everyone's agent list
* Great for team collaboration
### Step 6: Save and Test
1. Click **Save** to create your agent
2. Test it immediately in a new chat
3. Mention the agent using `@support-agent` (kebab-case name)
4. Refine instructions based on results
## Agent Editor Tabs
After creating an agent, the editor is organized into tabs:
| Tab | Purpose |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| **Instructions** | Name, optional display name, description, icon, and system prompt |
| **Applications** | OpenAPI integrations attached to the agent |
| **MCP Servers** | Native MCP server attachments |
| **Skills** | Org skills from your [Skills](/user-guide/skills) library |
| **Context** | Reusable context items |
| **Generative UI** | Visual templates for MCP App results (available after first save) |
| **Workflows** | List, create, visually edit, run, and simulate agent workflows |
| **Versions** | Draft vs live, publish, compare, version history, and `.zip` export (available after first save) |
| **Setup** | Live and design MCP URLs, per-tool toggles, managed setup export |
## Skills
Attach [Skills](/user-guide/skills) on the **Skills** tab to give the agent reusable workflows and domain procedures. At runtime the agent discovers skills via `list_skills` and loads full instructions with `get_skill_content` before applying them.
You can also attach skills during [Agent Builder](/user-guide/agent-builder) creation via the skill proposals card.
## Generative UI Templates
The **Generative UI** tab (visible after the agent is saved) lets you define visual templates for MCP App results — charts, tables, and custom layouts rendered in supported MCP hosts.
* Start from starter layouts or write a JSON / json-render style spec
* Preview with sample state before saving
* Keep dynamic values in template **state** so runtime data can merge
* Templates pair with `run_action_ui`, `run_multi_actions_ui`, and generative UI tools in MCP Gateway
For org-wide template libraries, GitHub sync, and clone/create flows, see [MCP Apps](/user-guide/mcp-apps).
See [MCP Gateway Tools](/user-guide/mcp-gateway/mcp-gateway-tools) for UI execution tools.
## Managed Agent Setup Export
On the **Setup** tab, expand **Managed agent setup (YAML / JSON)** to export a configuration document for external managed-agent platforms. The export includes:
* Agent name and system instructions (with skills workflow hints)
* MCP server URLs (agent gateway URL plus attached MCP servers)
* Tool set definitions
Copy as YAML or JSON for use in compatible deployment workflows.
## MCP connection URLs
On the **Setup** tab, copy the URL that matches how the client should use the agent:
| URL | What it uses |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| `/agent/{name}/mcp` | Published **live** version (chat, Cursor, Claude, and other runtime clients) |
| `/agent/{name}/design/mcp` | Unpublished **draft** — create or delete skills, workflows, and templates until you publish |
Example design URL:
```
https://app.apigene.ai/agent/{name}/design/mcp
```
Viewers of a shared agent can connect to the live URL. Design and mutation tools are hidden unless you own the agent.
## Draft, live, and version history
After the first save, the editor and agent cards show:
* A **vN** chip for the current live version
* A **Draft** chip when unpublished changes exist
**Save** updates draft only. Chat, Tasks, and `/agent/{name}/mcp` keep using live until you publish.
### Publish
1. Open the agent → **Versions**
2. Review the draft vs live summary (instructions, apps, MCP servers, skills, context, workflows, UI templates, tools)
3. Click **Publish**, optionally add a note, and confirm
Publish creates the next numbered version and points live at it. The public MCP URL does not change.
### History
The Versions table lists each published snapshot. Open a row for details, or use the row menu to:
* **Compare with live** — side-by-side diff of instructions and attachments (older on the left, newer on the right)
* **Download .zip** — export that published snapshot as an agent bundle (see [Export and import](#export-and-import-a-zip-bundle))
* **Restore into draft** — copy that version into draft (overwrites unpublished edits)
* **Switch live here** — point live at an earlier version without rewriting draft
New agents start version history on the first save (`v1`). Existing agents keep working as live; further saves stay in draft until you publish.
## Using Agents
### In Copilot
Invoke agents in your conversations:
**Direct Mention**
```
@github-bot please create an issue for the login bug
```
**Implicit Usage**
The agent's instructions guide the conversation context and behavior.
Pickers and agent cards show the optional **display name**. `@` mentions still use the kebab-case name.
### Agent Context
When you use an agent:
* Its instructions are added to the conversation
* Only specified tools are available
* The agent's personality shapes responses
* All mentions from instructions are inherited
## Managing Agents
### Viewing Agents
The Agents page lists every agent you can see (no 50-item cap). Cards show the **display name** when set, live version, and a **Draft** chip when unpublished changes exist.
**My Agents**
* Agents you created
* Private agents
* Full control to edit, publish, or delete
**Shared Agents**
* Public agents from your organization
* Created by team members
* View-only access (live version only)
### Export and import a zip bundle
Move an agent between organizations or environments (for example, design in one org and restore in another). The archive is a single `.zip` named `-.zip`. Credentials are never included — reconnect security on imported apps and MCP servers.
The bundle includes:
* Agent name, display name, description, icon, visibility, and instructions
* Attached skills, contexts, OpenAPI applications, and native MCP servers
* Workflows and generative UI templates
* Per-tool enable/disable settings
**Export**
1. Open the agent → **Versions**
2. Click **Export .zip** to pack the current **draft** (a progress state shows while it packs)
3. To export a published snapshot instead, open the version’s row menu and choose **Download .zip**
If some resources could not be read, the download still completes and Copilot notes how many warnings were skipped.
**Import**
1. Switch the sidebar to **Design** and open **Build → Agents**
2. Click **Import** and choose a `.zip` bundle
3. Review the plan (create vs update, which apps are **new** vs **reuse**)
4. If an agent with that name already exists:
* **Update the existing agent** — replaces the **draft** (only if you own it)
* **Create a copy** — pick a new kebab-case name
5. Click **Import** and wait for applications, skills/contexts/MCP servers, the agent, then workflows and UI templates
Existing applications are left unchanged. Missing applications are uploaded and indexed so their tools appear. After import, Copilot lists what was created, updated, reused, or skipped, and which connections you still need to configure.
You cannot update an agent you do not own — import creates a copy instead. Identity fields such as visibility can apply immediately (outside draft). If the target agent publishes on every save, the imported draft becomes live right away.
### Agent Marketplace
When an admin enables [Agent Marketplace](/user-guide/settings#agent-marketplace), the Agents page shows a catalog from a private GitHub repo (Claude plugin layout). Browse by industry or line of business, preview a listing, and install it as an agent in your organization.
**Try Now** installs (or reuses) the plugin agent, can prepare recommended demo applications so the agent has APIs to call, connects the agent to Copilot, and opens a **Live** chat with the agent mentioned. The first run for a line of business may take a minute and shows a progress sheet; later runs reuse what is already in place. Click the spinning **Try Now** button to reopen progress. **How it works** previews the plugin without installing. **Add to my agents** installs without opening chat.
If demo applications are not available in your deployment, **Try Now** still installs the agent as before.
### Editing Agents
1. Find your agent in "My Agents"
2. Click the **Edit** icon
3. Modify instructions, tools, or settings
4. Click **Save** to update the **draft**
5. Open **Versions** and **Publish** when new chats and MCP should use the change
Until you publish, existing conversations and the runtime MCP URL keep the last live version.
### Deleting Agents
1. Find your agent in "My Agents"
2. Click the **Delete** icon
3. Confirm the deletion
4. The agent is permanently removed
**Note**: Existing conversations using the agent will continue to work.
### Changing Visibility
Toggle between private and public:
1. Find your agent in the list
2. Click the visibility icon
3. Confirm the change
4. The agent moves to the appropriate section
## Agent Best Practices
### Writing Effective Instructions
**Be Specific**
* ❌ "Help users with GitHub"
* ✅ "You are a GitHub automation assistant that creates issues, manages pull requests, and updates project boards based on user requests"
**Define Boundaries**
```
You can:
- Create and update issues
- Comment on pull requests
- Search repositories
You cannot:
- Delete repositories
- Modify security settings
- Access private repositories without permission
```
**Include Examples**
```
Example interaction:
User: "Create an issue for the login bug"
You: "I'll create a GitHub issue. What should the title be?"
User: "Login fails with special characters"
You: *creates issue with title, asks for description*
```
### Tool Selection Strategy
**Specialized Agents**
* Select only necessary applications
* Reduces confusion and errors
* Improves response accuracy
* Example: GitHub-only agent for code management
**General Purpose Agents**
* Use default toolkit
* Enable multiple applications
* Good for exploratory workflows
* Example: Research assistant with web search, docs, and email
### Naming Conventions
Use clear, descriptive names:
* **Good**: "Jira Issue Creator", "Slack Notifier", "Data Export Assistant"
* **Avoid**: "Agent1", "My Agent", "Test"
Include the domain or platform in the name when relevant.
## Common Agent Types
### Support Agent
```
You are a customer support specialist.
Responsibilities:
- Answer customer questions
- Search documentation
- Create support tickets
- Track issue resolution
Always:
- Be empathetic and professional
- Verify information before responding
- Follow up on open issues
- Provide ticket numbers for tracking
```
### Development Assistant
```
You are a development workflow assistant.
You help developers by:
- Creating and updating Jira issues
- Managing GitHub pull requests
- Running CI/CD workflows
- Notifying teams in Slack
Technical Guidelines:
- Use proper technical terminology
- Include relevant links and references
- Format code snippets properly
- Verify changes before executing
```
### Data Analyst
```
You are a data analysis assistant.
Your capabilities:
- Query databases
- Generate reports
- Create visualizations
- Export data to various formats
Analysis approach:
- Clarify requirements first
- Validate data quality
- Explain your methodology
- Provide actionable insights
```
### Marketing Assistant
```
You are a marketing automation assistant.
You help with:
- Email campaign management
- Social media posting
- Analytics reporting
- Content scheduling
Brand Guidelines:
- Maintain consistent tone
- Follow brand voice guidelines
- Check content before publishing
- Track campaign performance
```
## Advanced Features
### Agent Mentions
Agents can include mentions in their instructions:
**Context Mentions**
```
When responding, always reference @company-policies for guidelines.
```
**Agent Chaining**
```
For complex issues, consult @expert-agent for additional insights.
```
**Thread References**
```
Refer to @project-thread for project context.
```
### Multi-Application Workflows
Create agents that orchestrate multiple services:
```
You are a deployment coordinator.
Deployment workflow:
1. Check CI status in GitHub
2. Create deployment record in Jira
3. Notify team in Slack
4. Monitor logs in Datadog
5. Update status in project board
At each step:
- Verify success before proceeding
- Report status to the user
- Handle errors gracefully
- Provide rollback guidance if needed
```
### Conditional Behavior
Include decision logic in instructions:
```
Issue Triage Agent:
When a new issue is reported:
IF severity is HIGH:
- Create P0 ticket in Jira
- Notify on-call engineer in Slack
- Set status to "Urgent"
IF severity is MEDIUM:
- Create P1 ticket in Jira
- Add to sprint backlog
- Assign to team lead
IF severity is LOW:
- Create P2 ticket in Jira
- Add to general backlog
- No immediate notification
```
## Searching Agents
Use the search bar to quickly find agents:
* Search by agent name
* Filter through descriptions
* Works on both "My Agents" and "Shared Agents"
* Updates results in real-time
## Troubleshooting
### Agent Not Responding as Expected
**Check Instructions**
* Review for clarity and specificity
* Ensure guidelines are unambiguous
* Add examples if behavior is unclear
**Verify Tool Access**
* Confirm necessary applications are selected
* Check application credentials
* Test tools individually
**Review Conversation Context**
* Agent instructions may conflict with user requests
* Check for contradictory mentions
* Verify all prerequisites are met
### Agent Can't Access Tools
**Application Not Selected**
* Edit agent configuration
* Add required applications
* Save changes
**Missing Credentials**
* Check Settings > Applications
* Verify API keys and tokens
* Reconfigure authentication
**Permissions Issue**
* Verify MCP server access
* Check organization permissions
* Confirm application is properly installed
### Shared Agent Not Visible
**Visibility Setting**
* Ensure agent is set to "Public"
* Check with agent creator
* Verify organization membership
## Next Steps
* [Agent Builder](/user-guide/agent-builder) — create agents conversationally
* [Workflows](/user-guide/workflows) — multi-step graphs on an agent (run, simulate, approve)
* [Tasks](/user-guide/tasks) — scheduled and on-demand saved prompts
* [Use agents in Copilot](/user-guide/copilot) for specialized tasks
* [Skills](/user-guide/skills) — org skill library and registry
* [Configure applications](/user-guide/applications) to enable more agent capabilities
* [Add context items](/user-guide/context) for agents to reference
* [MCP Gateway](/user-guide/mcp-gateway/mcp-gateway-overview) — connect agents to external clients
* [View agent usage](/user-guide/insights) in analytics
# Applications
Source: https://docs.apigene.ai/user-guide/applications
Install, configure, and manage API integrations
## Overview
Applications are the foundation of Apigene Copilot. Each application represents an API or service that Copilot can interact with on your behalf. By installing and configuring applications, you enable AI-powered interactions with your tools and services.
![Applications list with search and Install Application]()
Open the list from the **Design** workspace: **Build → Applications**.
## What Are Applications?
Applications are API integrations based on OpenAPI specifications. They provide:
* **API Operations**: Individual endpoints the AI can call
* **MCP Tools**: AI-friendly tools generated from API operations
* **Security Configuration**: Authentication and credential management
* **Metadata**: Context and descriptions for better AI understanding
## Application Lifecycle
### Discovery
Browse available applications or add custom ones
### Installation
Add the application to your workspace
### Configuration
Set up authentication and customize behavior
### Usage
Use the application in Copilot conversations
## Installing Applications
When you click **+ Install Application**, choose:
* **OpenAPI based** — import from URL, file, **Postman collection**, or an **OpenLegacy Hub** project
* **MCP Server** — opens the [official native MCP catalog](/user-guide/mcp-servers#install-from-the-official-catalog) (not an OpenAPI install)
### Method 1: From OpenAPI URL
Install applications directly from a URL:
1. Navigate to **Applications** page
2. Click **+ Install Application** button
3. Choose **OpenAPI based**, then **From URL**
4. Enter the OpenAPI specification URL
```
https://api.example.com/openapi.json
```
5. Click **Install**
**Supported Formats**
* JSON (`.json`)
* YAML (`.yaml`, `.yml`)
* OpenAPI 2.0 (Swagger)
* OpenAPI 3.0
* OpenAPI 3.1
### Method 2: Upload File
Install from a local OpenAPI specification file:
1. Navigate to **Applications** page
2. Click **+ Install Application** button
3. Choose **OpenAPI based**, then **From File**
4. Click to select or drag and drop your file
5. Click **Install**
**File Requirements**
* Valid OpenAPI specification
* Maximum size: 10MB
* Formats: JSON or YAML
### Method 3: From Postman Collection
Install from a Postman collection. Apigene converts the collection to OpenAPI, then runs the normal application install and reindex flow.
1. Navigate to **Applications** → **+ Install Application**
2. Choose **OpenAPI based**
3. Select **From Postman**
4. Upload your Postman collection file (JSON)
5. Wait for conversion and install to finish
6. Configure **Security** before making live calls
Conversion depends on collection structure. Nested folders become tags where possible. Review generated operations after install and reindex if tool metadata looks incomplete. If conversion fails, the error names the problem (invalid JSON, not a Postman collection, unresolved variables, or comments / stray quotes in the export).
### Method 4: From OpenLegacy Hub
Install a Hub project's OpenAPI as an application. Hub must be connected under **Settings → Organization → Open Legacy** (including **Use in Agent Builder**). See [OpenLegacy Hub](/user-guide/openlegacy).
1. Navigate to **Applications** → **+ Install Application**
2. Choose **OpenAPI based**, then **OpenLegacy Hub**
3. Search and select a Hub project (method count, last updated, and an **Installed** badge appear when relevant)
4. Click **Install** (or **Open** if that project is already installed)
The Hub card is shown only when the organization can reach Hub. Installation uses the same index and metadata flow as a file or URL import.
### Method 5: Native MCP Server
To connect a remote MCP server instead of an OpenAPI spec:
1. Choose **MCP Server** on the install screen, **or** open **MCP** in the main nav
2. Follow [Native MCP Servers](/user-guide/mcp-servers) — official catalog, registry, or custom URL
### Installation Process
When you install an OpenAPI-based application, Apigene:
1. **Checks LLM configuration**
* Installing or reindexing an application requires at least one model provider configured for the organization
* If no provider is configured, complete [Settings → AI Models](/user-guide/settings) first, then retry
2. **Validates the specification** (or converts Postman → OpenAPI first)
3. **Creates agentic metadata**
* Generates tool descriptions
* Extracts parameter information
* Creates operation summaries
4. **Initializes configuration**
* Sets up security placeholders
* Creates default settings
* Prepares for first use
The installation typically takes 10-30 seconds depending on the API size.
## Configuring Applications
After installation, configure your application for use:
### General Settings
Access via **Applications** > \[Application Name] > **General** tab
**Basic Information**
* **API Name**: Unique identifier (read-only)
* **API Title**: Display name for the application
* **Description**: What the application does
* **Version**: API version (from specification)
* **Domain URL**: Base URL for API calls
**Visibility**
* **Private**: Only you can use it
* **Organization**: Available to your team
* Toggle visibility as needed
### Security Configuration
Access via **Applications** > \[Application Name] > **Security** tab
This is the most critical configuration step. Without proper security setup, the application cannot make API calls.
#### Authentication Types
**API Key**
```
Security Scheme: API Key
Location: Header / Query Parameter / Cookie
Parameter Name: X-API-Key (example)
Configuration:
- Enter your API key
- Specify where it should be sent
- Save credentials
```
**Bearer Token**
```
Security Scheme: HTTP Bearer
Format: JWT (typical)
Configuration:
- Enter your bearer token
- Token is sent in Authorization header
- Refresh tokens if needed
```
**OAuth 2.0**
```
Security Scheme: OAuth2
Flow: Authorization Code / Client Credentials
Configuration:
- Client ID
- Client Secret
- Authorization URL
- Token URL
- Scopes (permissions needed)
```
**Basic Authentication**
```
Security Scheme: HTTP Basic
Encoding: Base64 (username:password)
Configuration:
- Username
- Password
- Automatically encoded
```
**Custom Authentication**
```
Security Scheme: Custom headers
Configuration:
- Add any custom headers required
- Support for multiple headers
- Dynamic value substitution
```
#### Credential scope (Basic / Bearer / API key)
For static schemes (API key, Bearer, Basic), choose how secrets are stored:
| Scope | Behavior |
| ------------------------ | -------------------------------------------------------------------------- |
| **Org-shared** (default) | One secret for the whole organization — everyone uses the same credentials |
| **Per-user** | Each person connects their own Basic / Bearer / API key |
**When to use per-user**
* Each teammate has their own provider account or personal token
* You do not want a shared org secret
* Chat prompts users to connect before calling the API
**How to enable**
1. Open **Applications** > \[Application Name] > **Security**
2. Select a static scheme (API key, Bearer, or Basic)
3. Set **Credential scope** to **Per-user**
4. Turn off shared security if it is still enabled (shared org secrets conflict with per-user scope)
**How each user connects**
1. On the Security tab, under **User credentials**, click **Connect**
2. Complete the connect-credentials form (or follow the connect link shown in chat when login is required)
3. Use **Clear credentials** to remove your personal secret without changing the org scope
OAuth flows continue to use their normal connect / authorize path; credential scope applies to static Basic / Bearer / API key schemes.
#### Security Setup Steps
1. **Identify Authentication Method**
* Check application documentation
* Look at the Security tab
* Note required credentials
2. **Choose credential scope**
* Org-shared for a single team secret
* Per-user when each member must use their own key
3. **Obtain Credentials**
* Generate API keys from provider
* Complete OAuth flow if needed
* Get service account or personal credentials
4. **Configure in Apigene**
* Org-shared: enter credentials in the Security tab and save
* Per-user: each user clicks **Connect** (or uses the chat connect link)
5. **Verify Setup**
* Use application in Copilot
* Check for authentication errors
* Update or clear credentials when they expire
### API Operations
Access via **Applications** > \[Application Name] > **Operations** tab
View and manage all available API endpoints:
**Operation List**
* Method (GET, POST, PUT, DELETE, etc.)
* Path (e.g., `/api/v1/users`)
* Summary description
* Tags for organization
**Operation Details**
* Full description
* Parameters (path, query, body)
* Request examples
* Response schemas
* Status codes
**Search and Filter**
* Search by operation name or description
* Filter by HTTP method (GET, POST, etc.)
* Filter by **path prefix** (e.g. `/api/v1/users`)
* Filter by one or more **tags**
* Clear filters to reset the list; pagination respects the active filter set
### MCP Tools Configuration
Access via **Applications** > \[Application Name] > **MCP Tools** tab
MCP (Model Context Protocol) tools are AI-optimized versions of your API operations.
**Tool Information**
* Tool name (e.g., `github_create_issue`)
* Description for AI understanding
* Required parameters
* Optional parameters
* Success criteria
**Customization Options**
* Edit tool descriptions
* Modify parameter hints
* Add usage examples
* Set default values
* Adjust inputs, response handling, and UI templates where available
**Tool Generation**
* Automatically created during installation
* One tool per API operation
* Can be regenerated via **reindex** (see below)
* Updates reflect in Copilot after reindex completes
### Agentic metadata list
Access via **Applications** > \[Application Name] > **Metadata** tab
Browse and manage generated agentic metadata for each operation:
**Search and Filter**
* Search by operation ID or description
* Filter by metadata **type**
* Filter by **priority rating** (1 = highest priority, 10 = lowest)
* Results sort by rating so high-value operations surface first
Use these filters on large specs to find operations that need description or rating edits before reindexing.
### Reindex and agentic metadata
Reindex regenerates MCP tool metadata from the current OpenAPI specification. Use it when:
* You updated the OpenAPI spec
* Tool descriptions look stale or incomplete
* Install finished but metadata is still generating
* Postman conversion produced a coarse operation set you refined in the spec
**How to reindex**
1. Open **Applications** → select the application
2. Use the **MCP Tools** / metadata area **Reindex** action
3. Watch status: queued → in progress → success or failure
4. Keep an organization model provider configured — reindex requires LLM access for agentic metadata
While reindex runs, the UI may show progress labels such as “Reindexing queued” or “Reindexing in progress”. Do not delete the application mid-run.
OpenAPI applications are exposed as Apigene MCP tools for agents and the gateway. That is separate from installing a [native MCP server](/user-guide/mcp-servers). Programmatic creation of an MCP server record from an API name is also available via the [MCP Server API](/api-reference/mcp-server/mcp-create-from-api).
### Common Parameters
Access via **Applications** > \[Application Name] > **Common Parameters** tab
Set default values for parameters used across multiple operations:
**Use Cases**
* Organization ID (consistent across all calls)
* API version preference
* Response format preferences
* Default pagination limits
**Configuration**
* Parameter name
* Default value
* Apply to all operations or specific ones
* Override in individual calls if needed
**Benefits**
* Reduce repetitive input
* Ensure consistency
* Simplify Copilot interactions
* Minimize errors
## Managing Applications
### Application List
The Applications page shows all installed applications:
**Information Displayed**
* Application icon (auto-generated from domain)
* Application name and title
* Description
* Security status (configured ✓ / not configured ⚠️)
* Installation date
**Actions**
* Click to view/edit details
* Delete application
* Refresh metadata
* Export configuration
### Searching Applications
Use the search bar to find applications:
* Search by name
* Search by description
* Filter results in real-time
### Updating Applications
When APIs change, update your applications:
1. Go to application details
2. Click **Update Specification**
3. Provide new URL or file
4. Review changes
5. Save updates
**What Gets Updated**
* New operations added
* Removed operations deprecated
* Modified parameters reflected
* Security schemes updated
* MCP tools regenerated
### Deleting Applications
Remove applications you no longer need:
1. Navigate to Applications page
2. Find the application
3. Click the delete icon
4. Confirm deletion
**Impact of Deletion**
* All configuration is removed
* MCP tools become unavailable
* Copilot conversations can no longer use it
* Agents using this application will show errors
* Historical data is retained
## Application Status Indicators
### Security Status
**✓ Configured** (Green)
* Authentication is set up (org-shared secret saved, or per-user credentials connected)
* Application is ready to use
* API calls will succeed
**⚠️ Not Configured** (Red)
* Missing credentials (org secret not saved, or you have not connected yet in per-user mode)
* Application cannot make API calls
* Configuration required
**🔄 Needs Update** (Yellow)
* Credentials may be expired
* Security scheme or credential scope changed
* Reconfiguration recommended
### Connection Status
**Connected** (Green)
* Successfully making API calls
* Credentials are valid
* Service is reachable
**Failed** (Red)
* Authentication errors
* Network issues
* Service unavailable
**Untested** (Gray)
* Not yet used in conversations
* Status unknown
* Test needed
## Best Practices
### Installation
**Choose Quality Specifications**
* Use official OpenAPI specs when available
* Verify specification completeness
* Check for recent updates
**Name Consistently**
* Use clear, recognizable names
* Include version if relevant
* Follow team naming conventions
### Configuration
**Secure Credential Management**
* Use service accounts when possible
* Rotate credentials regularly
* Don't share credentials publicly
* Use environment-specific keys (dev/prod)
**Test After Configuration**
* Make a simple API call in Copilot
* Verify authentication works
* Check returned data format
* Confirm permissions are sufficient
### Maintenance
**Monitor Usage**
* Check Insights for application usage
* Identify unused applications
* Review API call success rates
* Monitor for errors
**Keep Updated**
* Update specifications when APIs change
* Review security configurations quarterly
* Remove deprecated applications
* Document configuration changes
**Optimize Performance**
* Set common parameters to reduce overhead
* Configure only necessary operations
* Use appropriate authentication methods
* Monitor rate limits
## Advanced Features
### Custom Operation Metadata
Enhance AI understanding of operations:
```yaml theme={null}
Operation: createUser
Enhanced Description: |
Creates a new user account in the system.
Requirements:
- Email must be unique
- Password must be at least 8 characters
- Username can only contain alphanumeric characters
Returns the created user object with auto-generated ID.
Example usage:
"Create a new user with email john@example.com"
```
### Parameter Templates
Create reusable parameter sets:
```yaml theme={null}
Template: CreateIssue
Parameters:
project_id: "PROJ"
priority: "medium"
issue_type: "task"
Usage:
"Create an issue in PROJ with these defaults"
```
### Response Transformation
Configure how responses are displayed:
* **Full Response**: Show complete JSON
* **Summary**: Show key fields only
* **Custom Format**: Define what to extract
* **Error Handling**: Custom error messages
### Webhook Integration
For supported applications:
* Configure webhook endpoints
* Receive real-time updates
* Trigger automated workflows
* Enable event-driven actions
## Troubleshooting
### Installation Fails
**Invalid Specification**
* Verify OpenAPI format
* Use validation tools
* Check for syntax errors
* Ensure all required fields present
**Network Errors**
* Check URL accessibility
* Verify no authentication required for spec
* Try downloading and uploading as file
* Check firewall settings
### Authentication Issues
**401 Unauthorized**
* Verify credentials are correct
* Check if tokens have expired
* Confirm account has API access
* Review authentication method
**403 Forbidden**
* Check account permissions
* Verify required scopes granted
* Contact service administrator
* Review API access policies
### API Calls Failing
**Network Errors**
* Check internet connection
* Verify API service is online
* Review firewall rules
* Check for rate limiting
**Invalid Parameters**
* Review required vs optional parameters
* Check parameter data types
* Verify parameter formats
* Review API documentation
**Response Errors**
* Check API status page
* Review error messages
* Verify data format expectations
* Check for breaking changes in API
## Next Steps
* [Use applications in Copilot](/user-guide/copilot) to execute API operations
* [Create agents](/user-guide/agents) with specific application access
* [Monitor usage](/user-guide/insights) in Insights
* [View API call logs](/user-guide/actions) for debugging
# Audit Logs
Source: https://docs.apigene.ai/user-guide/audit
Track system changes and monitor configuration activities
## Overview
Audit Logs provide a comprehensive record of all configuration changes and system-level activities within your Apigene Copilot workspace. They enable you to track who made what changes, when they occurred, and maintain compliance with security and governance requirements.
## What Are Audit Logs?
Audit logs capture system-level events including:
* **Application changes**: Install, update, delete
* **Agent modifications**: Create, update, delete, visibility changes
* **MCP Server changes**: Configuration updates
* **Context changes**: Create, update, delete operations
* **User management**: Role changes, access grants/revokes
* **Security updates**: Credential changes, permission modifications
* **Settings changes**: Organization configuration updates (`org_settings`)
* **API tokens**: Generation of organization or user API access tokens (`api_token`)
## Accessing Audit Logs
In the **Design** workspace, open **Admin → Audit Logs**.
## Audit Log Interface
### Log List View
Each audit log entry displays:
**Timestamp**
* Exact date and time of the event
* Formatted for your timezone
* Sortable for chronological analysis
**User ID**
* Who performed the action
* User email or identifier
* Links to user details
**Action Type**
* **Create**: New resource created
* **Update**: Existing resource modified
* **Delete**: Resource removed
**Resource Type**
* **Application**: API integrations
* **Agent**: AI agents
* **MCP Server**: MCP configurations
* **Context**: Context items
* **User**: User account changes
* **Settings** / **org\_settings**: Organization configuration
* **API token** (`api_token`): Access token generation events
**Resource ID**
* Unique identifier of affected resource
* Quick reference for tracking
* Links to resource (if still exists)
## Search and Filter
### Quick Search
Use the search bar for instant filtering:
* Search by user ID
* Search by resource type
* Search by resource ID
* Search by action type
* Real-time results as you type
### Advanced Filters
Click **Filters** to access detailed filtering options:
**Resource Type Filter**
```
Options:
- All Resource Types
- Application
- Agent
- MCP Server
- Context
- Organization settings (org_settings)
- API token (api_token)
```
**Action Filter**
```
Options:
- All Actions
- Create
- Update
- Delete
```
**Date Range**
* **From Date**: Start of audit period
* **To Date**: End of audit period
* Defaults to last 30 days
**User Filter**
* Filter by specific user ID
* See activities by individual users
* Audit specific user actions
**Resource ID Filter**
* Track changes to specific resource
* View complete history of an item
* Useful for troubleshooting
### Applying and Clearing Filters
**Apply Filters**
1. Configure filter criteria
2. Click **Apply** button
3. Results update immediately
4. Page resets to page 1
**Clear Filters**
1. Click **Clear** button
2. All filters reset to default
3. Shows all audit logs again
4. Preserves date range selection
## Audit Log Details
Click on any log entry to view complete information:
### Event Summary
**Action Information**
* Action type badge (Create/Update/Delete)
* Color-coded for quick identification:
* **Green**: Create
* **Blue**: Update
* **Red**: Delete
**Resource Information**
* Resource type badge
* Resource ID with copy function
* Link to resource (if available)
**User Information**
* User ID who performed action
* User role at time of action
* User email address
**Timing Information**
* Full timestamp with timezone
* ISO format timestamp
* Time since event occurred
### Change Details
For **Update** operations, see:
**Before Values**
* Previous configuration
* Old settings
* Original state
**After Values**
* New configuration
* Updated settings
* Modified state
**Changed Fields**
* List of modified fields only
* Highlights what actually changed
* Easy comparison view
### Metadata
Additional context about the event:
**Request Context**
* Source IP address (if available)
* User agent / client information
* Session ID
* API version used
**System Information**
* System version at time of event
* Processing time
* Related events (if applicable)
**Export Options**
* Copy full log data as JSON
* Download specific log entry
* Share log URL (if permitted)
## Understanding Audit Events
### Application Events
**Application Created**
```json theme={null}
{
"action": "create",
"resource_type": "application",
"resource_id": "github",
"changes": {
"api_name": "github",
"api_title": "GitHub",
"domain_url": "https://api.github.com"
}
}
```
**Application Security Updated**
```json theme={null}
{
"action": "update",
"resource_type": "application",
"resource_id": "github",
"changes": {
"security_info_configured": {
"old": false,
"new": true
}
}
}
```
**Application Deleted**
```json theme={null}
{
"action": "delete",
"resource_type": "application",
"resource_id": "slack",
"metadata": {
"operations_count": 47,
"mcp_tools_removed": 47
}
}
```
### Agent Events
**Agent Created**
```json theme={null}
{
"action": "create",
"resource_type": "agent",
"resource_id": "support-bot-001",
"changes": {
"name": "Customer Support Bot",
"visibility": "private"
}
}
```
**Agent Visibility Changed**
```json theme={null}
{
"action": "update",
"resource_type": "agent",
"resource_id": "support-bot-001",
"changes": {
"visibility": {
"old": "private",
"new": "public"
}
}
}
```
**Agent Instructions Updated**
```json theme={null}
{
"action": "update",
"resource_type": "agent",
"resource_id": "support-bot-001",
"changes": {
"instructions": {
"old": "...",
"new": "..."
}
}
}
```
### Context Events
**Context Created**
```json theme={null}
{
"action": "create",
"resource_type": "context",
"resource_id": "company-info",
"changes": {
"name": "company-info",
"type": "documentation"
}
}
```
**Context Content Updated**
```json theme={null}
{
"action": "update",
"resource_type": "context",
"resource_id": "company-info",
"changes": {
"content": {
"old": "...",
"new": "..."
}
}
}
```
### MCP Server Events
**MCP Server Configured**
```json theme={null}
{
"action": "update",
"resource_type": "mcp_server",
"resource_id": "custom-tools",
"changes": {
"enabled": {
"old": false,
"new": true
}
}
}
```
## Pagination and Navigation
### Viewing Large Result Sets
**Page Controls**
* **Items per page**: Select 10, 20, 50, or 100
* **Previous button**: Go to previous page
* **Next button**: Go to next page
* **Page indicator**: Shows "Page X of Y"
**Navigation Tips**
* Start with more items per page for overview
* Reduce items for detailed review
* Use filters to narrow results first
* Export for offline analysis if needed
### Refresh
Click **Refresh** button to:
* Load latest audit logs
* Update current page
* Check for new activity
* Verify recent changes
## Use Cases
### Security Auditing
**Track Sensitive Changes**
1. Filter by resource type: "Application"
2. Filter by action: "Update"
3. Review security configuration changes
4. Verify authorized changes only
**Access Pattern Analysis**
1. Filter by specific user
2. Review all their activities
3. Identify unusual patterns
4. Ensure proper access usage
**Compliance Reporting**
1. Set date range for audit period
2. Export filtered results
3. Generate compliance reports
4. Document all changes
### Troubleshooting
**When Did This Break?**
1. Identify when issue started
2. Filter audit logs by timeframe
3. Review all changes in that period
4. Correlate changes with issues
**Who Changed This?**
1. Filter by resource ID
2. View all changes to resource
3. Identify who made changes
4. Contact for more information
**What Changed?**
1. View audit log details
2. Compare before/after values
3. Understand exact changes
4. Determine impact
### Change Management
**Track Deployment Changes**
1. Filter by date of deployment
2. Review all changes made
3. Verify deployment checklist
4. Document deployment activities
**Review Team Activities**
1. Filter by team member
2. Monitor configuration changes
3. Ensure best practices followed
4. Provide feedback as needed
**Configuration Drift Detection**
1. Export current configuration
2. Compare with baseline
3. Identify unexpected changes
4. Restore or document as needed
## Best Practices
### Regular Review
**Daily Quick Check**
* Review last 24 hours
* Check for unexpected changes
* Verify critical resources unchanged
* Monitor for security events
**Weekly Deep Dive**
* Review all changes for the week
* Analyze change patterns
* Verify compliance
* Document significant changes
**Monthly Audit**
* Comprehensive review of all logs
* Generate compliance reports
* Identify optimization opportunities
* Update documentation
### Security Monitoring
**Watch For**
* Changes outside business hours
* Bulk delete operations
* Unauthorized access attempts
* Unusual modification patterns
* Security configuration changes
**Alert On**
* Critical application changes
* Agent visibility changes to public
* User permission escalations
* Multiple failed operations
* Rapid configuration changes
### Documentation
**Keep Records Of**
* Intentional configuration changes
* Deployment activities
* Security incidents
* User access changes
* System updates
**Document Why**
* Reason for major changes
* Business justification
* Approval process followed
* Expected impact
* Rollback plan if needed
## Integration with Compliance
### Regulatory Requirements
**GDPR Compliance**
* Track data access changes
* Document user consent management
* Monitor data export activities
* Verify deletion requests processed
**SOC 2 Compliance**
* Access control changes
* Security configuration audit
* Change management documentation
* Incident tracking
**HIPAA Compliance**
* PHI access logging
* Security configuration tracking
* User access management
* Audit trail maintenance
### Audit Trail Export
**For Compliance**
1. Filter relevant time period
2. Apply necessary filters
3. Export audit logs
4. Store securely with compliance data
5. Retain per policy requirements
## Troubleshooting
### No Logs Appearing
**Possible Causes**
* No changes have been made
* Filters too restrictive
* Date range excludes all activity
* Insufficient permissions
**Solutions**
1. Verify changes were made
2. Clear all filters
3. Expand date range
4. Check user permissions
5. Refresh the page
### Can't See Change Details
**Possible Causes**
* Log data pruned
* Insufficient permissions
* Network issue
**Solutions**
1. Check data retention policy
2. Verify user role permissions
3. Refresh connection
4. Contact administrator
### Export Not Working
**Possible Causes**
* Too much data selected
* Export format not supported
* Browser blocking download
* Network timeout
**Solutions**
1. Reduce date range
2. Apply filters first
3. Check browser settings
4. Retry with smaller dataset
5. Contact support if persists
## Privacy and Data Retention
### What's Logged
**Included**
* Configuration changes
* Resource modifications
* User actions
* Timestamps and users
* Change details
**Excluded**
* API call payloads
* Sensitive credentials
* User conversation content
* Personal identifiable information (beyond user ID)
### Retention Period
* Logs retained based on your plan
* Typical retention: 90 days to 1 year
* Export before retention expires
* Automatic cleanup of old logs
* Can request extended retention
### Access Control
* Role-based access to audit logs
* Admin-only access (typically)
* Organization-level visibility
* Secure storage and encryption
* Compliance with data regulations
## Next Steps
* [Monitor actions](/user-guide/actions) for API call details
* [Review settings](/user-guide/settings) for current configurations
* [Check Insights](/user-guide/insights) for usage trends
* [Configure applications](/user-guide/applications) with proper security
# Chat History & Sharing
Source: https://docs.apigene.ai/user-guide/chat-history
Manage your conversations and share insights with your team
## Overview
Chat History allows you to access, manage, and share your Copilot conversations. Every interaction is automatically saved, enabling you to review past conversations, continue where you left off, and share valuable insights with your team.
## Accessing Chat History
### From Sidebar
Your conversations appear in the left sidebar. The list follows the **Live** / **Design** workspace:
* **Live** — everyday chats and task runs
* **Design** — Design Agent sessions (Create / Extend / Mock Mode)
Switch workspace to see the matching history. Use the thread filter (**All**, **Chats**, **Tasks**, **Design**) when you need a narrower view.
* **Recent chats**: Most recent at the top
* **Thread titles**: Auto-generated or custom
* **Timestamps**: Last activity time
* **Quick access**: Click to open any thread
### From Chat Interface
Navigate between threads:
* Thread dropdown in the top bar
* Shows recent conversations
* Quick thread switching
* Search within threads
## Managing Conversations
### Thread Organization
**Automatic Titling**
* AI generates descriptive titles in your [UI language](/user-guide/settings#change-ui-language)
* Based on first message or topic
* Updates as conversation develops
* Edit manually if needed
**Custom Titles**
1. Click on thread title
2. Enter your custom title
3. Press Enter to save
4. Title updates immediately
**Thread List**
* Sorted by last activity
* Most recent at top
* Scroll to see older threads
* Search to find specific conversations
### Thread Actions
**Continue Conversation**
* Click on any thread to reopen
* Previous context is maintained
* Add new messages to continue
* All history is preserved
**Create New Thread**
* Click **New Chat** button
* Starts fresh conversation
* Clean context without history
* Previous threads remain accessible
**Delete Thread**
1. Find thread in sidebar or list
2. Click delete icon
3. Confirm deletion
4. Thread permanently removed
**Important**: Deleted threads cannot be recovered.
### Searching Conversations
**Search Features**
* Search by message content
* Search by thread title
* Search by date range
* Search by mentioned applications
**Search Tips**
* Use specific keywords
* Include application names
* Reference dates for time-based search
* Use quotes for exact phrases
## Chat Sharing
### What is Chat Sharing?
Share your Copilot conversations with others:
* **Public link**: Anyone with the link can view
* **Read-only**: Recipients cannot edit
* **Snapshot**: Captures conversation at sharing moment
* **Secure**: Unique, unguessable URLs
### How to Share a Conversation
**Step 1: Open Thread**
* Navigate to the conversation you want to share
* Ensure it's complete and ready to share
* Review content for sensitive information
**Step 2: Enable Sharing**
1. Click the **Share** button in the thread
2. Sharing is toggled ON
3. Unique share link is generated
4. Link is immediately available
**Step 3: Copy Share Link**
1. Share dialog displays the link
2. Click **Copy Link** button
3. Link is copied to clipboard
4. Share via email, Slack, or other channels
**Step 4: Share with Others**
* Paste link where needed
* Anyone with link can view
* No login required for recipients
* Updates don't affect shared version
### Unsharing a Conversation
**Disable Sharing**
1. Open the shared thread
2. Click **Share** button again
3. Toggle sharing OFF
4. Link becomes invalid immediately
**After Unsharing**
* Previous link stops working
* Recipients get "not found" error
* You can re-share later (new link generated)
* Conversation remains in your history
### What Recipients See
**Shared Thread View**
* Complete conversation history
* All messages and tool invocations
* Request and response data
* Timestamps and flow
**Limitations for Recipients**
* Cannot modify the conversation
* Cannot add new messages
* Cannot see your private information
* Cannot access your other threads
**Branding**
* "Shared by \[Your Name]"
* Powered by Apigene Copilot
* Clean, professional layout
* Mobile-friendly view
## Use Cases
### Team Collaboration
**Share Successful Workflows**
```
Scenario: You figured out a complex integration
Action: Share the conversation thread
Benefit: Team learns from your approach
Result: Faster problem-solving across team
```
**Knowledge Sharing**
```
Scenario: Discovered useful API patterns
Action: Share thread with documentation team
Benefit: Patterns documented for others
Result: Better team documentation
```
**Training and Onboarding**
```
Scenario: New team member joining
Action: Share example conversations
Benefit: Real-world usage examples
Result: Faster onboarding
```
### Documentation
**Create How-To Guides**
1. Execute the workflow in Copilot
2. Document each step naturally
3. Share the thread as tutorial
4. Reference in documentation
**Troubleshooting References**
1. Document the problem-solving process
2. Show how issue was resolved
3. Share for future reference
4. Build knowledge base
**API Examples**
1. Demonstrate API usage
2. Show request/response patterns
3. Share with developers
4. Reference in API documentation
### Support and Debugging
**Share with Support Team**
```
Scenario: Encountering an issue
Action: Share conversation thread
Benefit: Support sees exact context
Result: Faster issue resolution
```
**Report Bugs**
```
Scenario: Found unexpected behavior
Action: Share thread showing bug
Benefit: Clear reproduction steps
Result: Easier bug fixing
```
**Feature Requests**
```
Scenario: Demonstrate needed feature
Action: Share use case conversation
Benefit: Clear feature requirements
Result: Better feature development
```
## Privacy and Security
### What's Shared
**Included in Shared Thread**
* Your messages and AI responses
* Tool invocations and parameters
* API responses and data
* Timestamps and flow
* Application names used
**Not Included**
* Your API credentials
* Your account information
* Your other conversations
* Private organization data
* Billing information
### Security Considerations
**Before Sharing**
* Review for sensitive data
* Check for API keys or tokens
* Verify no private information
* Consider data sensitivity
* Ensure compliance with policies
**Link Security**
* Unique, unguessable URLs
* Cryptographically secure slugs
* Not indexed by search engines
* Can be disabled anytime
**Best Practices**
* Only share when necessary
* Review content before sharing
* Disable sharing when done
* Don't share sensitive conversations
* Use organization sharing policies
### Compliance
**Data Privacy**
* Shared conversations comply with data policies
* Respect user privacy
* Follow organizational guidelines
* Consider regulatory requirements
**Access Control**
* Anyone with link can access
* No authentication required
* Consider using internal channels for sensitive content
* Disable public sharing if too sensitive
## Managing Shared Threads
### Track Shared Conversations
**Identify Shared Threads**
* Shared threads show share icon
* Visual indicator in thread list
* Easy to see what's public
* Quick access to share settings
**Review Shared Content**
1. Navigate to thread
2. Click share button
3. See sharing status
4. Copy link or disable sharing
### Updating Shared Threads
**Important**: Shared threads are snapshots
* Changes don't update the shared version
* Recipients see original version only
* Re-share to update (generates new link)
* Old link remains unchanged
**To Update**
1. Continue the conversation
2. Disable old share
3. Re-enable sharing
4. Share new link
5. Old link no longer works
## Thread Archive
### Archiving Conversations
**What is Archiving?**
* Move old threads out of main list
* Keep them accessible but hidden
* Declutter your workspace
* Preserve conversation history
**How to Archive**
1. Find thread to archive
2. Click archive icon/option
3. Thread moves to archive
4. Main list is cleaned up
**Access Archived Threads**
1. Navigate to Archive section
2. View all archived threads
3. Search archived conversations
4. Restore if needed
### Restoring Archived Threads
**Unarchive**
1. Go to Archive section
2. Find the thread
3. Click restore/unarchive
4. Thread returns to main list
## Best Practices
### Organization
**Naming Conventions**
* Use descriptive thread titles
* Include project or context
* Add dates if relevant
* Be consistent with team
**Regular Cleanup**
* Archive old threads monthly
* Delete unnecessary conversations
* Keep active threads in main list
* Maintain organized workspace
### Sharing Guidelines
**When to Share**
* Successful workflows worth documenting
* Solutions to common problems
* Examples for training
* Bug reports or feature requests
**When Not to Share**
* Conversations with sensitive data
* Threads with API credentials
* Private company information
* Personal or confidential content
**Sharing Process**
1. Review conversation thoroughly
2. Check for sensitive content
3. Add context if needed
4. Share with appropriate audience
5. Disable when no longer needed
### Collaboration
**Team Sharing**
* Create shared thread library
* Document best practices
* Build knowledge repository
* Facilitate learning
**Communication**
* Explain what recipients will see
* Provide context for shared thread
* Note any important details
* Set expectations for usage
## Keyboard Shortcuts
* `Cmd/Ctrl + K`: Open thread switcher
* `Cmd/Ctrl + N`: New thread
* `Cmd/Ctrl + Shift + S`: Share current thread
* `Escape`: Close dialogs
## Troubleshooting
### Can't Find Conversation
**Solutions**
1. Use search function
2. Check archived threads
3. Verify not deleted
4. Adjust date range
5. Check spelling in search
### Share Link Not Working
**Common Issues**
* Thread was unshared
* Link was disabled
* Thread was deleted
* Network connectivity issue
**Solutions**
1. Verify thread still shared
2. Generate new share link
3. Test link in incognito mode
4. Check if thread exists
5. Re-enable sharing
### Shared Thread Shows Error
**For Recipients**
* Link may be invalid
* Thread was unshared
* Temporary network issue
* Contact person who shared
**For Sharers**
1. Check if sharing still enabled
2. Verify thread exists
3. Try disabling and re-enabling
4. Generate fresh link
5. Contact support if persists
## Data Retention
### Conversation Storage
**Retention Period**
* Conversations stored per plan
* Typical retention: 90 days to unlimited
* Export before retention expires
* Archived threads count toward retention
**Export Options**
* Export individual threads
* Export as JSON or text
* Include metadata
* Download locally for backup
### Deletion
**Manual Deletion**
* Delete individual threads
* Permanent removal
* No recovery possible
* Export first if needed
**Automatic Cleanup**
* Old threads may be auto-archived
* Based on retention policy
* Notification before deletion
* Option to preserve important threads
## Next Steps
* [Use Copilot](/user-guide/copilot) to create valuable conversations
* [Create agents](/user-guide/agents) for consistent workflows
* [Add context](/user-guide/context) for better conversations
* [Review Insights](/user-guide/insights) for usage insights
# Context
Source: https://docs.apigene.ai/user-guide/context
Manage reusable context items for consistent AI interactions
## Overview
Context items are reusable pieces of information that you can reference in your Copilot conversations. They provide consistent data, instructions, or knowledge that the AI can use across multiple interactions, reducing repetition and ensuring accuracy.
## What Is Context?
Context items are stored pieces of information that can include:
* **Reference data**: Company information, product details, guidelines
* **Code snippets**: Reusable code templates or examples
* **Documentation**: Technical specs, API documentation, procedures
* **Instructions**: Standard operating procedures, policies
* **Templates**: Message templates, response formats
* **Knowledge**: Domain expertise, best practices, FAQs
## Why Use Context?
### Consistency
* Same information used across all conversations
* No need to repeat common details
* Reduced errors from manual entry
### Efficiency
* Reference complex information with simple mentions
* Avoid copying and pasting repeatedly
* Faster conversation setup
### Knowledge Sharing
* Share context across your organization
* Onboard new team members faster
* Centralize important information
### AI Enhancement
* Provide domain-specific knowledge
* Improve AI response accuracy
* Guide AI behavior consistently
## Creating Context Items
### Step 1: Navigate to Context
1. In the **Design** workspace, open **Build → Context**
2. Click **+ New Context** button
3. The context creation form appears
## Context Types
**Context Types** define reusable schemas/templates for how context items are structured (for example Knowledge, Tool, or custom types).
1. From the Context list, open **Context Types** (or go to `/context-type`)
2. Browse existing types, **import defaults**, or create a **New Type**
3. Edit a type’s name, summary, and structure
4. When creating a context item, select the appropriate type
Use types to keep org knowledge consistent and to help agents/MCP tools discover the right kind of context.
### Step 2: Configure Basic Information
**Context Name**
* Choose a descriptive, memorable name
* Use clear naming conventions
* Examples: "company-info", "api-guidelines", "brand-voice"
**Context Description** (Optional)
* Explain what the context contains
* Note when to use it
* Helpful for team members
### Step 3: Add Content
**Content Field**
* Enter your context information
* Can include:
* Plain text
* Markdown formatting
* Code snippets
* JSON data
* XML/YAML
* Documentation excerpts
**Content Examples**
**Company Information**
```markdown theme={null}
# Company Information
Company Name: Acme Corporation
Founded: 2020
Industry: Software Development
Main Product: AI-powered automation tools
Contact Information:
- Support Email: support@acme.com
- Sales Email: sales@acme.com
- Phone: +1-555-0123
Office Locations:
- HQ: San Francisco, CA
- Europe: London, UK
- Asia: Singapore
```
**API Guidelines**
```markdown theme={null}
# API Integration Guidelines
Authentication:
- Always use OAuth 2.0
- Refresh tokens before expiry
- Store tokens securely
Error Handling:
- Retry on 5xx errors with exponential backoff
- Log all 4xx errors for analysis
- Show user-friendly error messages
Rate Limiting:
- Maximum 100 requests per minute
- Implement request queuing
- Monitor usage via Insights
```
**Code Template**
```python theme={null}
# Standard API Request Template
import requests
from typing import Dict, Any
def make_api_request(
endpoint: str,
method: str = "GET",
headers: Dict[str, str] = None,
data: Dict[str, Any] = None
) -> Dict[str, Any]:
"""
Standard API request handler with error handling.
"""
try:
response = requests.request(
method=method,
url=f"{BASE_URL}/{endpoint}",
headers=headers,
json=data,
timeout=30
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
logger.error(f"API request failed: {e}")
raise
```
### Step 4: Set Metadata
**Context Type**
* Select the appropriate type
* Helps with organization and filtering
* Examples: documentation, code, template, policy
**Tags** (Optional)
* Add searchable tags
* Group related contexts
* Examples: "api", "customer-support", "development"
### Step 5: Set Visibility
**Private Context**
* Only you can see and use it
* Perfect for personal references
* Test before sharing
**Public Context**
* Available to your entire organization
* Appears in everyone's context list
* Great for team standards
### Step 6: Save
1. Click **Save** to create the context item
2. It's immediately available for use
3. Reference it with `@context-name` in Copilot
## Using Context Items
### In Copilot Conversations
Reference context items using mentions:
**Simple Reference**
```
@company-info please draft an email to a new client
```
**Multiple Context Items**
```
Using @api-guidelines and @code-template, create a new
API integration
```
**Implicit Usage**
```
Following our standard practices, create a support ticket
(if agent has context item in instructions)
```
### How Context Is Applied
When you mention a context item:
1. The AI receives the full context content
2. It uses this information to inform responses
3. It maintains consistency with the guidelines
4. It references specific details as needed
### Context in Agents
Agents can include context mentions in their instructions:
```
You are a customer support agent.
Always reference @company-policies and @support-templates
when responding to customers.
Use @faq-database to answer common questions before
escalating.
```
This ensures the agent always has access to this information.
## Managing Context Items
### Viewing Context
The Context page shows:
**My Contexts**
* Context items you created
* Private items
* Full edit/delete access
**Shared Contexts**
* Public items from your organization
* Created by team members
* View-only access
### Searching Context
Use the search bar to find context items:
* Search by name
* Search by description
* Search by tags
* Filter in real-time
### Editing Context
1. Find your context in "My Contexts"
2. Click the **Edit** button
3. Modify name, content, or settings
4. Click **Save Changes**
**Changes Apply**
* Immediately to new conversations
* Existing conversations may have old version
* Update agents that reference this context
### Deleting Context
1. Find your context in "My Contexts"
2. Click the **Delete** button
3. Confirm deletion
4. Context is permanently removed
**Impact**
* No longer available for new mentions
* Agents referencing it may show warnings
* Existing conversations with it continue to work
### Changing Visibility
Toggle between private and public:
1. Click the visibility toggle
2. Confirm the change
3. Context moves to appropriate section
4. Available to others immediately
## Context Best Practices
### Naming Conventions
**Use Clear Names**
* ✅ "customer-support-guidelines"
* ✅ "api-authentication-process"
* ✅ "brand-voice-standards"
* ❌ "context1"
* ❌ "my-stuff"
* ❌ "temp"
**Follow Patterns**
* Use lowercase with hyphens
* Include domain or purpose
* Keep names concise but descriptive
* Consistent with team conventions
### Content Organization
**Keep It Focused**
* One purpose per context item
* Break large contexts into smaller ones
* Example: Instead of "all-company-info", create:
* "company-details"
* "contact-information"
* "office-locations"
**Structure for Clarity**
```markdown theme={null}
# Title
## Overview
Brief description of the content
## Key Information
- Point 1
- Point 2
- Point 3
## Examples
Concrete examples when applicable
## Related Resources
Links to related contexts or documentation
```
**Use Formatting**
* Markdown for readability
* Code blocks for snippets
* Lists for easier scanning
* Headers for organization
### Maintenance
**Regular Review**
* Monthly review of all contexts
* Update outdated information
* Remove unused contexts
* Consolidate duplicates
**Version Control**
* Note major changes in descriptions
* Keep change log if critical
* Communicate updates to team
* Test changes before saving
**Quality Assurance**
* Verify information accuracy
* Check links and references
* Test context in conversations
* Get feedback from users
## Common Context Types
### Company Information
```markdown theme={null}
# Company Profile
Name: Acme Corp
Mission: Empowering businesses through AI
Values: Innovation, Integrity, Impact
Products:
1. Copilot Platform
2. Automation Suite
3. Analytics in Insights
```
### API Documentation
```markdown theme={null}
# Authentication API
Endpoint: POST /api/v1/auth/login
Request Body:
{
"email": "user@example.com",
"password": "securepass"
}
Response:
{
"token": "jwt_token_here",
"expires_in": 3600
}
Rate Limit: 5 requests per minute per IP
```
### Process Guidelines
```markdown theme={null}
# Bug Report Process
1. User reports bug
2. Create Jira ticket with:
- Title: Clear description
- Priority: Based on severity
- Components: Affected areas
- Labels: bug, needs-triage
3. Notify team in #bugs Slack channel
4. Assign to appropriate team member
5. Update ticket status as work progresses
```
### Brand Voice
```markdown theme={null}
# Brand Communication Guidelines
Tone: Friendly, professional, helpful
Do:
- Use clear, simple language
- Be empathetic and understanding
- Provide actionable guidance
- Include concrete examples
Don't:
- Use jargon unnecessarily
- Be overly formal or casual
- Make promises we can't keep
- Ignore customer concerns
```
### Code Standards
```javascript theme={null}
// Standard Function Documentation
/**
* Brief description of function purpose
*
* @param {Type} paramName - Parameter description
* @returns {Type} Return value description
* @throws {ErrorType} When error occurs
*
* @example
* const result = functionName(param);
*/
function functionName(paramName) {
// Implementation
return result;
}
```
## Advanced Features
### Dynamic Content
Include placeholders that get filled in:
```markdown theme={null}
# Email Template
Subject: Welcome to {COMPANY_NAME}
Dear {USER_NAME},
Thank you for joining {PRODUCT_NAME}!
Your account has been created with email: {USER_EMAIL}
Next steps:
1. Complete your profile
2. Explore our features
3. Join our community
Best regards,
{SUPPORT_TEAM}
```
### Nested References
Context items can reference other contexts:
```markdown theme={null}
# Complete Onboarding Process
## Step 1: Account Setup
See @account-creation-guide
## Step 2: Initial Configuration
Follow @configuration-checklist
## Step 3: First Project
Use @project-template
```
### Conditional Guidelines
Include decision trees or conditional logic:
```markdown theme={null}
# Support Escalation Rules
IF issue_priority == HIGH AND no_solution_found:
- Escalate to senior support
- Notify team lead
- Update customer within 1 hour
ELSE IF issue_priority == MEDIUM:
- Attempt standard troubleshooting
- Consult knowledge base
- Escalate if unresolved in 24 hours
ELSE:
- Handle using standard procedures
- Document solution
- Update knowledge base if new
```
## Troubleshooting
### Context Not Working
**Context Not Applied**
* Verify mention syntax: `@context-name`
* Check context name spelling
* Ensure context exists and is accessible
* Try refreshing the context list
**Partial Content**
* Context might be too large
* Consider splitting into smaller contexts
* Verify full content was saved
* Check for formatting issues
### Can't Find Context
**Missing from List**
* Check visibility settings
* Verify you have access
* Use search function
* Check spelling variations
**Search Not Working**
* Clear search and try again
* Use partial name matching
* Check filters
* Refresh the page
### Context Conflicts
**Multiple Contexts with Similar Info**
* Consolidate duplicate contexts
* Use clear differentiation in names
* Add descriptive tags
* Document which to use when
## Integration with Other Features
### Context + Agents
* Agents reference contexts in instructions
* Ensures consistent agent behavior
* Provides domain knowledge
* Reduces agent instruction length
### Context + Copilot
* Direct mentions in conversations
* Quick access to complex information
* Consistent responses across chats
* Reduced input required from users
### Context + Applications
* Application-specific guidelines
* API usage templates
* Authentication instructions
* Error handling procedures
## Next Steps
* [Use context in Copilot](/user-guide/copilot) conversations
* [Reference context in agents](/user-guide/agents) for specialized behavior
* [Monitor usage](/user-guide/insights) of your applications
* [Configure settings](/user-guide/settings) for your workspace
# Copilot
Source: https://docs.apigene.ai/user-guide/copilot
Interact with your applications using AI-powered conversations
## Overview
Apigene Copilot is an AI-powered conversational interface that enables you to interact with multiple applications, APIs, and services using natural language. Instead of writing code or making manual API calls, simply describe what you want to accomplish, and Copilot will execute the necessary actions.
![Copilot home screen with Chat and Agent Builder toggle]()
Copilot can run tools live and render structured results (for example, a searchable table of GitHub commits):
![Copilot chat showing generative UI table of GitHub commits]()
## Key Features
### Multi-Application Support
* Connect and interact with multiple applications simultaneously
* Execute complex workflows across different services
* Seamlessly switch between applications in a single conversation
### Intelligent Tool Selection
* Automatic selection of the right tools and APIs based on your request
* Context-aware recommendations for API operations
* Smart parameter detection and validation
### Real-Time Execution
* Live execution of API calls with streaming responses
* View request and response data in real-time
* Monitor tool invocations as they happen
### Design Agent (Agent Builder)
A dedicated mode for **creating and configuring agents** — not for everyday chat. In the UI it is labeled **Design Agent**. Use **Create** for a new agent, **Extend** to add a skill, workflow, or UI to an existing draft (publish stays explicit), or **Mock Mode** to provision a mock application when the real API is not ready yet.
Use **Live** (Chat) to talk to your apps and agents. Switch to **Design** and open **Design Agent** to define agents as resources.
See the full [Agent Builder](/user-guide/agent-builder) guide for workflows, examples, and when to use each mode.
### Model Selection
Choose from multiple AI model providers configured in [Settings](/user-guide/settings):
* **OpenAI** — GPT-6 (Astra, Sol, Luna), GPT-5.5, GPT-5.4 (including mini and nano)
* **Anthropic** — Claude Opus 5.5, Fable 5.1, Sonnet 5, and earlier Claude 4.x models
* **Google** — Gemini 3.8 Flash and other Gemini 3.x models
* **xAI** — Grok 4.7, Grok 4, Grok 3
* **Amazon Bedrock** — AWS-hosted models (IAM credentials)
* **Microsoft Foundry** — Azure OpenAI deployments
The model selector supports search and collapsible provider groups when you have many models configured.
When an admin enables **Model comparison**, the composer shows **Compare**. Pick a second model and send the same prompt to both. Each comparison doubles token spend and may execute tools twice. See [Settings](/user-guide/settings#model-comparison).
### Reasoning Models
For models that support extended thinking, Copilot can show a **reasoning** panel alongside the response. Organization admins set **Reasoning Effort** (None, Low, Medium, High) under Settings → Organization → Model Settings.
## Getting Started
### Starting a New Chat
1. Stay in the **Live** workspace (sidebar toggle) and click **New Chat**
2. To design an agent instead, switch to **Design** and open **Design Agent**, or use the mode toggle on the home screen
3. Type your request in the message input at the bottom
4. Press Enter or click Send to start the conversation
### Onboarding Checklist (Trial Users)
New trial users see a **getting started checklist** on the home screen. It tracks progress toward:
1. Configuring a model provider (API key)
2. Installing and configuring an application
3. Creating your first agent
Dismiss the checklist when you no longer need it, or follow the links to complete each step. Agent Builder is the fastest path to step 3 — see [Agent Builder](/user-guide/agent-builder).
### Your First Query
Try these example queries to get started:
* "List all my GitHub repositories"
* "Create a new Jira issue for the bug I found"
* "Send a message in Slack to the #engineering channel"
* "Get my last 10 emails from Gmail"
### Selecting AI Model
1. Click the model selector in the top bar
2. Choose from available models based on your needs:
* **Fast models**: Quick responses for simple tasks
* **Powerful models**: Complex reasoning and multi-step workflows
* **Balanced models**: Good balance of speed and capability
## Chat Features
### Tool Invocations
When Copilot executes actions, you'll see:
* **Tool name and description**: What action is being performed
* **Parameters**: The data being sent to the API
* **Status indicators**: Success, loading, or error states
* **Response data**: Full results from the API call
* **Generative UI**: Interactive widgets (tables, charts, and similar) stay expanded in the tool group instead of collapsing with other calls. Workflow runs that render UI are listed separately from the collapsed group.
### Message Actions
Each message supports:
* **Copy**: Copy message content to clipboard
* **Regenerate**: Re-run the AI response with same context
* **Edit**: Modify your previous message
* **Branch**: Create a new conversation from this point
### File Attachments
Upload files to enhance your conversations:
1. Click the **+** button in the message input and select files
2. Drag and drop files onto the chat
3. Paste a screenshot (`⌘V` / `Ctrl+V`) while the chat input is focused — useful after a screen capture to the clipboard
Copilot analyzes and uses the file content in responses.
**Supported formats:** images (`image/*`), PDF (`.pdf`), plain text and code files (`text/*`), and other readable text-based files. Binary files that cannot be read as text prompt you to describe what you need instead.
File attachments are available in **Chat** mode. Agent Builder focuses on agent configuration rather than file analysis.
### Mentions
Type `@` in the chat input to pick a resource. The picker is split into columns:
* **Agents** — invoke a specific agent (and its workflows)
* **MCP** — attach an application or native MCP server; the picker shows connection status (connected, idle, or disconnected). Use **Login** / **Logout** on a native OAuth server to connect or switch your account
* **Tools** — built-in tools available in chat
You can also mention **@context** items and previous **@threads**. On a phone, the mention and model pickers open as sheets so they stay usable above the keyboard.
### Diagrams
When the assistant replies with a Mermaid chart (flowchart, sequence, and similar), the diagram auto-fits in the message so large charts stay readable without horizontal scrolling.
### Commands (Saved Prompts)
Reuse frequent prompts without retyping them. Commands are personal saved prompts you can insert into chat.
**Create a command**
1. Type a prompt in the chat input
2. Click the **bookmark** button to open **Save command**
3. Give it a name, optionally bind an agent, and save
You can also manage commands under **Settings → Personal → Commands** (add, edit, or delete).
**Use a command**
1. Type `/` in the chat input
2. Search or select a saved command
3. The prompt is inserted (and the bound agent is mentioned when one is attached)
Commands are stored in your personal settings and follow you across chats.
### Follow-up Suggestions
When enabled, Copilot shows short **Continue with** chips under the latest assistant reply. Click a chip to send that follow-up as your next message.
Enable or disable under **Settings → Personal → Chat → Follow-up suggestions**. Off by default.
### Message Queue
While Copilot is still streaming a reply, you can keep typing and send the next message. Queued messages appear above the input (up to **5** per thread). You can:
* **Remove** a queued message before it sends
* **Send now** to interrupt the current run and flush that message when ready
If the queue is full, wait for a slot or remove an item before adding another.
### Use Case Proposals
In Chat and Agent Builder, ask Copilot to suggest concrete use cases for your apps (for example, “Suggest use cases for Jira and Slack”). Copilot can show a **use case proposals** card you can review and act on, similar to skill proposal cards in Agent Builder.
If [OpenLegacy Hub](/user-guide/openlegacy) is connected for Agent Builder, Hub projects can appear on those proposals. Building a Hub use case provisions a scoped Hub skill and attaches the **ol-hub** app. Proposal cards show app icons on chips so a full idea can stay on screen.
### Chat Preferences
Open **Chat Preferences** (shortcut **⇧⌘L** / **Shift+Ctrl+L**) to personalize how Copilot behaves in chat:
* **User instructions / personalization** — how you want to be addressed, role, traits, and related fields
* **MCP instructions** — optional per-MCP-server customization for tool behavior
* **Base system prompt** — personal base prompt applied across chats
These preferences are personal. Organization model keys and policies still come from [Settings](/user-guide/settings).
### Languages and layout
Set the Copilot UI language under **Settings → Personal → Language** (English, Español, Deutsch, Français, Português (Brasil), 日本語, עברית). The choice is stored on your user. Auto-generated thread titles use that language.
Hebrew uses a full right-to-left layout. Copilot also detects Hebrew and Arabic in messages, suggestions, and the composer and applies RTL alignment. Code blocks and byte sizes stay LTR for readability.
## Tool Control
### Tool Choice Modes
Control how Copilot uses tools:
**Auto** (Default)
* AI automatically decides when to use tools
* Best for most use cases
* Balances efficiency and accuracy
**Required**
* Forces the AI to use at least one tool
* Ensures API interactions happen
* Good for action-focused tasks
**None**
* Disables all tool usage
* Pure conversational mode
* Use for questions and planning
### Selecting Applications
Choose which applications Copilot can access:
1. Click the applications dropdown in the top bar
2. Select or deselect applications
3. Only selected applications will be available for the conversation
4. Leave empty to allow access to all configured applications
## Advanced Features
### Multi-Step Workflows
Copilot can execute complex multi-step operations:
```
Create a GitHub issue, then post a message in Slack with the issue link
```
The AI will:
1. Create the GitHub issue
2. Extract the issue URL from the response
3. Post to Slack with the URL included
### Context Awareness
Copilot maintains context throughout the conversation:
* References to previous messages
* Remembers data from earlier tool invocations
* Builds on previous results
### Error Handling
When errors occur:
* Clear error messages explain what went wrong
* Suggestions for how to fix the issue
* Option to retry with corrected parameters
## Best Practices
### Writing Effective Prompts
**Be Specific**
* ❌ "Get my data"
* ✅ "Get all issues created in the last week from Jira"
**Include Context**
* ❌ "Update the issue"
* ✅ "Update issue PROJ-123 to set status to 'In Progress'"
**Break Down Complex Tasks**
* Instead of one complex request, use multiple specific requests
* Let Copilot handle each step and verify results
### Managing Conversations
**Create New Threads**
* Start new conversations for unrelated topics
* Keep conversations focused on a single workflow
* Use descriptive titles for easy reference
**Use Mentions**
* Type `@` to browse **Agents**, **MCP**, and **Tools** in separate columns
* The MCP column shows connection status (connected, idle, or disconnected)
* Mention a specific agent for specialized tasks
* Reference context items for consistent data
### Performance Tips
**Choose the Right Model**
* Use faster models for simple queries
* Reserve powerful models for complex reasoning
* Consider cost and response time tradeoffs
**Limit Application Scope**
* Select only relevant applications
* Reduces tool selection overhead
* Improves response accuracy
## Keyboard Shortcuts
Labels use **⌘** on macOS and **Ctrl** on Windows.
* `⌘/Ctrl + Enter`: Send message
* `⌘/Ctrl + K`: Open command palette
* `/`: Open [Tasks](/user-guide/tasks) picker (saved prompts)
* `Shift + ⌘/Ctrl + L`: Open Chat Preferences (when available)
* `⌘/Ctrl + V`: Paste a screenshot or file into chat when the input is focused
* `Escape`: Cancel current operation
* `↑`: Edit previous message
## Troubleshooting
### Copilot Not Responding
* Check your internet connection
* Verify API keys are configured
* Try refreshing the page
### Wrong Tool Selected
* Be more specific in your request
* Mention the application name explicitly
* Check that the right applications are enabled
### Authentication Errors
* Verify application credentials in Settings
* Check if tokens have expired
* Reconfigure the application security settings
## Next Steps
* [Agent Builder](/user-guide/agent-builder) — create and configure agents conversationally
* [Tasks](/user-guide/tasks) — schedule and reuse prompts
* [Workflows](/user-guide/workflows) — multi-step agent graphs
* [Configure your applications](/user-guide/applications) to enable more capabilities
* [Native MCP Servers](/user-guide/mcp-servers) for remote MCP integrations
* [Create and edit agents](/user-guide/agents) in the full editor
* [Skills](/user-guide/skills) — reusable instruction libraries
* [Add context items](/user-guide/context) for consistent data access
* [View analytics](/user-guide/insights)
# Insights
Source: https://docs.apigene.ai/user-guide/insights
Organization analytics for conversations, agents, workflows, and actions
## Overview
**Insights** is the analytics home for your organization. Use it to monitor Copilot adoption and LLM spend, agent performance, workflow reliability, and API action volume.
In Apigene 5.16, Insights replaces the separate **Dashboard** page. Bookmarks to Dashboard open the same analytics under Insights.
## Accessing Insights
In the **Design** workspace, open **Monitor → Insights** (admin). Pick a tab and date range to load charts and tables.
## Tabs
| Tab | Focus |
| ----------------- | -------------------------------------------------------------- |
| **Conversations** | Chat volume, tokens, and estimated LLM cost |
| **Agents** | Agent performance rollup and per-agent drill-down |
| **Workflows** | Workflow run volume, success rate, duration, and failures |
| **Actions** | API / application call volume, status codes, and usage by user |
### Date range
* Quick presets (for example 7 / 30 / 90 days) plus custom start and end dates
* **Default**: Last 30 days
* Changing the range updates charts on the active tab (except where Agents uses its own agent-scoped controls)
## Conversations
### Activity
* Threads over time
* Threads by user (accounts that share the same email are counted as one user)
* Average tokens per conversation
Use this to track Copilot adoption and spot power users or quiet periods.
### LLM usage and cost
* Daily LLM usage with a **cost / tokens** toggle (input vs output)
* Estimated spend by model and by provider
* LLM usage by user
Costs are **list-price estimates** from known model pricing — useful for trends and chargeback, not an invoice. Pair with [Settings](/user-guide/settings) to hide expensive models or add custom model IDs.
## Agents
### Org rollup
The **Agents** tab opens with a lightweight org summary:
* Total interactions
* Average duration
* Success rate and error rate
* Volume across agents
### Per-agent detail
Select an agent to load deeper charts and tables:
* Totals and success rate
* Response-time trends
* Usage over time, peak days and hours
* Application mix
* Top and slowest actions
* Cache performance (when caching is enabled)
* User engagement
Empty or sparse charts usually mean little traffic in the selected range — widen the dates or confirm the agent is used in Copilot or via MCP.
## Workflows
* Total runs, success rate, average duration, and runs waiting on approval
* Runs over time and by status
* Success rate and average duration over time
* Breakdowns by workflow, agent, and user
* Failures by step (where runs fail most often)
Pair with [Workflow History](/user-guide/workflow-history) to open a specific run and simulate it on the graph.
## Actions
* Daily action volume and trends
* Status-code mix (success vs client/server errors)
* Usage by user and by application
Drill into [Actions](/user-guide/actions) for request/response detail when investigating spikes or failures.
## Tips
* Use shorter ranges for incident analysis; longer ranges for trends
* Investigate slowest agent actions together with Actions history
* If payloads look incomplete, check [Interaction Recording](/user-guide/settings#interaction-recording-organization)
* After fixing credentials or parameters, re-check Insights to confirm error rates drop
## Related
* [Actions](/user-guide/actions)
* [Workflow History](/user-guide/workflow-history)
* [Agents](/user-guide/agents)
* [Applications](/user-guide/applications)
* [Settings](/user-guide/settings)
# User Guide
Source: https://docs.apigene.ai/user-guide/introduction
Learn how to use Apigene Copilot effectively
## Welcome to Apigene Copilot
Apigene Copilot is an AI-powered platform that enables you to interact with APIs and services using natural language. This guide will help you get started and make the most of all features.
![Apigene application menu with navigation to product areas]()
The left sidebar has two workspaces (toggle **Live** / **Design**):
* **Live** — **New Chat**, chat history, and **Tasks**. Use this to talk to apps and agents.
* **Design** — **Design Agent** (**Create**, **Extend**, or **Mock Mode**), then **Build** (Agents, Applications, Skills, Context), **Monitor** (Actions, Workflows, Insights), and **Admin**. Use this to create and configure agents.
Organization members and phones stay in **Live**.
## What You'll Learn
This user guide covers everything you need to know to effectively use Apigene Copilot:
### Getting Started
Learn the fundamentals to start using Apigene:
Start having AI-powered conversations with your applications
Create and configure agents through a guided conversational workflow
Install and configure your first API integration
### Core Features
Master the key features that make Apigene powerful:
Create specialized AI assistants for your workflows
Reusable instruction libraries for consistent agent behavior
Manage reusable information for consistent results
Organize and share your conversations
### Integrations
Connect external tools and AI assistants:
Install official, registry, or custom MCP servers and attach them to agents
Connect Hub, install project OpenAPI as applications, and build Hub-ready agents
Connect AI assistants like Claude Desktop and Cline to Apigene using the Model Context Protocol
Build UI templates for rich MCP App and generative results
### Monitoring & Management
Track usage and manage your workspace:
Monitor all API calls and troubleshoot issues
Inspect and replay past agent workflow runs
Conversations, agents, workflows, and action analytics
Track system changes and security events
Configure your workspace preferences
## Quick Navigation
### New to Apigene?
If you're just getting started:
1. **[Install Applications](/user-guide/applications)** - Add your first API integration
2. **[Configure Security](/user-guide/applications#security-configuration)** - Set up authentication
3. **[Try Copilot](/user-guide/copilot)** - Start your first conversation
4. **[Create an Agent](/user-guide/agents)** - Build your first specialized assistant
### Common Tasks
Jump to frequently accessed guides:
* **[How to use Copilot](/user-guide/copilot)** - AI conversations with applications
* **[Installing new applications](/user-guide/applications#installing-applications)** - Add integrations
* **[Creating agents](/user-guide/agents#creating-an-agent)** - Build custom assistants
* **[Adding context](/user-guide/context#creating-context-items)** - Manage reusable data
* **[Sharing conversations](/user-guide/chat-history#chat-sharing)** - Collaborate with team
* **[Debugging actions](/user-guide/actions#troubleshooting)** - Fix API call issues
* **[Viewing analytics](/user-guide/insights)** - Monitor usage patterns
* **[Connecting MCP clients](/user-guide/mcp-gateway/mcp-gateway-overview)** - Integrate AI assistants
## How to Use This Guide
Each section of this guide is designed to be:
**Comprehensive**
* Complete coverage of each feature
* Step-by-step instructions
* Real-world examples
**Practical**
* Use cases and scenarios
* Best practices
* Troubleshooting tips
**Easy to Navigate**
* Searchable content
* Cross-referenced topics
* Clear section headings
## Getting Help
### Search the Docs
Use the search bar (⌘K) to quickly find what you need.
### In-Product Help
Look for help icons and tooltips throughout the Apigene interface.
### Contact Support
Reach out to our team at [support@apigene.ai](mailto:support@apigene.ai) for assistance.
### API Documentation
For programmatic integration, see our [API Reference](/api-reference).
## What's Next?
Learn how to interact with applications using AI
Add your first API integration
See example queries and use cases
Learn tips for effective usage
Connect external AI assistants to Apigene
# MCP Apps
Source: https://docs.apigene.ai/user-guide/mcp-apps
Create and manage MCP App UI templates and generative layouts for agents
## Overview
**MCP Apps** are visual templates that render API or tool results as interactive widgets in MCP-compatible hosts (for example charts, tables, and custom layouts). You manage organization templates under **MCP Apps**, and per-agent generative UI templates on the agent **Generative UI** tab.
MCP Apps complement [native MCP servers](/user-guide/mcp-servers) and [OpenAPI applications](/user-guide/applications): they control **how results look**, not which backend you connect.
## Accessing MCP Apps
Navigate to **MCP Apps** from the application menu (admin). The list shows templates grouped by application, with search and actions to create, clone, edit, or delete.
## Create a template
1. Open **MCP Apps**
2. Click **Create Template**
3. Choose the target application (API / MCP app name)
4. Define the template id and layout (starter layouts or JSON / json-render style specs, depending on editor)
5. Preview with sample state when available
6. Save
Templates can be used by MCP tools such as `run_action_ui`, `run_multi_actions_ui`, and generative UI tools when MCP App UI is enabled on your deployment. See [MCP Gateway Tools](/user-guide/mcp-gateway/mcp-gateway-tools).
## Edit, clone, and delete
* **Edit** — open the template editor for an existing template
* **Clone** — duplicate a template to another id or app context
* **Delete** — remove a template from the organization library
Cloning is useful when you want a variant layout without rewriting the base template.
## GitHub Sync
MCP Apps supports optional **GitHub Sync** for template source control:
1. **Connect** a GitHub repository
2. **Push** local templates to the repo
3. **Pull** remote changes into Apigene
4. Review **Sync History**
5. **Disconnect** when you no longer need sync
Use sync when multiple builders maintain templates outside the UI or you need review workflows in Git.
## Generative UI on agents
Each agent can also manage generative UI templates after the agent is saved:
1. Open **Agents** → select an agent → **Generative UI**
2. Create or edit templates used when that agent renders MCP App results
3. Preview with sample state
4. Save the agent
Agent templates pair with gateway tools `show_generative_ui`, template CRUD tools, and `show_generative_ui_from_template`. Prefer putting dynamic values in template **state** so runtime data can merge cleanly.
### Editor tips
* Start from a starter layout when available, then customize
* Keep layouts focused on one job (one chart, one table, one form)
* Preview before attaching the agent to external MCP clients
* Disable unused UI tools under agent **Setup → Enable MCP Tools** for least privilege
## When templates apply
| Path | When to use |
| ------------------------- | ---------------------------------------------------------- |
| **MCP Apps** library | Org-wide action-result templates reused across agents/apps |
| **Agent → Generative UI** | Agent-specific generative layouts for MCP hosts |
| **Gateway tools** | Runtime render from Claude/Cursor/other MCP clients |
Feature availability depends on deployment flags for MCP App UI / generative UI.
## Related
* [Agents — Generative UI](/user-guide/agents#generative-ui-templates)
* [MCP Gateway Resources](/user-guide/mcp-gateway/mcp-gateway-resources)
* [MCP Gateway Tools](/user-guide/mcp-gateway/mcp-gateway-tools)
* [Native MCP Servers](/user-guide/mcp-servers)
# MCP Gateway Authentication
Source: https://docs.apigene.ai/user-guide/mcp-gateway/mcp-gateway-authentication
How to authenticate with the MCP Gateway
## Authentication Methods
The MCP Gateway supports two authentication methods:
### OAuth Authentication (Recommended for User Applications)
Use OAuth when you need user-specific access:
* Automatically handled by your MCP client
* User context is maintained
* Actions are tracked per user
* No additional configuration needed
### API Key Authentication (For Server Integrations)
Use API keys for automated systems:
* Include `apigene-api-key` header in requests
* Direct server-to-server access
* No user context required
* Ideal for automated workflows
## How to Choose
**Use OAuth when:**
* Building user-facing applications
* Need to track actions per user
* Want automatic token management
**Use API key when:**
* Building server-to-server integrations
* Running automated systems
* Don't need user context
## Next Steps
* [Learn about available tools](/user-guide/mcp-gateway/mcp-gateway-tools)
* [See usage examples](/user-guide/mcp-gateway/mcp-gateway-examples)
# MCP Gateway Examples
Source: https://docs.apigene.ai/user-guide/mcp-gateway/mcp-gateway-examples
Practical examples for using the MCP Gateway
## Overview
This guide provides practical examples for common use cases with the MCP Gateway. All examples use standard MCP tool calling format.
## Example 1: Discovering and Executing an Action
### Step 1: Discover Available Actions
```json theme={null}
{
"tool": "list_actions",
"arguments": {
"requests": [
{
"app_name": "Slack",
"detail_level": "summary"
}
]
}
}
```
**Response:**
```json theme={null}
[
{
"operationId": "chat.postMessage",
"description": "Sends a message to a channel"
},
{
"operationId": "conversations.list",
"description": "Lists all channels in a Slack team"
},
{
"operationId": "users.info",
"description": "Gets information about a user"
}
]
```
### Step 2: Get Full Action Details
```json theme={null}
{
"tool": "list_actions",
"arguments": {
"requests": [
{
"app_name": "Slack",
"operationIds": ["chat.postMessage"]
}
]
}
}
```
**Response:**
```json theme={null}
[
{
"operationId": "chat.postMessage",
"description": "Sends a message to a channel",
"parameters": {
"channel": {
"type": "string",
"required": true,
"description": "Channel, private group, or IM channel to send message to"
},
"text": {
"type": "string",
"required": true,
"description": "Text of the message to send"
},
"thread_ts": {
"type": "string",
"required": false,
"description": "Provide another message's ts value to make this message a reply"
}
}
}
]
```
### Step 3: Execute the Action
```json theme={null}
{
"tool": "run_action",
"arguments": {
"app_name": "Slack",
"user_input": "Send a message to the general channel",
"context": {
"operationId": "chat.postMessage",
"channel": "#general",
"text": "Hello from Apigene!"
}
}
}
```
**Response:**
```json theme={null}
{
"status_code": 200,
"response_content": {
"ok": true,
"channel": "C1234567890",
"ts": "1234567890.123456",
"message": {
"text": "Hello from Apigene!",
"user": "U1234567890",
"ts": "1234567890.123456"
}
}
}
```
## Example 2: Searching for Actions
### Search for Message-Related Actions
```json theme={null}
{
"tool": "search_actions",
"arguments": {
"query": "send message",
"detail_level": "summary",
"max_results": 10
}
}
```
**Response:**
```json theme={null}
[
{
"app_name": "Slack",
"operationId": "chat.postMessage",
"description": "Sends a message to a channel",
"rating": 4.8
},
{
"app_name": "Microsoft Teams",
"operationId": "sendMessage",
"description": "Send a message to a channel or chat",
"rating": 4.6
},
{
"app_name": "Discord",
"operationId": "createMessage",
"description": "Create a message in a channel",
"rating": 4.5
}
]
```
### Get Details and Execute
After finding the right action, get full details and execute:
```json theme={null}
{
"tool": "list_actions",
"arguments": {
"requests": [
{
"app_name": "Slack",
"operationIds": ["chat.postMessage"]
}
]
}
}
```
Then execute with proper parameters.
## Example 3: Batch Execution
### Reading Multiple Emails
```json theme={null}
{
"tool": "run_action_batch",
"arguments": {
"app_name": "Gmail",
"user_input": "Read multiple emails",
"base_context": {
"operationId": "readEmail",
"format": "full"
},
"batch_context": [
{ "email_id": "msg_001" },
{ "email_id": "msg_002" },
{ "email_id": "msg_003" }
]
}
}
```
**Response:**
```json theme={null}
[
{
"status_code": 200,
"response_content": {
"id": "msg_001",
"subject": "Meeting Tomorrow",
"from": "colleague@example.com",
"body": "Let's meet at 2pm..."
}
},
{
"status_code": 200,
"response_content": {
"id": "msg_002",
"subject": "Project Update",
"from": "manager@example.com",
"body": "Here's the latest update..."
}
},
{
"status_code": 200,
"response_content": {
"id": "msg_003",
"subject": "Action Required",
"from": "system@example.com",
"body": "Please review the attached..."
}
}
]
```
## Example 4: Parallel Multi-Action Execution
### Fetching Data from Multiple Sources
```json theme={null}
{
"tool": "run_multi_actions",
"arguments": {
"actions": [
{
"app_name": "Gmail",
"user_input": "Get latest email",
"context": {
"operationId": "getLatestEmail"
}
},
{
"app_name": "Jira",
"user_input": "List my open issues",
"context": {
"operationId": "listIssues",
"assignee": "me",
"status": "open"
}
},
{
"app_name": "Slack",
"user_input": "Get unread message count",
"context": {
"operationId": "getUnreadCount"
}
}
]
}
}
```
**Response:**
```json theme={null}
{
"results": [
{
"success": true,
"index": 0,
"request": {
"app_name": "Gmail",
"user_input": "Get latest email",
"context": {
"operationId": "getLatestEmail"
}
},
"result": {
"status_code": 200,
"response_content": {
"id": "msg_123",
"subject": "Latest Email Subject",
"from": "sender@example.com"
}
}
},
{
"success": true,
"index": 1,
"request": {
"app_name": "Jira",
"user_input": "List my open issues",
"context": {
"operationId": "listIssues",
"assignee": "me",
"status": "open"
}
},
"result": {
"status_code": 200,
"response_content": {
"issues": [
{"id": "PROJ-123", "summary": "Fix bug"},
{"id": "PROJ-124", "summary": "Add feature"}
]
}
}
},
{
"success": true,
"index": 2,
"request": {
"app_name": "Slack",
"user_input": "Get unread message count",
"context": {
"operationId": "getUnreadCount"
}
},
"result": {
"status_code": 200,
"response_content": {
"unread_count": 5
}
}
}
],
"summary": {
"total": 3,
"successful": 3,
"failed": 0
}
}
```
## Example 5: Using Response Projection
### Extract Specific Fields from Large Response
```json theme={null}
{
"tool": "run_action",
"arguments": {
"app_name": "Jira",
"user_input": "List all issues",
"context": {
"operationId": "listIssues"
},
"response_projection": "{issues: issues[*].{id: id, key: key, summary: fields.summary, status: fields.status.name}}"
}
}
```
**Response:**
```json theme={null}
{
"status_code": 200,
"response_content": {
"issues": [
{
"id": "10001",
"key": "PROJ-123",
"summary": "Fix login bug",
"status": "In Progress"
},
{
"id": "10002",
"key": "PROJ-124",
"summary": "Add dark mode",
"status": "To Do"
}
]
}
}
```
### Filter and Aggregate Data
```json theme={null}
{
"tool": "run_action",
"arguments": {
"app_name": "Salesforce",
"user_input": "Get high-value opportunities",
"context": {
"operationId": "listOpportunities"
},
"response_projection": "opportunities[?amount > 10000].{name: name, amount: amount, stage: stageName}"
}
}
```
**Response:**
```json theme={null}
{
"status_code": 200,
"response_content": {
"opportunities": [
{
"name": "Enterprise Deal",
"amount": 50000,
"stageName": "Negotiation"
},
{
"name": "SMB Contract",
"amount": 15000,
"stageName": "Proposal"
}
]
}
}
```
## Example 6: Agent Mode - Getting Instructions
### Retrieve Agent Instructions
```json theme={null}
{
"tool": "get_instructions",
"arguments": {}
}
```
**Response:**
```json theme={null}
"You are a helpful AI assistant that can interact with various applications including Slack, Gmail, and Jira. Your capabilities include:
- Sending messages and notifications
- Reading and managing emails
- Creating and tracking issues
- Searching across multiple data sources
Available applications: Slack, Gmail, Jira, GitHub
Guidelines:
- Always confirm before executing destructive actions
- Provide clear summaries of actions taken
- Ask for clarification when parameters are ambiguous"
```
## Example 7: Agent Mode - Listing Applications
### Get All Apps with Action Summaries
```json theme={null}
{
"tool": "list_available_apps",
"arguments": {
"include_action_summaries": true,
"max_action_summary": 20
}
}
```
**Response:**
```json theme={null}
[
{
"app_name": "Slack",
"action_summaries": [
{
"operationId": "chat.postMessage",
"description": "Sends a message to a channel"
},
{
"operationId": "conversations.list",
"description": "Lists all channels"
}
]
},
{
"app_name": "Gmail",
"action_summaries": [
{
"operationId": "readEmail",
"description": "Reads an email by ID"
},
{
"operationId": "listEmails",
"description": "Lists emails in inbox"
}
]
}
]
```
## Example 8: Agent Mode - Context Management
### List All Contexts
```json theme={null}
{
"tool": "list_contexts",
"arguments": {}
}
```
**Response:**
```json theme={null}
{
"contexts": [
{
"id": "ctx_123",
"name": "Customer Support Knowledge",
"type": "Knowledge",
"summary": "Support policies and procedures"
},
{
"id": "ctx_456",
"name": "Product Information",
"type": "Knowledge",
"summary": "Product features and specifications"
}
],
"context_types": [
{
"type": "Knowledge",
"description": "Structured knowledge base information"
},
{
"type": "Instructions",
"description": "Agent instructions and guidelines"
}
]
}
```
### Search for Specific Contexts
```json theme={null}
{
"tool": "search_contexts",
"arguments": {
"query": "customer support",
"type": "Knowledge",
"max_results": 5
}
}
```
**Response:**
```json theme={null}
{
"contexts": [
{
"id": "ctx_123",
"name": "Customer Support Knowledge",
"type": "Knowledge",
"summary": "Support policies and procedures"
}
],
"context_types": [...]
}
```
### Get Context Details
```json theme={null}
{
"tool": "get_context",
"arguments": {
"context_id": "ctx_123"
}
}
```
**Response:**
```json theme={null}
{
"id": "ctx_123",
"name": "Product Knowledge Base",
"description": "Comprehensive information about our products...",
"summary": "Product information and features",
"type": "Knowledge",
"apps": ["Salesforce", "Zendesk"],
"status": "active",
"created_at": "2024-01-15T10:30:00Z"
}
```
### Create New Context
```json theme={null}
{
"tool": "add_context",
"arguments": {
"name": "Product Knowledge Base",
"description": "Comprehensive information about our products, features, and pricing...",
"summary": "Product information and features",
"type": "Knowledge",
"apps": ["Salesforce", "Zendesk"],
"status": "active"
}
}
```
**Response:**
```json theme={null}
{
"id": "ctx_789",
"name": "Product Knowledge Base",
"description": "Comprehensive information about our products, features, and pricing...",
"summary": "Product information and features",
"type": "Knowledge",
"apps": ["Salesforce", "Zendesk"],
"status": "active",
"created_at": "2024-01-15T10:30:00Z",
"_message": "Context created successfully and added to agent 'MyAgent'"
}
```
## Example 9: Complete Workflow
### Multi-Step Workflow Example
**Step 1:** Discover available actions
```json theme={null}
{
"tool": "list_actions",
"arguments": {
"requests": [
{ "app_name": "GitHub", "detail_level": "summary" },
{ "app_name": "Slack", "detail_level": "summary" }
]
}
}
```
**Step 2:** Get full details for specific actions
```json theme={null}
{
"tool": "list_actions",
"arguments": {
"requests": [
{
"app_name": "GitHub",
"operationIds": ["createIssue"]
},
{
"app_name": "Slack",
"operationIds": ["chat.postMessage"]
}
]
}
}
```
**Step 3:** Execute actions in sequence or parallel
```json theme={null}
{
"tool": "run_multi_actions",
"arguments": {
"actions": [
{
"app_name": "GitHub",
"user_input": "Create a new issue",
"context": {
"operationId": "createIssue",
"title": "Bug: Login not working",
"body": "Users cannot log in..."
}
},
{
"app_name": "Slack",
"user_input": "Notify team about new issue",
"context": {
"operationId": "chat.postMessage",
"channel": "#engineering",
"text": "New GitHub issue created: Bug: Login not working"
}
}
]
}
}
```
**Step 1 Response:**
```json theme={null}
{
"GitHub": [
{
"operationId": "createIssue",
"description": "Create a new issue in a repository"
},
{
"operationId": "listIssues",
"description": "List issues in a repository"
}
],
"Slack": [
{
"operationId": "chat.postMessage",
"description": "Sends a message to a channel"
}
]
}
```
**Step 2 Response:**
```json theme={null}
[
{
"operationId": "createIssue",
"description": "Create a new issue in a repository",
"parameters": {
"title": {"type": "string", "required": true},
"body": {"type": "string", "required": false},
"labels": {"type": "array", "required": false}
}
},
{
"operationId": "chat.postMessage",
"description": "Sends a message to a channel",
"parameters": {
"channel": {"type": "string", "required": true},
"text": {"type": "string", "required": true}
}
}
]
```
**Step 3 Response:**
```json theme={null}
{
"results": [
{
"success": true,
"index": 0,
"request": {
"app_name": "GitHub",
"user_input": "Create a new issue",
"context": {
"operationId": "createIssue",
"title": "Bug: Login not working",
"body": "Users cannot log in..."
}
},
"result": {
"status_code": 201,
"response_content": {
"id": 12345,
"number": 42,
"title": "Bug: Login not working",
"state": "open",
"url": "https://github.com/owner/repo/issues/42"
}
}
},
{
"success": true,
"index": 1,
"request": {
"app_name": "Slack",
"user_input": "Notify team about new issue",
"context": {
"operationId": "chat.postMessage",
"channel": "#engineering",
"text": "New GitHub issue created: Bug: Login not working"
}
},
"result": {
"status_code": 200,
"response_content": {
"ok": true,
"channel": "C1234567890",
"ts": "1234567890.123456",
"message": {
"text": "New GitHub issue created: Bug: Login not working"
}
}
}
}
],
"summary": {
"total": 2,
"successful": 2,
"failed": 0
}
}
```
## Best Practices
### 1. Use Summary Mode for Discovery
Always start with `detail_level: "summary"` when exploring actions to save tokens and improve performance.
### 2. Get Full Schemas Before Execution
Always call `list_actions` with specific `operationIds` to get complete parameter specifications before executing actions.
### 3. Use Batch Operations for Efficiency
When executing the same action multiple times, use `run_action_batch` instead of multiple `run_action` calls.
### 4. Leverage Parallel Execution
Use `run_multi_actions` when you need to fetch data from multiple sources simultaneously.
### 5. Use Response Projection for Large Data
Apply `response_projection` to reduce response size when you only need specific fields from large responses.
## Common Patterns
### Pattern: Discover → Get Details → Execute
1. Use `list_actions` with `detail_level: "summary"` to discover
2. Use `list_actions` with `operationIds` to get full schemas
3. Use `run_action` with complete parameters to execute
### Pattern: Search → Execute
1. Use `search_actions` to find relevant actions
2. Get full details for selected actions
3. Execute with proper parameters
### Pattern: Batch Processing
1. Identify the action to execute multiple times
2. Prepare `base_context` with shared parameters
3. Prepare `batch_context` with varying parameters
4. Execute with `run_action_batch`
## Next Steps
* [Review all available tools](/user-guide/mcp-gateway/mcp-gateway-tools)
* [Learn about resources](/user-guide/mcp-gateway/mcp-gateway-resources)
# MCP vs Agent Modes
Source: https://docs.apigene.ai/user-guide/mcp-gateway/mcp-gateway-modes
Understanding the difference between MCP and Agent modes
## Overview
The MCP Gateway operates in two modes, each optimized for different use cases. Choose the mode that best fits your needs.
## MCP Mode
**Endpoint**: `https://app.apigene.ai/mcp/{genai_app}/mcp`
> **Note**: `{genai_app}` is the name of the agent or MCP that is configured in Apigene admin.
### Capabilities
MCP mode provides core action execution capabilities:
* ✅ List and search actions
* ✅ Execute single actions
* ✅ Batch action execution
* ✅ Parallel multi-action execution
* ✅ Optional: MCP App UI tools (`run_action_ui`, `run_multi_actions_ui`) when UI features are enabled for your environment
* ✅ Optional: Generative UI tools (`show_generative_ui`, template CRUD, `show_generative_ui_from_template`) when generative UI is enabled
### Use Cases
* Simple API integrations
* Direct action execution
* Applications that don't need agent features
* Lightweight integrations
### Available Tools
* `list_actions`
* `search_actions`
* `run_action`
* `run_action_batch`
* `run_multi_actions`
* `run_action_ui` (when MCP App UI is enabled)
* `run_multi_actions_ui` (when MCP App UI is enabled)
* `show_generative_ui` (when generative UI is enabled)
* `list_generative_ui_templates` (when generative UI is enabled)
* `create_generative_ui_template` (when generative UI is enabled)
* `update_generative_ui_template` (when generative UI is enabled)
* `get_generative_ui_template` (when generative UI is enabled)
* `delete_generative_ui_template` (when generative UI is enabled)
* `show_generative_ui_from_template` (when generative UI is enabled)
## Agent Mode
**Endpoint (live)**: `https://app.apigene.ai/agent/{genai_app}/mcp`
**Endpoint (design / draft)**: `https://app.apigene.ai/agent/{genai_app}/design/mcp`
> **Note**: `{genai_app}` is the name of the agent or MCP that is configured in Apigene admin. Connect clients that should run the published agent to the live URL. The design URL reads and writes the unpublished draft until you [publish](/user-guide/agents#draft-live-and-version-history).
## Design-mode vs live-mode tools
Agent mode tools fall into two groups. **Live-mode** tools stay available to anyone who can use the shared agent. **Design-mode** tools are authoring mutations: they are registered for the agent creator (typically on the design URL) and are hidden from other users in live MCP.
### Design-mode only (creator)
These tools are not available to viewers of a shared agent:
| Tool | Purpose |
| ------------------------------- | ------------------------------------------------ |
| `add_skill` | Create a skill on the agent |
| `add_context` | Create a context |
| `create_workflow` | Persist a new workflow |
| `update_workflow` | Edit a stored workflow |
| `delete_workflow` | Delete a stored workflow |
| `show_generative_ui` | Render ad-hoc json-render UI from an inline spec |
| `create_generative_ui_template` | Create a UI template |
| `update_generative_ui_template` | Edit a UI template |
| `delete_generative_ui_template` | Delete a UI template |
### Live mode (creator and viewers)
Everyone with access to the agent can list, read, search, and run:
* Actions: `list_actions`, `search_actions`, `run_action`, `run_action_batch`, `run_multi_actions`, and UI variants when enabled
* Agent: `get_instructions`, `list_available_apps`
* Contexts: `list_contexts`, `get_context`, `search_contexts`
* Skills: `list_skills`, `get_skill`, `get_skill_content`
* Workflows: `list_workflows`, `get_workflow`, `run_workflow`, `resume_workflow`
* Generative UI: `list_generative_ui_templates`, `get_generative_ui_template`, `show_generative_ui_from_template`
See the [complete tool index](/user-guide/mcp-gateway/mcp-gateway-tools#complete-tool-index) for MCP vs Agent mode plus design vs live.
### Capabilities
Agent mode includes everything in MCP mode plus:
* ✅ All MCP mode features
* ✅ Access to agent instructions
* ✅ Application discovery
* ✅ Context management
* ✅ Context creation and search
* ✅ Agent Skills: list, fetch metadata/files, fetch `SKILL.md` content, and create skills
* ✅ Agent Workflows: list/create/update/delete, `run_workflow` (with dry run), and `resume_workflow` for human approvals
### Use Cases
* Full agent workflows
* Applications needing context awareness
* Complex multi-step operations
* AI assistants with extended capabilities
### Available Tools
**All MCP Mode Tools Plus:**
* `get_instructions`
* `list_available_apps`
* `list_contexts`
* `get_context`
* `search_contexts`
* `add_context`
* `list_skills`
* `get_skill`
* `get_skill_content`
* `add_skill`
* `list_workflows`
* `create_workflow`
* `get_workflow`
* `update_workflow`
* `delete_workflow`
* `run_workflow`
* `resume_workflow`
## Choosing the Right Mode
### Use MCP Mode When:
* You only need basic action execution
* You don't need agent instructions
* Context management isn't required
* You want a simpler integration
### Use Agent Mode When:
* You need full agent capabilities
* You want to access agent instructions
* You need context management
* You're building AI assistants
* You want complete workflow support
## Resources Available
### MCP Mode Resources
* App Actions Template
* Action Details Template
* MCP App UI templates (`ui://…`) when MCP App UI is enabled
### Agent Mode Resources
* Agent Instructions
* Available Apps List
* Contexts List
* Context Type Definitions
* Skills list, skill details, and skill content (`apigene://…/skills` — see [resources](/user-guide/mcp-gateway/mcp-gateway-resources))
* App Actions Template
* Action Details Template
* Context Details Template
* MCP App UI resources (`ui://run-action-ui`, `ui://run-multi-actions-ui`) when MCP App UI is enabled
* Generative UI resource (`ui://show-generative-ui`) when generative UI is enabled
## Switching Between Modes
You can use both modes simultaneously by connecting to different endpoints. Each mode maintains its own session and capabilities.
## Next Steps
* [Explore available tools](/user-guide/mcp-gateway/mcp-gateway-tools)
* [See usage examples](/user-guide/mcp-gateway/mcp-gateway-examples)
# MCP Gateway Overview
Source: https://docs.apigene.ai/user-guide/mcp-gateway/mcp-gateway-overview
Connect AI assistants to Apigene using the Model Context Protocol
## What is the MCP Gateway?
The Apigene MCP Gateway enables AI assistants and chatbots to interact with your Apigene applications through the Model Context Protocol (MCP). Connect tools like Claude Desktop, Cline, or any MCP-compatible client to discover and execute actions across your integrated applications.
## Key Capabilities
### Discover Applications and Actions
* Browse all available applications in your agent
* Search for specific actions by description or type
* Get detailed action schemas and parameters
### Execute Actions
* Run single actions with full parameter control
* Execute the same action multiple times in parallel (batch mode)
* Run different actions simultaneously across multiple apps
### Manage Context (Agent Mode)
* Access agent instructions and capabilities
* List and search available contexts
* Create new contexts to extend agent knowledge
### Skills and optional UI (Agent Mode and deployments with MCP App UI)
* List, read, and create [Agent Skills](https://github.com/agentskills/agentskills) attached to the agent (`list_skills`, `get_skill`, `get_skill_content`, `add_skill`)
* When MCP App UI is enabled: run actions with visual widgets (`run_action_ui`, `run_multi_actions_ui`)
* When generative UI is enabled: render json-render specs and manage templates (`show_generative_ui`, `list_generative_ui_templates`, `create_generative_ui_template`, `update_generative_ui_template`, `get_generative_ui_template`, `delete_generative_ui_template`, `show_generative_ui_from_template`)
## Two Operation Modes
### MCP Mode
Basic action execution for simple integrations:
* List and search actions
* Execute actions across applications
* Perfect for straightforward API interactions
### Agent Mode
Full agent capabilities with enhanced features:
* Access agent instructions
* Context management
* Application discovery
* Agent Skills (list, fetch content, create)
* Complete agent workflow support
## Getting Started
### Prerequisites
* An Apigene account with configured applications
* An MCP-compatible client (Claude Desktop, Cline, etc.)
* Your application identifier (`genai_app`)
### Connection Steps
1. **Get Your Endpoint**
* MCP Mode: `https://app.apigene.ai/mcp/{genai_app}/mcp`
* Agent Mode (live): `https://app.apigene.ai/agent/{genai_app}/mcp`
* Agent design (draft): `https://app.apigene.ai/agent/{genai_app}/design/mcp`
> **Note**: `{genai_app}` is the name of the agent or MCP that is configured in Apigene admin. The live URL uses the published agent. Use the design URL only when you want to author against the unpublished draft (skills, workflows, templates). [Which tools are design-only vs live](/user-guide/mcp-gateway/mcp-gateway-modes#design-mode-vs-live-mode-tools).
2. **Configure Authentication**
* Use OAuth for user-based access
* Or use API key for server-to-server access
3. **Connect Your Client**
* Add the gateway URL to your MCP client configuration
* Initialize the connection
* Start using tools and resources
## What You Can Do
### For AI Assistants
Connect your AI assistant to execute real actions across your applications:
* "Send a message in Slack"
* "Create a Jira issue"
* "Get my latest emails from Gmail"
### For Developers
Build integrations that can discover and use Apigene capabilities:
* Dynamic action discovery
* Flexible execution patterns
* Standard MCP protocol compliance
## Next Steps
* [Explore available tools](/user-guide/mcp-gateway/mcp-gateway-tools)
* [Learn about resources](/user-guide/mcp-gateway/mcp-gateway-resources)
* [See usage examples](/user-guide/mcp-gateway/mcp-gateway-examples)
# MCP Gateway Resources
Source: https://docs.apigene.ai/user-guide/mcp-gateway/mcp-gateway-resources
Available resources in the MCP Gateway
## Overview
Resources provide read-only access to information about your agent, applications, actions, contexts, and skills. MCP App UI resources expose templates for visual rendering in supported clients. They can be accessed through standard MCP resource requests.
## Static Resources (Agent Mode Only)
### Agent Instructions
**URI**: `apigene://{genai_app}/instructions`
Get the complete agent instructions including:
* Agent description and capabilities
* Internal guidelines
* Available applications list
### Available Apps List
**URI**: `apigene://{genai_app}/apps`
List all applications available in the agent:
* App names and summaries
* Action summaries (optional)
* App capabilities overview
### Contexts List
**URI**: `apigene://{genai_app}/contexts`
View all available contexts:
* Context IDs and names
* Context summaries
* Context types
### Context Type Definitions
**URI**: `apigene://{genai_app}/context-types`
Get all context type templates:
* Available context types
* How to create each type
* When to use each type
### Skills List
**URI**: `apigene://{genai_app}/skills`
List all skills available to the agent (metadata summary appropriate for discovery). For creating or updating skills, use the `add_skill` tool (see [MCP Gateway Tools](/user-guide/mcp-gateway/mcp-gateway-tools)).
## Dynamic Resource Templates
### App Actions
**URI**: `apigene://{genai_app}/apps/{app_name}/actions`
Get actions for a specific app:
* All available actions (summary or full details)
* Action descriptions
* Operation IDs
**Parameters:**
* `app_name`: The application identifier
### Action Details
**URI**: `apigene://{genai_app}/apps/{app_name}/actions/{operationId}`
Get complete schema for a specific action:
* Full parameter specifications
* Required and optional parameters
* Parameter types and descriptions
**Parameters:**
* `app_name`: The application identifier
* `operationId`: The specific action identifier
### Context Details (Agent Mode Only)
**URI**: `apigene://{genai_app}/contexts/{context_id}`
Get detailed information about a specific context:
* Full context description
* Associated apps
* Usage guidelines
**Parameters:**
* `context_id`: The context identifier
### Skill Details (Agent Mode Only)
**URI**: `apigene://{genai_app}/skills/{skill_id}`
Get skill metadata and optional packaged files (`scripts`, `references`, `assets`) when present. For the full `SKILL.md` body, use the Skill Content resource below or the `get_skill_content` tool.
**Parameters:**
* `skill_id`: The skill identifier
### Skill Content (Agent Mode Only)
**URI**: `apigene://{genai_app}/skills/{skill_id}/content`
Get the full `SKILL.md` text (front matter and Markdown) for a skill. MIME type is `text/markdown`.
**Parameters:**
* `skill_id`: The skill identifier
## MCP App UI Resources
When MCP App UI is enabled for your Apigene deployment, the gateway may expose UI resources for hosts that support embedded MCP Apps (for example Claude). These pair with the `run_action_ui` and `run_multi_actions_ui` tools.
### Run Action UI
**URI**: `ui://run-action-ui`
Template used to render a single action result inside an MCP App iframe. The host loads this resource according to the MCP Apps protocol.
### Run Multi Actions UI
**URI**: `ui://run-multi-actions-ui`
Template used to render multiple parallel action results (for example in a grid or mesh layout).
### Show Generative UI
**URI**: `ui://show-generative-ui`
MCP App widget for **json-render** generative UI specs. Used by `show_generative_ui` and `show_generative_ui_from_template`. Renders interactive layouts (charts, tables, forms) from `{ root, elements, state? }` specs — not HTML action-result templates.
### UI Action Templates (Dynamic)
**URI**: `ui://templates/{template_id}`
Legacy/dynamic HTML templates for rendering structured API action results (table, list, chart). Loaded on demand for `run_action_ui` when a stored template id is used.
## Using Resources
Resources are accessed through standard MCP resource requests. Your MCP client will handle the protocol details automatically.
### Example: Reading Agent Instructions
```json theme={null}
{
"method": "resources/read",
"params": {
"uri": "apigene://my-agent/instructions"
}
}
```
### Example: Getting App Actions
```json theme={null}
{
"method": "resources/read",
"params": {
"uri": "apigene://my-agent/apps/Slack/actions"
}
}
```
### Example: Listing Skills (Agent Mode)
```json theme={null}
{
"method": "resources/read",
"params": {
"uri": "apigene://my-agent/skills"
}
}
```
## Resource vs Tools
**Resources** provide read-only information:
* Use when you need to read data
* Accessed via `resources/read`
* Return structured information
**Tools** execute operations:
* Use when you need to perform operations (including `run_action`, context updates, and `add_skill`)
* Accessed via `tools/call`
* Execute actions and return results
## Next Steps
* [Learn about available tools](/user-guide/mcp-gateway/mcp-gateway-tools)
* [See usage examples](/user-guide/mcp-gateway/mcp-gateway-examples)
# MCP Gateway Tools
Source: https://docs.apigene.ai/user-guide/mcp-gateway/mcp-gateway-tools
Complete reference for all available tools
## Overview
Tools enable you to discover, search, and execute actions across your Apigene applications. Agent mode adds context tools, [Agent Skills](https://github.com/agentskills/agentskills)-compatible skill listing/retrieval/creation, and [Agent Workflows](/user-guide/workflows) (`run_workflow`, `resume_workflow`, and CRUD). When MCP App UI is enabled, additional tools render results in UI widgets. All tools follow the standard MCP tool calling protocol.
## Tools Reference
### get\_instructions
Get the complete agent instructions and capabilities.
**Available in:** Agent mode only
**Parameters:** None
**Returns:** Agent instructions including description, guidelines, and available apps
**Example:**
```json theme={null}
{
"tool": "get_instructions",
"arguments": {}
}
```
### list\_available\_apps
List all available applications in the agent.
**Available in:** Agent mode only
**Parameters:**
* `include_action_summaries` (boolean, optional): Include action summaries (default: `true`)
* `max_action_summary` (number, optional): Max summaries per app (default: `20`)
**Returns:** List of applications with optional action summaries
**Example:**
```json theme={null}
{
"tool": "list_available_apps",
"arguments": {
"include_action_summaries": true,
"max_action_summary": 10
}
}
```
### list\_actions
Retrieve actions from one or multiple applications.
**Available in:** Both MCP and Agent modes
**Parameters:**
* `requests` (array, required): Array of action requests, each containing:
* `app_name` (string, required): Application identifier
* `operationIds` (array, optional): Specific action IDs to fetch. If omitted, returns all actions
* `detail_level` (string, optional): `"summary"` or `"full"` (default: `"full"`)
**Usage Modes:**
* **Discovery Mode**: Omit `operationIds` to get all actions (use `detail_level: "summary"` for lightweight listing)
* **Details Mode**: Provide `operationIds` to get full parameter schemas
**Returns:** Array of actions or object with app names as keys (for multiple apps)
**Example:**
```json theme={null}
{
"tool": "list_actions",
"arguments": {
"requests": [
{
"app_name": "Slack",
"detail_level": "summary"
}
]
}
}
```
### search\_actions
Search across all agentic metadata to find relevant actions.
**Available in:** Both MCP and Agent modes
**Parameters:**
* `query` (string, optional): Free text search
* `action_type` (string, optional): Filter by type (get, search, add, update, delete, execute)
* `resource` (string, optional): Filter by resource type
* `min_rating` / `max_rating` (number, optional): Filter by rating
* `required_input` (string, optional): Only actions requiring this parameter
* `max_results` (number, optional): Maximum results to return
* `detail_level` (string, optional): `"summary"` or `"full"` (default: `"full"`)
**Returns:** Filtered list of matching actions. When nothing matches, the response may include `actions`, a short `message`, and `suggestions` (for example: broaden the query, use `list_available_apps`, or use `list_actions` for a specific app) instead of only an empty list.
**Example:**
```json theme={null}
{
"tool": "search_actions",
"arguments": {
"query": "send message",
"detail_level": "summary"
}
}
```
### run\_action
Execute a single action for a specific application.
**Available in:** Both MCP and Agent modes
**Parameters:**
* `app_name` (string, required): Application identifier
* `user_input` (string, required): Natural language description
* `context` (object, required): Action parameters including `operationId`
* `response_format` (string, optional): `"raw"` or `"formatted_md"` (default: `"raw"`)
* `response_projection` (string, optional): JMESPath expression to transform response
* `customer_execution_context` (object, optional): Customer-specific context
* `reasoning` (string, optional): Short explanation of why this action was chosen; supports decision tracing in agent workflows
**Returns:** Action execution result
**Example:**
```json theme={null}
{
"tool": "run_action",
"arguments": {
"app_name": "Slack",
"user_input": "Send a message to #general",
"context": {
"operationId": "chat.postMessage",
"channel": "#general",
"text": "Hello, world!"
}
}
}
```
### run\_action\_batch
Execute the same action multiple times in parallel with different parameters.
**Available in:** Both MCP and Agent modes
**Parameters:**
* `app_name` (string, required): Application identifier
* `user_input` (string, required): Natural language description
* `base_context` (object, required): Shared parameters (must include `operationId`)
* `batch_context` (array, required): Array of varying parameters, one per execution
* `response_format` (string, optional): Output format
* `response_projection` (string, optional): JMESPath expression
* `customer_execution_context` (object, optional): Customer context
**Returns:** Object with `batch_results` array and `summary` statistics
**Example:**
```json theme={null}
{
"tool": "run_action_batch",
"arguments": {
"app_name": "Gmail",
"user_input": "Read multiple emails",
"base_context": {
"operationId": "readEmail"
},
"batch_context": [
{ "email_id": "123" },
{ "email_id": "456" },
{ "email_id": "789" }
]
}
}
```
### run\_multi\_actions
Execute multiple different actions in parallel across different applications.
**Available in:** Both MCP and Agent modes
**Parameters:**
* `actions` (array, required): Array of action requests, each containing:
* `app_name` (string, required)
* `user_input` (string, required)
* `context` (object, required): Must include `operationId`
* `response_format` (string, optional)
* `response_projection` (string, optional)
* `customer_execution_context` (object, optional)
* `template_id` (string, optional): Only set when a specific MCP App template should render that action’s result in the UI
**Returns:** Object with `results` array and `summary` statistics
**Example:**
```json theme={null}
{
"tool": "run_multi_actions",
"arguments": {
"actions": [
{
"app_name": "Gmail",
"user_input": "Get latest email",
"context": { "operationId": "getLatestEmail" }
},
{
"app_name": "Jira",
"user_input": "List my tasks",
"context": { "operationId": "listIssues", "assignee": "me" }
}
]
}
}
```
### run\_action\_ui
Execute a single action with MCP App UI rendering so results can be shown in a visual widget (when your host supports MCP Apps).
**Available in:** Both MCP and Agent modes, when MCP App UI features are enabled for your Apigene deployment.
**Parameters:**
* `app_name` (string, required): Application identifier
* `user_input` (string, required): Natural language description
* `context` (object, required): Action parameters including `operationId`
* `response_format` (string, optional): `"raw"` or `"formatted_md"` (default: `"raw"`)
* `customer_execution_context` (object, optional): Customer-specific context
* `reasoning` (string, optional): Why this action was chosen
* `template_id` (string, optional): Only include when the user explicitly requests a specific template; otherwise omit so the default template applies
**Returns:** Action result; when a template applies, the response includes data suitable for the UI resource (see [MCP Gateway Resources](/user-guide/mcp-gateway/mcp-gateway-resources)).
**Note:** Unlike `run_action`, this tool does not accept `response_projection`.
### run\_multi\_actions\_ui
Execute multiple different actions in parallel with MCP App UI rendering (for example a grid or mesh layout comparing outputs).
**Available in:** Both MCP and Agent modes, when MCP App UI features are enabled for your Apigene deployment.
**Parameters:**
* `actions` (array, required): Same shape as `run_multi_actions` (each item may include `template_id` when a specific template is requested)
**Returns:** Combined results with UI-oriented payload for supported hosts.
## Generative UI Tools
These tools render **json-render** specs as interactive MCP App widgets. They are separate from `run_action_ui` (which visualizes API action results). Generative UI tools are available when MCP App UI is enabled (`APIGENE_FEATURE_SHOW_GENERATIVE_UI` is not disabled on your deployment).
Only call generative UI tools when the user **explicitly** asks for interactive or visual UI. Do not auto-invoke for normal text answers.
### show\_generative\_ui
Render a one-off generative UI from an inline json-render spec.
**Available in:** Both MCP and Agent modes, when generative UI is enabled. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
**Parameters:**
* `title` (string, optional): Heading shown above the widget
* `spec` (object, required): json-render spec `{ root, elements, state? }` — layout in `elements`, dynamic values in `state` bound via `{ "$state": "/path" }`
**Returns:** Validated spec plus MCP App metadata pointing at `ui://show-generative-ui`.
**Example:**
```json theme={null}
{
"tool": "show_generative_ui",
"arguments": {
"title": "Plan comparison",
"spec": {
"root": "stack",
"elements": {
"stack": { "type": "Stack", "props": {}, "children": ["title"] },
"title": { "type": "Text", "props": { "text": "Hello" }, "children": [] }
}
}
}
}
```
### list\_generative\_ui\_templates
List saved generative UI templates for the agent from the MCP connection URL.
**Available in:** Both MCP and Agent modes, when generative UI is enabled.
**Parameters:**
* `detailed` (boolean, optional, default `false`): If `true`, include full `generative_spec` per template; if omitted/`false`, return summary fields only (`template_id`, description, audit fields)
**Returns:** Array of template records from the generative-ui-templates API.
### create\_generative\_ui\_template
Persist a new generative UI template for reuse.
**Available in:** Both MCP and Agent modes, when generative UI is enabled. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
**Parameters:**
* `template_id` (string, required): Unique template id (client-provided)
* `generative_spec` (object, required): json-render spec (same shape as `show_generative_ui`)
* `description` (string, optional): Human-readable description
**Returns:** Created template record.
Put all dynamic values in `state`, not as literals in `elements`. `show_generative_ui_from_template` only deep-merges runtime `data` into `state`.
### update\_generative\_ui\_template
Patch an existing template.
**Available in:** Both MCP and Agent modes, when generative UI is enabled. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
**Parameters:**
* `template_id` (string, required): Template to update
* `description` (string, optional, nullable): New description; `null` clears it; omit to leave unchanged
* `generative_spec` (object, optional): Replacement spec; omit to keep current layout
**Returns:** Updated template record.
### get\_generative\_ui\_template
Load one template including its full `generative_spec`.
**Available in:** Both MCP and Agent modes, when generative UI is enabled.
**Parameters:**
* `template_id` (string, required)
**Returns:** Full template record.
### delete\_generative\_ui\_template
Remove a saved template.
**Available in:** Both MCP and Agent modes, when generative UI is enabled. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
**Parameters:**
* `template_id` (string, required)
**Returns:** Deletion confirmation.
### show\_generative\_ui\_from\_template
Render UI from a saved template, merging runtime data into `spec.state`.
**Available in:** Both MCP and Agent modes, when generative UI is enabled.
**Parameters:**
* `template_id` (string, required): Id from `create_generative_ui_template`
* `title` (string, optional): Override title
* `data` (object, optional): Values deep-merged into the template's `state` before render
**Returns:** Rendered widget via `ui://show-generative-ui`.
**Example:**
```json theme={null}
{
"tool": "show_generative_ui_from_template",
"arguments": {
"template_id": "pricing-table",
"data": { "selectedPlan": "pro" }
}
}
```
### list\_contexts
List all available contexts and context type definitions.
**Available in:** Agent mode only
**Parameters:** None
**Returns:** Object with `contexts` array and `context_types` array
**Example:**
```json theme={null}
{
"tool": "list_contexts",
"arguments": {}
}
```
### get\_context
Get detailed information about a specific context.
**Available in:** Agent mode only
**Parameters:**
* `context_id` (string, required): The context identifier
**Returns:** Full context details
**Example:**
```json theme={null}
{
"tool": "get_context",
"arguments": {
"context_id": "ctx_123"
}
}
```
### search\_contexts
Search for contexts with flexible filtering.
**Available in:** Agent mode only
**Parameters:**
* `query` (string, optional): Search query
* `type` (string, optional): Filter by context type
* `status` (string, optional): Filter by status (default: `"active"`)
* `max_results` (number, optional): Maximum results (default: `5`)
**Returns:** Object with matching `contexts` and `context_types`
**Example:**
```json theme={null}
{
"tool": "search_contexts",
"arguments": {
"query": "customer support",
"type": "Knowledge"
}
}
```
### add\_context
Create a new context in the system.
**Available in:** Agent mode only. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
**Parameters:**
* `name` (string, required): Unique context name
* `description` (string, required): Detailed description
* `summary` (string, optional): Short summary
* `when_to_use` (string, optional): Usage guidelines
* `type` (string, optional): Context type (must match existing types)
* `apps` (array, optional): Associated app names
* `status` (string, optional): `"active"` or `"disabled"` (default: `"active"`)
**Returns:** Created context object
**Example:**
```json theme={null}
{
"tool": "add_context",
"arguments": {
"name": "Customer Support Guidelines",
"description": "Guidelines for handling customer support requests...",
"summary": "Support handling guidelines",
"type": "Knowledge",
"apps": ["Zendesk", "Slack"]
}
}
```
### list\_skills
List skill metadata attached to the agent (Agent Skills style). Does not return the full `SKILL.md` body; use `get_skill_content` for that.
**Available in:** Agent mode only
**Parameters:**
* `detail_level` (string, optional): `"summary"` (id, name, description only; fewer tokens) or `"full"` (all metadata fields; default: `"full"`)
**Returns:** Object with `skill_list` entries. Summary mode is best for discovery; full mode includes fields such as license, compatibility, metadata, allowed tools, status, and timestamps.
**Example:**
```json theme={null}
{
"tool": "list_skills",
"arguments": {
"detail_level": "summary"
}
}
```
### get\_skill
Fetch one skill by id: metadata plus optional packaged files (`scripts`, `references`, `assets`). Does not return the main `SKILL.md` body; use `get_skill_content` for the instruction text.
**Available in:** Agent mode only
**Parameters:**
* `skill_id` (string, required): Skill identifier
**Returns:** Object with a `skill` payload (metadata and optional path→content maps for scripts, references, assets).
**Example:**
```json theme={null}
{
"tool": "get_skill",
"arguments": {
"skill_id": "sk_abc123"
}
}
```
### get\_skill\_content
Return the full `SKILL.md` content for a skill (YAML front matter plus Markdown body).
**Available in:** Agent mode only
**Parameters:**
* `skill_id` (string, required): Skill identifier
**Returns:** Object with a `content` string.
**Example:**
```json theme={null}
{
"tool": "get_skill_content",
"arguments": {
"skill_id": "sk_abc123"
}
}
```
### add\_skill
Create a new skill and attach it to the current agent. Content should follow the [Agent Skills specification](https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx) (valid name format, description length, structured front matter, reasonably sized body with long reference material in `references/` when needed).
**Available in:** Agent mode only. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
**Parameters:**
* `name` (string, required): Skill name (lowercase, hyphens; per spec)
* `description` (string, required): What the skill does and when to use it
* `content` (string, required): Full `SKILL.md` (front matter + Markdown body)
* `license` (string, optional)
* `compatibility` (string, optional)
* `metadata` (object, optional)
* `allowed_tools` (string, optional)
* `status` (string, optional): `"active"` or `"disabled"` (default: `"active"`)
* `scripts` (object, optional): Map of file path to content under `scripts/`
* `references` (object, optional): Map of file path to content under `references/`
* `assets` (object, optional): Map of file path to content under `assets/`
**Returns:** The created skill record.
**Example:**
```json theme={null}
{
"tool": "add_skill",
"arguments": {
"name": "my-workflow",
"description": "Steps for our internal review workflow.",
"content": "---\nname: my-workflow\ndescription: Steps for our internal review workflow.\n---\n\n## When to use\n..."
}
}
```
## Agent workflow tools
Multi-step graphs on an agent. Product guide: [Workflows](/user-guide/workflows).
### list\_workflows
List workflows for the current agent.
**Available in:** Agent mode only
**Parameters:**
* `detailed` (boolean, optional): Return full definitions instead of summaries
### create\_workflow
Create a workflow (`workflow_id`, `description`, `nodes`, `connections`; optional `name`, `inputs`).
**Available in:** Agent mode only. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
### get\_workflow
Fetch one workflow by `workflow_id` (`detailed` optional).
**Available in:** Agent mode only
### update\_workflow
Update an existing workflow by `workflow_id` (optional fields: `description`, `name`, `nodes`, `connections`, `inputs`).
**Available in:** Agent mode only. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
### delete\_workflow
Delete a workflow by `workflow_id`.
**Available in:** Agent mode only. **Design-mode only** — hidden from viewers of a shared agent in live MCP.
### run\_workflow
Execute a workflow.
**Available in:** Agent mode only
**Parameters:**
* `workflow_id` (string, required)
* `inputs` (object, optional): Runtime inputs merged over stored defaults
* `include_data` (boolean, optional): Include per-step traces (needed to **Simulate** in Copilot)
* `dry_run` (boolean, optional): Walk the graph without live API / MCP / LLM side effects
**Example:**
```json theme={null}
{
"tool": "run_workflow",
"arguments": {
"workflow_id": "onboard-new-hire",
"inputs": { "email": "alex@example.com" },
"include_data": true,
"dry_run": true
}
}
```
### resume\_workflow
Continue a run paused at a human approval (`waiting_human`).
**Available in:** Agent mode only
**Parameters:**
* `run_id` (string, required)
* `decision` (string, required): `"approve"` or `"reject"`
* `edits` (object, optional): Field overrides before approve
* `reason` (string, optional)
* `include_data` (boolean, optional)
## Recommended Workflows
### Discovering and Executing Actions
1. **Discovery**: Use `list_actions` with `detail_level: "summary"` to find relevant actions
2. **Get Details**: Use `list_actions` with `operationIds` to get full parameter schemas
3. **Execute**: Use `run_action` with complete parameters
### Searching for Actions
1. **Search**: Use `search_actions` with `detail_level: "summary"` to find actions
2. **Get Details**: Use `list_actions` with specific `operationIds` for full schemas
3. **Execute**: Use `run_action` with proper parameters
### Batch Operations
1. **Identify Action**: Find the action you want to execute multiple times
2. **Prepare Batch**: Create `base_context` with shared parameters and `batch_context` with varying parameters
3. **Execute**: Use `run_action_batch` for parallel execution
### Skills
1. **Discover**: `list_skills` with `detail_level: "summary"` to see what exists
2. **Read instructions**: `get_skill_content` for the main `SKILL.md` body when activating a skill
3. **Optional files**: `get_skill` if you need scripts, references, or assets
4. **Create**: `add_skill` when adding a new skill to the agent (follow Agent Skills formatting rules)
### Agent Workflows
1. **Create / update**: `create_workflow` or `update_workflow` with nodes and connections
2. **Dry run**: `run_workflow` with `dry_run: true` and `include_data: true`
3. **Simulate** in Copilot on the agent's **Workflows** tab after a traced run
4. **HITL**: when status is `waiting_human`, call `resume_workflow` with `run_id` and `decision`
### Generative UI
1. **Ad hoc**: `show_generative_ui` with an inline `{ root, elements, state? }` spec
2. **Persist**: `create_generative_ui_template` → `list_generative_ui_templates` / `get_generative_ui_template` to manage
3. **Render saved**: `show_generative_ui_from_template` with `data` merged into template `state`
4. **Update or remove**: `update_generative_ui_template` or `delete_generative_ui_template`
Author templates in the Copilot **Agents** editor (**Generative UI** tab) or entirely via these MCP tools.
## Complete Tool Index
| Tool | MCP mode | Agent live | Agent design |
| ---------------------------------- | -------- | ---------- | ------------ |
| `list_actions` | ✅ | ✅ | ✅ |
| `search_actions` | ✅ | ✅ | ✅ |
| `run_action` | ✅ | ✅ | ✅ |
| `run_action_batch` | ✅ | ✅ | ✅ |
| `run_multi_actions` | ✅ | ✅ | ✅ |
| `run_action_ui` | ✅\* | ✅\* | ✅\* |
| `run_multi_actions_ui` | ✅\* | ✅\* | ✅\* |
| `show_generative_ui` | ✅\* | — | ✅\* |
| `list_generative_ui_templates` | ✅\* | ✅\* | ✅\* |
| `create_generative_ui_template` | ✅\* | — | ✅\* |
| `update_generative_ui_template` | ✅\* | — | ✅\* |
| `get_generative_ui_template` | ✅\* | ✅\* | ✅\* |
| `delete_generative_ui_template` | ✅\* | — | ✅\* |
| `show_generative_ui_from_template` | ✅\* | ✅\* | ✅\* |
| `get_instructions` | — | ✅ | ✅ |
| `list_available_apps` | — | ✅ | ✅ |
| `list_contexts` | — | ✅ | ✅ |
| `get_context` | — | ✅ | ✅ |
| `search_contexts` | — | ✅ | ✅ |
| `add_context` | — | — | ✅ |
| `list_skills` | — | ✅ | ✅ |
| `get_skill` | — | ✅ | ✅ |
| `get_skill_content` | — | ✅ | ✅ |
| `add_skill` | — | — | ✅ |
| `list_workflows` | — | ✅ | ✅ |
| `create_workflow` | — | — | ✅ |
| `get_workflow` | — | ✅ | ✅ |
| `update_workflow` | — | — | ✅ |
| `delete_workflow` | — | — | ✅ |
| `run_workflow` | — | ✅ | ✅ |
| `resume_workflow` | — | ✅ | ✅ |
\* Requires MCP App UI / generative UI features to be enabled on your deployment. Individual tools can also be disabled per agent via **Setup** → MCP tool toggles in the Agents editor.
**Agent design** tools (`add_skill`, `add_context`, workflow create/update/delete, `show_generative_ui`, and generative UI template create/update/delete) are registered for the agent creator and hidden from other users in live MCP. Details: [Design-mode vs live-mode tools](/user-guide/mcp-gateway/mcp-gateway-modes#design-mode-vs-live-mode-tools).
## Response Formatting
### response\_format Parameter
* `"raw"` (default): Returns exact API response
* `"formatted_md"`: Returns Markdown-formatted response (use when explicitly requested)
### response\_projection Parameter
Use JMESPath expressions to transform and reduce response size:
* **Field Selection**: `"{name: name, email: email}"`
* **Array Extraction**: `"items[*].name"`
* **Filtering**: `"items[?price > 100]"`
* **Aggregation**: `"sum(items[*].price)"`
## Error Handling
Tools return standard error responses when:
* Authentication fails
* Required parameters are missing
* Action execution fails
* Invalid operation IDs are provided
Check the error message for specific details about what went wrong.
## Next Steps
* [Workflows](/user-guide/workflows) — product guide for graphs, simulate, and approvals
* [Learn about resources](/user-guide/mcp-gateway/mcp-gateway-resources)
* [See usage examples](/user-guide/mcp-gateway/mcp-gateway-examples)
# Native MCP Servers
Source: https://docs.apigene.ai/user-guide/mcp-servers
Install and manage native MCP servers — official catalog, registry, and custom connections
## Overview
**Native MCP servers** are external Model Context Protocol servers you connect to Apigene (for example vendor MCP endpoints). They are different from **OpenAPI applications**, which Apigene turns into MCP tools automatically.
Use native MCP when you already have (or want) a remote MCP server. Use [Applications](/user-guide/applications) when you have an OpenAPI/Swagger spec or Postman collection.
After install, attach native MCP servers to [Agents](/user-guide/agents) so Co-pilot and the [MCP Gateway](/user-guide/mcp-gateway/mcp-gateway-overview) can use their tools.
Managing MCP servers is typically an **admin** capability. Availability may depend on your plan and deployment.
## Accessing MCP Servers
Open **MCP** from **Design → Build → Applications → Install Application → MCP Server**, or open the MCP dashboard URL directly.
From the MCP dashboard you can:
* Browse installed servers (search and sort)
* Install from the **official catalog** or **MCP registry**
* Create a **custom** MCP connection
* **Authorize**, **edit**, **test tools**, or **delete** a server
## Install from the official catalog
1. Go to **MCP → Official MCP Servers** (or **Install Application → MCP Server**)
2. Search by name or browse the list
3. Open vendor help links when you need auth or setup details
4. Click **Install** on the server you want
5. Complete any authorization the server requires (see [Authorize and reconnect](#authorize-and-reconnect))
Official entries typically include a display name, MCP URL, description, and optional website/help URL.
## Install from the MCP registry
1. Go to **MCP → Registry** (directory-style catalog)
2. Search and filter servers
3. Review metadata, then install into your organization
4. Authorize if the server requires OAuth or credentials
Use the registry when you need a broader directory beyond the curated official list.
## Custom MCP installation
Connect any remote MCP endpoint:
1. Go to **MCP → Custom MCP Installation** (create)
2. Enter a **name** for the server (unique in your org)
3. Enter the MCP **server URL**
4. Optionally add **HTTP headers** (for example API keys)
5. Optionally configure **OAuth** client id, secret, and scopes when the server uses OAuth
6. Save the configuration
You are returned to the MCP list when the server is created successfully.
## Authorize and reconnect
Some MCP servers require user or client authorization before tools work:
1. Open the MCP dashboard
2. Find the server and click **Authorize** when prompted
3. Complete the OAuth or credential flow in the browser
4. Use refresh/reconnect actions if tokens expire or tools fail to load
If tools stay empty after install, authorize first, then use **Test tools**.
## Login, logout, and switch OAuth account
Native MCP OAuth tokens are stored per Apigene user. Use **Login** and **Logout** on the MCP dashboard (row menu, server detail, or the @mention picker).
**Login**
1. Click **Login**
2. Complete the provider login in the popup
3. This stores **your** token for Copilot and for the MCP gateway (agents in Cursor / Claude)
**Logout / switch account**
1. Click **Logout** to clear **your** Copilot session and gateway token
2. Click **Login** and sign in with the other account
These actions do not delete the MCP server. Other users' tokens are unchanged.
API: [MCP Server Login](/api-reference/mcp-server/mcp-server-login) · [MCP Server Logout](/api-reference/mcp-server/mcp-server-logout)
## Test MCP tools
1. Open **Test tools** for an installed server
2. Review discovered tools and try sample invocations
3. Fix URL, headers, or OAuth settings if discovery fails
4. Save changes and re-test
## Attach native MCP to agents
1. Open **Agents** → select an agent → **Applications** (or MCP attachments area)
2. Add the native MCP server (not an OpenAPI→MCP bridge listed as an application)
3. Save the agent
4. Optionally restrict which gateway tools are exposed under **Setup → Enable MCP Tools**
In [Agent Builder](/user-guide/agent-builder), recommendations distinguish **APIs** (OpenAPI apps) from **installed MCP** (native servers). Prefer APIs for OpenAPI integrations; use native MCP only for real MCP endpoints.
## Native MCP vs OpenAPI applications
| | Native MCP | OpenAPI application |
| ---------------- | -------------------------------------------- | ---------------------------------- |
| Source | Remote MCP URL / catalog | OpenAPI URL, file, or Postman |
| Install UI | MCP dashboard / official / registry / custom | Applications → OpenAPI based |
| Tools | Provided by the MCP server | Generated by Apigene from the spec |
| Attach to agents | As MCP server | As application / API |
OpenAPI apps still appear as MCP tools inside Apigene and the gateway — you do not need a separate native MCP install for those.
## Related
* [Applications](/user-guide/applications) — OpenAPI and Postman installs
* [Agents](/user-guide/agents) — attach tools and MCP client setup
* [MCP Gateway](/user-guide/mcp-gateway/mcp-gateway-overview) — expose *your* agents to Claude, Cursor, and other clients
* [MCP Apps](/user-guide/mcp-apps) — UI templates for action results
* API: [MCP Server](/api-reference/mcp-server/mcp-server-create) reference
# OpenLegacy Hub
Source: https://docs.apigene.ai/user-guide/openlegacy
Connect OpenLegacy Hub, install Hub projects as applications, and build Hub-ready agents
## Overview
**OpenLegacy Hub** connects your organization to Hub so Copilot can use Hub projects as applications and Agent Builder can design agents around those contracts.
After you enable Hub for the organization, you can:
* Install a Hub project's OpenAPI as an [application](/user-guide/applications)
* Include Hub projects in [Agent Builder](/user-guide/agent-builder) app scope and use-case proposals
* Create agents that call Hub test flows through a provisioned skill
Hub integration is organization-wide. You need permission to edit **Settings → Organization**.
## Connect OpenLegacy Hub
1. Go to **Settings → Organization → Open Legacy**
2. Enable **Enable OpenLegacy**
3. Enter the **OpenLegacy Hub Server URL** (must start with `http://` or `https://`, e.g. `https://api.ol-hub.com/backend`)
4. Choose **Authentication**:
* **API Key** — sent as the `x-api-key` header
* **Bearer token** — sent as `Authorization: Bearer` (JWT from Hub)
5. Enter the matching credential
6. Click **Test connection** to verify the URL and credential (unsaved form values are fine; a last-4 stored secret is reused)
7. Optionally enable **Use in Agent Builder** so Hub projects appear in the Agent Builder Apps picker
8. Save organization settings
Stored credentials are shown as the last 4 characters. Enter a new value to replace them.
Stored as `openlegacy` on the organization (`enabled`, `agent_builder_enabled`, `hub_server_url`, `auth_type`, `api_key`).
See also [Settings → Open Legacy](/user-guide/settings#open-legacy).
## Install a Hub project as an application
Use this when you want the project's OpenAPI available like any other app (operations, security, Copilot tools).
1. Connect Hub as above, including **Use in Agent Builder**
2. Go to **Applications → + Install Application**
3. Choose **OpenAPI based** if prompted, then select **OpenLegacy Hub**
4. Search and select a Hub project (method count and last updated appear on each row)
5. Click **Install**
Already-installed projects show an **Installed** badge. Click **Open** to go to that application.
Installation fetches the project's OpenAPI from Hub, then runs the same index and metadata flow as a normal spec import. Configure [Security](/user-guide/applications#security-configuration) on the new application before making live calls.
Installing an application requires at least one model provider configured for the organization. If install is blocked, complete [Settings → AI Models](/user-guide/settings) first.
The **OpenLegacy Hub** install card appears only when Hub is enabled, reachable, and available for Agent Builder.
## Build an agent from Hub projects
1. Enable **Use in Agent Builder** in organization Open Legacy settings
2. Open **Agent Builder** and pick Hub projects in the Apps picker (selecting a project includes contract methods as read-only context)
3. Ask for use cases, or describe the agent you want
4. Review the **use case proposals** card, then **Build**
When a use case includes Hub projects, Agent Builder:
* Attaches the **ol-hub** OpenAPI application so the agent can call Hub actions
* Provisions (creates or updates) a project-scoped skill named like `ol-hub-{project}` with baked contract, method, and flow IDs
* Instructs the agent to run Hub **test flows** from that skill instead of discovering projects and methods on every turn
You can inspect the provisioned skill later under [Skills](/user-guide/skills) and the agent under [Agents](/user-guide/agents).
## Troubleshooting
### I do not see OpenLegacy Hub on the install page
* Confirm **Enable OpenLegacy** and **Use in Agent Builder** are on, then save
* Confirm **Test connection** succeeds
* Refresh **Applications → Install Application**
### Test connection fails
* Check the Hub Server URL (include the Hub backend path, e.g. `/backend`)
* Confirm **API Key** vs **Bearer token** matches how your Hub tenant authenticates
* Replace a last-4 stored secret with the full credential if you recently rotated it
### Agent Builder does not list Hub projects
* **Use in Agent Builder** must be enabled
* Hub must be reachable (use **Test connection**)
* Start a new Agent Builder thread and open the Apps picker again
### The agent cannot run Hub test flows
* Confirm the agent has the **ol-hub** application attached
* Open the provisioned `ol-hub-…` skill and confirm it lists method and flow IDs
* Configure security on **ol-hub** (and on any installed Hub project apps) so live calls can authenticate
## Next steps
* [Applications](/user-guide/applications) — install Hub OpenAPI and configure security
* [Agent Builder](/user-guide/agent-builder) — create agents from Hub use cases
* [Skills](/user-guide/skills) — review provisioned Hub skills
* [Settings](/user-guide/settings#open-legacy) — Hub URL, auth type, and test connection
# Settings
Source: https://docs.apigene.ai/user-guide/settings
Configure your workspace, preferences, and integrations
## Overview
Settings is your central hub for configuring Apigene Copilot. Here you can manage workspace preferences, user settings, API configurations, and system-level options to tailor the platform to your needs.
![Settings Organization tab with AI provider configuration]()
## Accessing Settings
Open **Settings** from the sidebar. In **Live**, Settings opens on the **Personal** tab. In **Design**, it opens organization settings (admins). You can also use the user profile dropdown.
## Settings Categories
### User Settings
Personal preferences and account information.
**Profile Information**
* Display name
* Email address
* Profile picture
* User role and permissions
**Preferences**
* Default AI model preference
* Theme (light/dark mode)
* **Language** — UI locale stored on your user (**Settings → Personal → Language**): English, Español, Deutsch, Français, Português (Brasil), 日本語, עברית
* Notification settings
**Chat**
* **Follow-up suggestions** — after each reply, show short clickable prompts to continue the conversation (off by default)
**Commands**
* Personal saved prompts inserted with `/` in chat
* Optionally bind a command to an agent
* Add, edit, or delete from Settings, or save from chat with the bookmark button
**Keyboard Shortcuts**
* View available shortcuts
* Customize key bindings
* Enable/disable shortcuts
* Quick reference guide
### Workspace Settings
Organization-level configurations.
**General**
* Workspace name
* Workspace ID
* Default settings for new users
* Feature access control
**Interaction Recording**
* Control what request/response data is stored in [Actions](/user-guide/actions) history
* Modes: **Full recording**, **Headers only**, or **Disabled** (see below)
**Workflow Recording**
* Control what workflow run data is stored in [Workflow History](/user-guide/workflow-history)
* Modes: **Full recording**, **Headers only**, or **Disabled** (HITL checkpoints still kept for resume)
**Billing & Usage**
* Current plan details
* Usage statistics
* Billing information
* Upgrade options
**Team Management**
* Add/remove users
* Assign roles
* Permission levels
* Access control
### Application Settings
Configure installed applications and integrations.
**Installed Applications**
* View all applications
* Quick access to configuration
* Security status overview
* Usage statistics per app
**Default Configurations**
* Default tool selection mode
* Application access policies
* Common parameters
* Rate limiting preferences
**API Keys Management**
* View configured API keys
* Add new API keys
* Rotate credentials
* Test connections
### AI Model Settings
Configure AI model preferences and access.
**Model Providers**
* OpenAI configuration
* Anthropic configuration
* Google AI configuration
* xAI configuration
* OpenRouter configuration
* Amazon Bedrock (IAM access key, secret, region)
* Microsoft Foundry (Azure OpenAI — service principal or API key, deployments)
* Exa (web search / content tools)
**Model visibility and custom models**
* Per provider, open **Models** to show or hide individual models in Copilot pickers
* Supported for OpenAI, Anthropic, Google, xAI, **OpenRouter**, and **Amazon Bedrock**
* **OpenRouter** and **Bedrock** load the available model list from your configured credentials (live catalog); toggle models on or off or use **Enable all** / **Disable all**
* Add a custom **model ID** when your provider offers a model that is not in the default list (static-catalog providers)
* The built-in catalog includes GPT-6, Claude Opus 5.5 / Fable 5.1 / Sonnet 5, Grok 4.7, and Gemini 3.8 Flash (plus earlier models). Hide models you do not want in Copilot pickers
* Remove custom models you no longer need; built-in models can only be disabled, not deleted
**Extra HTTP headers**
* On each model provider, expand **Extra headers** to send additional request headers on every call (for example Anthropic `anthropic-workspace-id`)
* Empty names are ignored; headers are stored with the provider config and applied in Copilot
**Reasoning Effort**
* Organization-wide setting for how much supported models think before answering
* Options: None, Low, Medium, High
* Affects Copilot Chat reasoning panels for compatible models
**Mock Execution** (Advanced)
* Return mock API responses from OpenAPI spec examples instead of calling real APIs
* Optional **LLM-generated mocks** for realistic placeholder data when examples are missing
* Useful for demos and development without live credentials
**Interaction Recording**
* Organization setting under Settings → Organization
* Controls whether Actions history stores full payloads, headers only, or nothing
**Workflow Recording**
* Organization setting under Settings → Organization
* Controls whether Workflow History stores full run payloads, metadata only, or nothing (except HITL resume checkpoints)
**API Keys**
* Add provider API keys
* Test key validity
* Set key priorities
* Manage key usage
* Organization members can use configured models in Copilot (model credentials are available to members; Hub and Agent Marketplace tokens stay admin-only)
**Default Models**
* Set default model for Copilot
* Configure model fallbacks
* Set model per use case
* Cost optimization preferences
### Interaction Recording (Organization)
Admins control how much of each API/MCP call is persisted for the [Actions](/user-guide/actions) page:
| Mode | What is stored |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| **Full recording** (default) | Complete request and response bodies |
| **Headers only** | Headers and payload sizes; bodies are not persisted (shown as redacted in Actions) |
| **Disabled** | No new interaction records; Actions will not show new entries |
Configure under **Settings → Organization → Interaction Recording**. Changes apply to new interactions going forward.
### Workflow Recording (Organization)
Admins control how much of each workflow run is persisted for the [Workflow History](/user-guide/workflow-history) page:
| Mode | What is stored |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| **Full recording** (default) | Inputs, step traces, and result |
| **Headers only** | Metadata and payload sizes; bodies are redacted in Workflow History |
| **Disabled** | No new history rows, except HITL approval checkpoints required to resume waiting runs |
Configure under **Settings → Organization → Workflow Recording**. Dry runs are never persisted. Changes apply to new runs going forward.
### Organization Advanced Settings
Under **Settings → Organization** (Advanced), admins can also configure:
**Response Size Control**
* Set a maximum response size (bytes)
* **Alert Only** — log when responses exceed the limit
* **Auto Truncate** — truncate oversized responses (with guidance for agents)
* Other modes may include signaling the agent when limits are hit
**Interaction Caching**
* Enable Redis-backed caching of API responses
* Configure TTL (seconds) and whether GET, POST, or both are cached
**JSON Compression**
* Compress large JSON payloads before they reach the model
* Modes such as **json-compact** or **TOON** (see [toonformat.dev](https://toonformat.dev) for TOON)
**PII Sanitization**
* Enable masking of sensitive entities before data is shown to the model
* Configure patterns / entity types in the PII settings modal
**Mock Execution**
* Return mock responses from OpenAPI examples instead of calling live APIs
* Optional LLM-generated mocks when examples are missing
**Outbound network**
* Optional HTTP proxy URL for all outbound integration and action API calls (corporate egress)
**Reasoning Effort**
* Organization-wide None / Low / Medium / High for supported models
**Model comparison**
* Opt-in **Compare** control in Copilot chat (two models side by side). Off by default because each comparison doubles token spend and may run tools twice
### Branding (Organization)
Admins can white-label the product UI under **Settings → Branding**:
* **Product Name** — display name shown in the UI
* **Product Icon** — favicon / product mark
* **Sidebar Logo** — logo in the navigation shell
Save branding to apply across the organization. Clear fields to fall back to defaults.
### Security Settings
Manage authentication and security policies.
**Authentication**
* Single Sign-On (SSO) setup
* Multi-factor authentication
* Session timeout settings
* Password policies
**Access Control**
* Role-based access control (RBAC)
* Permission matrices
* Resource access policies
* API access restrictions
**Audit & Compliance**
* Audit log retention
* Compliance certifications
* Data residency preferences
* Export settings
### Integration Settings
Connect external services and tools.
**Webhooks**
* Configure webhook endpoints
* Event subscriptions
* Webhook security
* Test webhook delivery
**External Services**
* Connect collaboration tools
* Integration with CI/CD
* Monitoring services
* Analytics platforms
**Data Export**
* Export formats
* Scheduled exports
* Destination configuration
* Data retention policies
## Common Configuration Tasks
### Enable Follow-up Suggestions
1. Open **Settings → Personal → Chat**
2. Turn on **Follow-up suggestions**
3. Save your personal settings
4. In Copilot Chat, look for **Continue with** chips under the latest assistant reply
### Manage Commands
1. Open **Settings → Personal → Commands** to add, edit, or delete saved prompts
2. Or in chat, click the **bookmark** on the prompt input to **Save command**
3. Type `/` in chat to insert a command (optionally with a bound agent)
### Configure Interaction Recording
1. Open **Settings → Organization**
2. Find **Interaction Recording**
3. Choose **Full recording**, **Headers only**, or **Disabled**
4. Save organization settings
Use **Headers only** or **Disabled** when you need to reduce stored sensitive payloads in Actions history.
### Configure Workflow Recording
1. Open **Settings → Organization**
2. Find **Workflow Recording**
3. Choose **Full recording**, **Headers only**, or **Disabled**
4. Save organization settings
Use **Headers only** or **Disabled** when you need to reduce stored sensitive payloads in Workflow History. Approval waits still keep the checkpoint needed to resume.
### Configure Advanced Performance and Privacy Controls
1. Open **Settings → Organization**
2. Expand **Advanced** settings
3. Adjust **Response Size Control**, **Interaction Caching**, **JSON Compression**, **PII Sanitization**, and **Mock Execution** as needed
4. Save
### Update Branding
1. Open **Settings → Branding**
2. Set product name, icon, and sidebar logo
3. Save
### Platform administration pages
Admins may also see:
* **Platform Version** — deployed image / version information for the environment
* **Platform Test** — run built-in health and API smoke checks against the deployment
Use these when validating upgrades or diagnosing environment issues. They complement [Insights](/user-guide/insights) rather than replacing them.
### Adding API Keys for Model Providers
Enable AI models by adding provider API keys:
**OpenAI**
1. Navigate to Settings > AI Models
2. Find OpenAI section
3. Click "Add API Key"
4. Paste your OpenAI API key
5. Click "Save" and "Test Connection"
**Anthropic**
1. Navigate to Settings > AI Models
2. Find Anthropic section
3. Click "Add API Key"
4. Paste your Anthropic API key
5. Select available models
6. Click "Save"
**Google AI**
1. Navigate to Settings > Organization > Model Settings
2. Find Google AI section
3. Click "Add API Key"
4. Paste your Google AI API key
5. Configure model access
6. Click "Save"
**Amazon Bedrock**
1. Navigate to Settings > Organization > Model Settings
2. Find **Amazon Bedrock**
3. Enter IAM **Access Key ID**, **Secret Access Key**, and **Region** (or a Bedrock API key where supported)
4. Save and test — available models are loaded from your AWS account
5. Open **Models** to enable or disable individual Bedrock models in the Copilot selector
**OpenRouter**
1. Navigate to Settings > Organization > Model Settings
2. Find **OpenRouter**
3. Add your OpenRouter API key and save
4. Open **Models** to enable or disable models from the built-in catalog and your live OpenRouter account list
**Microsoft Foundry**
1. Navigate to Settings > Organization > Model Settings
2. Find **Microsoft Foundry** (Azure OpenAI)
3. Configure authentication (service principal or API key) and add deployments
4. Each deployment maps to a model name shown in Copilot
**Extra HTTP headers**
1. Open the provider card under Settings → Organization → Model Settings
2. Expand **Extra headers**
3. Add header name and value pairs (for example `anthropic-workspace-id` on Anthropic)
4. Save — Copilot sends these headers on every request to that provider
**Exa (Web Search)**
1. Navigate to Settings > Organization > Model Settings
2. Find **Exa (Web Search)**
3. Add your Exa API key
4. Save — Copilot web search and related content tools use Exa when configured
### Model visibility and custom models
Control which models appear in Copilot for your organization:
1. Settings → Organization → Model Settings
2. Open a configured provider
3. Click **Models (N/M enabled)**
4. Toggle models on or off for the org model selector (use **Enable all** or **Disable all** when available)
5. For OpenAI, Anthropic, Google, and xAI, optionally type a **model ID** and add it as a custom model
6. Save organization settings
Disabled models stay configured on the provider but are hidden from users. Custom model IDs are useful when a provider releases a new model before Apigene updates the default catalog. **OpenRouter** and **Bedrock** use dynamically fetched catalogs — you enable or disable models from the list returned for your credentials rather than adding custom IDs.
### Reasoning Effort
Control extended thinking for supported models:
1. Settings → Organization → Model Settings
2. Find **Reasoning Effort**
3. Choose **None** (fastest), **Low**, **Medium**, or **High**
4. Save organization settings
Higher effort may improve complex answers but increases latency and cost.
### Model comparison
Let users run the same prompt against two models in Copilot:
1. Settings → Organization → **Advanced** → **Model comparison**
2. Enable **Model comparison**
3. Save organization settings
When it is on, Copilot shows **Compare** on the chat composer. Pick a second model, send, continue the thread as needed, then conclude to generate a review. Stored as `model_comparison.enabled` on the organization (default off).
### Change UI language
1. Open **Settings → Personal → Language**
2. Choose a locale (English, Español, Deutsch, Français, Português (Brasil), 日本語, עברית)
3. The UI reloads in that language. Hebrew uses a right-to-left layout
The choice is stored on your user (`language`) and synced across browsers. Auto-generated chat thread titles use the selected language.
### Mock Execution Mode
For development and demos without live API credentials:
1. Settings → Organization → Advanced (or Model Settings accordion)
2. Enable **Mock Execution Mode** — returns OpenAPI example responses instead of real API calls
3. Optionally enable **LLM-generated mocks** for realistic values when examples are absent
4. Save — Copilot uses mocks for application actions until you disable the setting
### Outbound HTTP proxy
For corporate or locked-down networks, route outbound integration and action API calls through an HTTP proxy:
1. Settings → Organization → **Outbound network**
2. Enter an **HTTP proxy URL** (must start with `http://` or `https://`, e.g. `https://proxy.corp.example.com:8080`)
3. Save organization settings
Apigene uses this proxy for all outbound HTTP/HTTPS requests when calling third-party APIs from integrations and actions. Clear the field and save to return to direct egress. Stored as `proxy_server_url` on the organization.
### Open Legacy
Connect the organization to OpenLegacy Hub. After Hub is connected you can [install Hub projects as applications](/user-guide/openlegacy#install-a-hub-project-as-an-application) and [build Hub-ready agents](/user-guide/openlegacy#build-an-agent-from-hub-projects).
1. Settings → Organization → **Open Legacy**
2. Enable **Enable OpenLegacy** and enter the **OpenLegacy Hub Server URL** (must start with `http://` or `https://`, e.g. `https://api.ol-hub.com/backend`)
3. Choose **Authentication**: **API Key** (`x-api-key` header) or **Bearer token** (`Authorization: Bearer`)
4. Enter the matching **API Key** or **Bearer Token**
5. Click **Test connection** to verify the URL and credential (unsaved values are used; last-4 credentials reuse the stored secret)
6. Optionally enable **Use in Agent Builder** to show Hub projects in the Agent Builder Apps picker (selecting a project includes all contract methods as read-only context)
7. Save organization settings
Stored credentials are shown as the last 4 characters. Enter a new value to replace them. Stored as `openlegacy` on the organization (`enabled`, `agent_builder_enabled`, `hub_server_url`, `auth_type`, `api_key`).
Full walkthrough: [OpenLegacy Hub](/user-guide/openlegacy).
### Agent Marketplace
Point the Agent Marketplace on **Agents** at a private GitHub marketplace repo (Claude plugin layout, e.g. `apigene/apigene-industry-marketplace`).
1. Settings → Organization → **Agent Marketplace**
2. Enable **Enable Agent Marketplace**
3. Enter the **GitHub repository** as `owner/name` or a `https://github.com/owner/name` URL
4. Set the **Branch or ref** (default `main`)
5. Enter a GitHub personal access token with read access to that private repo (`contents:read` or classic `repo`)
6. Click **Test connection** to confirm `marketplace.json` is readable (uses the token in the form; after save only last 4 characters remain and Test is disabled until you paste a new token)
7. Save organization settings
Stored tokens are shown as the last 4 characters. Enter a new value to replace them. Stored as `industry_marketplace` on the organization (`enabled`, `repo`, `ref`, `token`). The token never appears in gallery API responses — Copilot reads files through the backend.
A local `INDUSTRY_MARKETPLACE_PATH` env var still overrides this for development.
### Authentication Providers (Self-Hosted)
Apigene Copilot supports multiple auth backends via `NEXT_PUBLIC_AUTH_PROVIDER`:
| Provider | Use case |
| ------------ | --------------------------------------- |
| **clerk** | Default SaaS authentication |
| **apigene** | Apigene-native basic auth (self-hosted) |
| **keycloak** | Enterprise SSO via Keycloak |
Configure the matching environment variables in your deployment. Contact your administrator for sign-in URLs and client setup.
### OnPrem license (Self-Hosted)
Self-hosted installs start on a trial. When Apigene provides a signed license token:
1. Settings → Organization
2. Copy your **organization ID** if Apigene asks for it when issuing the license
3. Paste the token under **Apply license token**
4. Click **Apply license**
A valid token ends the trial for that organization. You can paste a new token later to renew or replace the current license. API equivalent: [`POST /api/org/apply_license`](/api-reference/org/org-apply-license).
### Configuring Application Defaults
Set default behaviors for application usage:
**Tool Choice Default**
1. Settings > Application Settings
2. Find "Default Tool Choice"
3. Select: Auto / Required / None
4. Apply to all users or per-user
**Application Access**
1. Settings > Application Settings
2. Configure default application access
3. Set restrictions if needed
4. Save preferences
### Managing User Access
Add or remove team members:
**Add User**
1. Settings > Team Management
2. Click "Invite User"
3. Enter email address
4. Select role (Admin, User, Viewer)
5. Send invitation
**Remove User**
1. Settings > Team Management
2. Find user in list
3. Click "Remove"
4. Confirm removal
5. User access revoked immediately
**Change User Role**
1. Settings > Team Management
2. Find user in list
3. Click "Edit Role"
4. Select new role
5. Save changes
### Configuring Notifications
Control how you receive notifications:
**Email Notifications**
* System alerts
* Usage reports
* Security notifications
* Team activity updates
**In-App Notifications**
* Real-time updates
* Action completions
* Error alerts
* Collaboration notifications
**Notification Preferences**
1. Settings > User Settings > Notifications
2. Toggle notification types
3. Set frequency (real-time, daily digest, weekly)
4. Choose channels (email, in-app, both)
5. Save preferences
## Advanced Settings
### Custom Model Endpoints
Configure custom or self-hosted models:
**Setup**
1. Settings > AI Models > Custom Endpoints
2. Click "Add Custom Endpoint"
3. Enter endpoint URL
4. Configure authentication
5. Set model parameters
6. Test connection
7. Save configuration
**Use Cases**
* Self-hosted models
* Organization-specific models
* Compliance requirements
* Cost optimization
### Rate Limiting
Configure rate limits for API usage:
**Application Rate Limits**
1. Settings > Application Settings
2. Select application
3. Set requests per minute/hour/day
4. Configure burst limits
5. Set user-specific limits
6. Save configuration
**Model Rate Limits**
1. Settings > AI Models
2. Configure tokens per request
3. Set concurrent request limits
4. Define cooldown periods
5. Apply limits
### Webhook Configuration
Set up webhooks for event notifications:
**Create Webhook**
1. Settings > Integrations > Webhooks
2. Click "Add Webhook"
3. Enter endpoint URL
4. Select events to subscribe
5. Configure security (signing secret)
6. Test webhook
7. Save and activate
**Webhook Events**
* Action completed
* Error occurred
* User activity
* System updates
* Configuration changes
### Data Retention Policies
Configure how long data is retained:
**Action Logs**
1. Settings > Security > Data Retention
2. Set retention period (30-365 days)
3. Configure automatic cleanup
4. Set archival rules
5. Save policy
**Chat History**
1. Configure retention duration
2. Set archival preferences
3. Define deletion policies
4. Enable/disable exports before deletion
## Security Best Practices
### API Key Management
**Best Practices**
* Rotate keys regularly (quarterly)
* Use different keys for dev/prod
* Never share keys publicly
* Revoke compromised keys immediately
* Use environment-specific keys
**Key Rotation**
1. Generate new key with provider
2. Add new key to Settings
3. Test new key works
4. Remove old key
5. Update documentation
### Access Control
**Principle of Least Privilege**
* Grant minimum necessary permissions
* Regular access reviews
* Remove access when no longer needed
* Use role-based access control
* Document access policies
**User Roles**
* **Admin**: Full system access
* **User**: Standard usage access
* **Viewer**: Read-only access
* **Custom**: Tailored permissions
### Audit Trail
**Enable Comprehensive Logging**
1. Settings > Security > Audit Logs
2. Enable all log categories
3. Set appropriate retention
4. Configure log exports
5. Review logs regularly
**What to Monitor**
* Configuration changes
* User access patterns
* Failed authentication attempts
* Unusual API usage
* Data exports
## Troubleshooting Settings
### Can't Save Settings
**Possible Causes**
* Insufficient permissions
* Invalid configuration values
* Network connectivity issues
* Concurrent modifications
**Solutions**
1. Verify you have admin access
2. Check all required fields
3. Validate input formats
4. Refresh page and retry
5. Contact support if persists
### API Keys Not Working
**OpenAI Key Invalid**
* Verify key is correct (starts with sk-)
* Check key hasn't expired
* Verify account has credits
* Test key with OpenAI directly
**Anthropic Key Invalid**
* Verify key format
* Check API access enabled
* Verify model access permissions
* Test with Anthropic console
**General Troubleshooting**
1. Copy key again from provider
2. Remove spaces or extra characters
3. Test connection button
4. Check provider status page
5. Generate new key if needed
### Application Configuration Issues
**Application Not Responding**
* Verify credentials are current
* Check API service status
* Test with simple operation
* Review error messages
* Reconfigure if needed
**Permission Errors**
* Review granted scopes
* Check account permissions
* Verify API access level
* Contact service provider
### Notification Issues
**Not Receiving Notifications**
* Check email spam folder
* Verify email address is correct
* Check notification preferences enabled
* Verify account email is verified
* Test with a trigger event
**Too Many Notifications**
* Adjust notification frequency
* Disable non-critical alerts
* Set daily/weekly digests
* Configure filters
* Customize per-notification type
## Settings Import/Export
### Export Configuration
Save your settings for backup or migration:
**Export Steps**
1. Settings > Advanced > Export
2. Select what to export:
* User preferences
* Application configurations
* Team settings
* Integration settings
3. Choose format (JSON, YAML)
4. Click "Export"
5. Save file securely
**Use Cases**
* Backup before changes
* Migrate to new workspace
* Share configurations with team
* Disaster recovery
### Import Configuration
Restore or apply saved settings:
**Import Steps**
1. Settings > Advanced > Import
2. Click "Choose File"
3. Select configuration file
4. Review changes to be applied
5. Confirm import
6. Verify settings applied correctly
**Cautions**
* Review before importing
* Backup current settings first
* Test in non-production first
* Some settings may need adjustment
## Workspace Administration
### Organization Settings
**Organization Profile**
* Organization name
* Primary domain
* Industry/sector
* Company size
* Contact information
**Branding**
* Logo upload
* Color scheme
* Custom domain (if supported)
* Email templates customization
**Compliance**
* Data residency preferences
* Compliance certifications needed
* Privacy policy acceptance
* Terms of service
### Resource Limits
**Usage Limits**
* API calls per month
* Storage capacity
* Number of users
* Number of applications
* Concurrent sessions
**Monitoring**
1. Settings > Workspace > Usage
2. View current usage
3. Check against limits
4. Plan upgrades if needed
5. Set usage alerts
### Feature Flags
Control access to beta or advanced features:
**Enable Features**
1. Settings > Advanced > Feature Flags
2. View available features
3. Toggle features on/off
4. Apply to users/teams
5. Monitor feature usage
**Common Features**
* Beta features preview
* Advanced analytics
* Custom integrations
* Experimental AI models
* Performance optimizations
## Best Practices
### Regular Maintenance
**Weekly Tasks**
* Review failed actions
* Check API key status
* Monitor usage metrics
* Review user activity
* Test critical integrations
**Monthly Tasks**
* Rotate sensitive credentials
* Review and update settings
* Audit user access
* Clean up unused integrations
* Review and optimize costs
**Quarterly Tasks**
* Comprehensive security audit
* Review all application configurations
* Update team documentation
* Evaluate new features
* Plan capacity adjustments
### Documentation
**Document Your Configuration**
* Settings rationale
* Custom configurations
* Integration details
* Access policies
* Troubleshooting guides
**Share with Team**
* Onboarding documentation
* Configuration standards
* Best practices guide
* Emergency procedures
* Contact information
## Next Steps
* [Configure applications](/user-guide/applications) for use in Copilot
* [Set up agents](/user-guide/agents) with proper tool access
* [Monitor usage](/user-guide/insights) to optimize settings
* [Review audit logs](/user-guide/audit) for security
# Skills
Source: https://docs.apigene.ai/user-guide/skills
Reusable instruction sets that extend agent capabilities
## Overview
**Skills** are reusable instruction packages that teach agents how to handle specific tasks consistently. They follow the [Agent Skills specification](https://agentskills.io/specification) — a `SKILL.md` file with YAML frontmatter and a Markdown body.
Skills live in your **organization library**. Attach them to agents so the same workflows, checklists, and domain knowledge apply everywhere that agent runs — in Copilot Chat, Agent Builder, and via [MCP Gateway](/user-guide/mcp-gateway/mcp-gateway-overview).
![Skill Management page listing organization skills]()
## Why use skills
* **Reuse** — write once, attach to many agents
* **Consistency** — standardized procedures (PR review, SEO audits, deploy runbooks)
* **Discoverability** — browse your library or install from the public registry
* **Compatibility** — Agent Skills format works across Apigene and external MCP clients
## Accessing Skills
In the **Design** workspace, open **Build → Skills**.
## Creating skills
### Upload a skill
1. Click **Upload Skill**
2. Choose a tab:
* **Upload** — drop or select a `SKILL.md` file, or a `.zip` of a skill folder (`SKILL.md` at the zip root or in a wrapper folder such as `ol-deck/SKILL.md`, plus optional `scripts/`, `references/`, `assets/`)
* **GitHub** — import from a public GitHub repository URL
3. Review validation results and save
Skills must follow the Agent Skills spec: valid `name` and `description` in frontmatter, with procedural content in the Markdown body.
### Generate with AI
Use **Generate Skill** to draft a `SKILL.md` from a short description. Edit the result before saving.
### Browse the registry
Click **Browse Skills** to search [skills.sh](https://skills.sh) — the public skill registry:
* Search by keyword or use case
* View install counts and source
* Install into your org library with one click
* Already-installed skills show an **Installed** badge
Installed registry skills become org skills you can attach to agents.
## Managing skills
The Skills table lists all org skills with:
* **Name** and **description** (from frontmatter)
* **Search** and **sort** for large libraries
* **Edit** — update instructions and optional files
* **Download** — export the skill’s `SKILL.md` content as a Markdown file
* **Delete** — remove from the org library (does not remove from agents until you detach)
Open a skill to view full `SKILL.md` content, metadata, and packaged files.
## Attaching skills to agents
### From the Agents editor
1. Open **Agents** → select an agent → **Skills** tab
2. Add skills from your org library
3. Save the agent
### From Agent Builder
When building an agent in [Agent Builder](/user-guide/agent-builder), Copilot can:
1. Search your org library and the registry
2. Show a **skill proposals** card with recommended matches
3. Wait for you to install or select skills before calling `create_agent`
See [Agent Builder](/user-guide/agent-builder) for the full creation workflow.
When you build an agent from [OpenLegacy Hub](/user-guide/openlegacy) projects, Agent Builder also **provisions** a project-scoped org skill (name like `ol-hub-{project}`) with Hub contract, method, and flow IDs. That skill is created or updated automatically — you do not upload it yourself.
## How agents use skills at runtime
In Chat and MCP Gateway **Agent mode**, the model:
1. Calls `list_skills` to discover attached skills (metadata only)
2. Calls `get_skill_content` for relevant skills before following their procedures
Skills are **not** fully loaded from summaries alone — the agent must fetch the full `SKILL.md` before applying a skill.
## Skill structure
A minimal skill:
```markdown theme={null}
---
name: code-review
description: Review pull requests for bugs, style, and security. Use when the user asks for a PR or code review.
---
# Code Review
## Steps
1. Read the diff summary
2. Check for security issues
3. Suggest concrete improvements
```
Put long reference material in `references/` files and link from the body (progressive disclosure).
## Best practices
**Write trigger-rich descriptions**
* The `description` in frontmatter is how the model decides *when* to activate the skill — include use cases and triggers there, not only in the body
**Keep SKILL.md focused**
* Core workflow in the body; detailed docs in `references/`
**Prefer org skills for team standards**
* Install registry skills for common patterns, then customize copies for your org
**Attach sparingly**
* A few well-chosen skills per agent beats attaching everything
## Skills vs Context
| | **Skills** | **Context** |
| ----------- | ----------------------------------- | ---------------------------------- |
| **Format** | `SKILL.md` (Agent Skills spec) | Free-form instructions / knowledge |
| **Purpose** | Procedures and workflows | Background facts and policies |
| **Runtime** | `list_skills` → `get_skill_content` | `list_contexts` → `get_context` |
Use both when an agent needs *how to work* (skills) and *what to know* (context).
## Troubleshooting
### Skill validation failed on upload
* Check frontmatter: `name` (lowercase, hyphens) and `description` (includes when-to-use triggers)
* Ensure the file is valid Markdown
### Agent ignores a skill
* Confirm the skill is attached on the agent **Skills** tab
* Make the description more specific about when to use the skill
* In Chat, ensure the agent (with skills attached) is selected via `@`
### Registry install failed
* Verify network access to the registry
* Try importing via **GitHub** if the skill is hosted in a public repo
## Next steps
* [Agent Builder](/user-guide/agent-builder) — create agents with skill proposals
* [Agents](/user-guide/agents) — attach skills and configure behavior
* [MCP Gateway Tools](/user-guide/mcp-gateway/mcp-gateway-tools) — `list_skills`, `get_skill_content`, `add_skill` in Agent mode
# Tasks
Source: https://docs.apigene.ai/user-guide/tasks
Schedule and run saved prompts from Copilot
## Overview
**Tasks** are saved prompts you can run on demand or on a schedule. Each task stores a prompt, a chat model, an optional agent, and a schedule (manual, daily, or weekly).
Use Tasks when you want the same instruction to run repeatedly — for example a morning standup digest, a weekly status check, or a reusable slash command in chat.
Tasks are different from [Workflows](/user-guide/workflows) (deterministic multi-step graphs) and [Skills](/user-guide/skills) (reusable instruction packages for agents).
## Accessing Tasks
1. Open Apigene Copilot in the **Live** workspace
2. Click **Tasks** in the sidebar (available to org admins and non-member roles that can manage tasks)
You can also manage tasks from chat: type `/` in the composer to open the Tasks picker.
## Create a task
1. Go to **Tasks**
2. Click **Create New Task** (or **Create Your First Task** when the list is empty)
3. Fill in the form:
* **Name** — unique for your account; spaces become hyphens
* **Prompt** — the message that runs when the task executes
* **Model** — chat model used for the run (required)
* **Also attach agent** (optional) — bind an agent so runs use that agent's tools and instructions
* **Frequency** — **Manual**, **Daily** (time in UTC), or **Weekly** (day + time in UTC)
* **Continue in same chat** — append to one thread across runs, or start a new chat each run
4. Click **Save**
From chat, open the `/` Tasks picker and choose **Add new task** to use the same form.
## Edit, pause, and run
| Action | How |
| ------------------ | ---------------------------------------------------------- |
| **Edit** | Click the row or use **Edit** in the row menu |
| **Pause / Resume** | Use the pause control on the row (Active ↔ Paused) |
| **Run now** | Row menu → **Run now** — queues the task in the background |
| **Delete** | Row menu → **Delete** |
After **Run now**, Apigene queues the execution and shows toast feedback. When the run finishes, results appear as a chat thread (open from the toast when offered). The table shows a **Last run** status when available.
Schedule times are always in **UTC**. Convert from your local timezone when setting Daily or Weekly runs.
## Using tasks in chat
1. In Copilot chat, type `/`
2. Pick a task from the list
3. The prompt (and attached agent, if any) is applied to the composer so you can send or edit it
This is useful for prompts you reuse often without opening the Tasks page.
## Good to know
* Task names must be **unique** for your user (case-insensitive)
* Visibility is private to you in the current Tasks UI
* Concurrent **Run now** on the same task may be rejected while a run is already queued or in progress
* Scheduled and manual runs use the model saved on the task
## Related
* [Workflows](/user-guide/workflows) — multi-step agent graphs with simulate and approvals
* [Agents](/user-guide/agents) — attach an agent to a task for tool access
* [Copilot](/user-guide/copilot) — chat experience where `/` tasks live
* [Task API](/api-reference/task/task-list) — REST endpoints for automation
# Workflow History
Source: https://docs.apigene.ai/user-guide/workflow-history
Monitor, inspect, and replay past agent workflow runs
## Overview
**Workflow History** is the run log for agent workflows — similar to [Actions](/user-guide/actions) for individual API calls. Every real (non-dry-run) execution with a workflow id is stored so you can filter, share, inspect inputs/steps/result, and replay the path on the graph.
How much payload is stored depends on your organization's **Workflow Recording** policy. See [Settings](/user-guide/settings#workflow-recording-organization).
## Accessing Workflow History
In the **Design** workspace, open **Monitor → Workflows**.
## List view
Each row typically shows:
* **User** who started the run
* **Agent** and **workflow** display names
* **When** it ran (Local or GMT toggle)
* **Duration**
* **Status** (icon: succeeded, failed, waiting for approval/auth, and other)
* Approximate **payload size** when recording includes sizes
### Search and filters
* Search by run id, workflow name, agent, or user
* Filter by status and date range
* **Last 7 days** activity chart — click and drag to apply a time range; **Clear** removes the brush selection
## Run details
Open a run to see:
* Summary badges (agent, workflow, user, status, duration, time, and redaction flags when applicable)
* **Copy ID** / **Share** / **Simulation** / **Help** (node types and expressions)
* **Inputs** and **Output** (Steps / Result tabs) when Simulation is off
Simulation opens by default when the run has a resolvable workflow graph. Toggle **Simulation** off to return to the JSON inputs/output layout.
### Simulation replay
Play, pause, and scrub **waves** to walk recorded step statuses on the workflow graph — the same visual language as dry-run simulation on the agent Workflows tab, driven by the stored run traces.
### Share
**Share** copies a link to `/workflow-history/share/{run_id}`. Recipients in your org (with permission to see the run) get the same detail and simulation UI.
## Who can see which runs?
| Role | Visibility |
| --------- | ---------------------------- |
| Org admin | All runs in the organization |
| Member | Only their own runs |
## What is recorded?
| Case | Persisted? |
| ------------------------------------ | --------------------------------------------------------------- |
| Normal / live run with a workflow id | Yes (subject to Workflow Recording) |
| Dry run | Never |
| Waiting for human approval | Yes (even if recording is **Disabled**, so resume can continue) |
### Workflow Recording modes
| Mode | What is stored |
| ---------------------------- | --------------------------------------------------------- |
| **Full recording** (default) | Inputs, step traces, and result |
| **Headers only** | Metadata and payload sizes; bodies redacted in the UI |
| **Disabled** | No history rows except HITL checkpoints needed for resume |
Configure under **Settings → Organization → Workflow Recording**.
## Related
* [Workflows](/user-guide/workflows) — design and run workflows on an agent
* [Actions](/user-guide/actions) — API / MCP call history
* [Settings](/user-guide/settings#workflow-recording-organization) — recording policy
* API: [List workflow run history](/api-reference/workflow/workflow-runs-history-list), [Get workflow run history](/api-reference/workflow/workflow-run-history-get), [Activity timeline](/api-reference/workflow/workflow-runs-activity-timeline)
# Workflows
Source: https://docs.apigene.ai/user-guide/workflows
Multi-step agent graphs you can run, simulate, and approve
## Overview
**Workflows** are executable multi-step graphs attached to an agent. Each workflow has nodes (actions, branches, joins, LLM steps, approvals, and outputs) connected into a path the Apigene engine runs from start to finish.
Use workflows when you need a **deterministic** sequence — with branching, parallel joins, human approval, and a clear final result — rather than a free-form chat turn.
| Feature | Best for |
| ---------------------------------- | -------------------------------------------------------- |
| [Workflows](/user-guide/workflows) | Compiled multi-step automation with run/simulate/approve |
| [Tasks](/user-guide/tasks) | Scheduled or on-demand saved prompts |
| [Skills](/user-guide/skills) | Reusable procedures the agent loads as guidance |
## Where to find them
1. In the **Design** workspace, open **Build → Agents**
2. Select an agent
3. Open the **Workflows** tab
From there you can list workflows, open the graph, **Edit** it visually, run, simulate, and delete. Create or update graphs through **Copilot** / **Design Agent** (with that agent selected) or **MCP Gateway** tools.
## View and edit the graph
Open a workflow to see the graph:
* Nodes are color-coded by type (action, condition, join, LLM, approve, output, and more)
* Click a node to inspect parameters and, after a traced run, the resolved step input and output
* Pan, zoom, and search steps. Toggle the **mini map** on or off (your preference is remembered)
* Open **Help** on the graph or a run for node types, expressions, and limits
If you have edit access, click **Edit** to change the graph in place:
1. Add steps from the palette: **Action**, **Condition**, **Approval**, **Set values**, **Result**, and **AI step**
2. Drag from a handle to connect steps. **Backspace** or **Delete** removes the selected step or link
3. Edit the workflow name and description in the header, and inspect or update the selected node in the side panel
4. Click **Save** to compile and store the draft
**View** leaves edit mode and discards unsaved changes. Simulation is disabled while you are editing — leave edit mode to replay a run on the graph.
The visual palette covers linear steps plus if / approve branches. Map, switch, and join nodes created from Copilot or MCP still appear on the graph and can be inspected; rewiring those loop or case handles is done from chat or MCP.
## Run a workflow
1. Open the workflow (or use **Run** from the list)
2. Provide **runtime inputs** as JSON (merged over any stored defaults)
3. Optionally enable:
* **Include step data** — keep per-step traces (required for **Simulate**)
* **Dry run** — walk the graph without live API / MCP / LLM side effects (approvals auto-pass)
4. Click **Run**
When the run finishes, Copilot shows status feedback. In chat, **Run Workflow** tool cards show a green / yellow / red status indicator and the workflow name.
### Run statuses
| Status | Meaning |
| --------------- | --------------------------------------------------------------------------- |
| `succeeded` | Workflow completed; use the final `result` |
| `failed` | A step failed; check `failed_step_id` when present |
| `waiting_human` | An **approve** node is waiting — use the approval card or `resume_workflow` |
| `waiting_auth` | Credentials needed — authenticate, then run again |
| `rejected` | An approval was rejected (and no reject path continued) |
## Simulate on the graph
After a successful run **with step data**:
1. Click **Simulate** (or **Simulate on graph** from the run dialog)
2. Watch steps light up from Start through the run path to End
3. **Pause** to inspect any node’s details in the side panel
4. **Resume** or **Reset** as needed
Simulate is the best way to demo and debug a workflow path without re-hitting live systems every time — pair it with **Dry run** for a fully safe rehearsal.
## Human approval (HITL)
Workflows can include an **approve** node. When the run reaches it, status becomes `waiting_human` and Copilot shows an approval card:
* **Approve** or **Reject**
* Optionally edit preview fields before approving
* The run continues via resume (same user who started the run)
From MCP clients, call `resume_workflow` with the `run_id` and `decision`.
## Create and update workflows
Ask Copilot (with the agent selected) or Design Agent **Extend** to create a workflow, or call MCP `create_workflow` from Cursor, Claude, or other clients connected to the design MCP URL. The id is derived from the name (for example `Account update` → `account-update`). Open the new graph on the agent's **Workflows** tab, click **Edit**, add steps, then **Save**.
MCP clients can also create or update workflows when connected to the **design** MCP URL (mutations are design-only):
```
https://app.apigene.ai/agent/{agent_name}/design/mcp
```
Runtime runs use `https://app.apigene.ai/agent/{agent_name}/mcp` (live).
### MCP tools (Agent mode)
| Tool | Purpose | Mode |
| ----------------- | ------------------------------------------------------------------------ | --------------- |
| `list_workflows` | List workflows (`detailed` optional) | Live and design |
| `create_workflow` | Create with `workflow_id`, `description`, `nodes`, `connections` | Design only |
| `get_workflow` | Fetch one workflow | Live and design |
| `update_workflow` | Patch name, description, nodes, connections, or inputs | Design only |
| `delete_workflow` | Delete by `workflow_id` | Design only |
| `run_workflow` | Run with `inputs`, optional `include_data`, optional `dry_run` | Live and design |
| `resume_workflow` | Continue after HITL with `run_id` and `decision` (`approve` \| `reject`) | Live and design |
See [MCP Gateway Tools](/user-guide/mcp-gateway/mcp-gateway-tools#list_workflows) for parameter details.
### Example: dry run with traces
```json theme={null}
{
"tool": "run_workflow",
"arguments": {
"workflow_id": "onboard-new-hire",
"inputs": { "email": "alex@example.com" },
"include_data": true,
"dry_run": true
}
}
```
## Node types
Common `apigene.*` node types:
| Type | Role |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `action` | Call an application operation |
| `if` / `switch` | Branch on conditions |
| `join` | Wait for parallel branches |
| `set` / `filter` / `summarize` | Transform or aggregate data |
| `map` | Iterate an array — **loop** body per item, then **done** with the collected list |
| `llm` | Call a language model inside the graph |
| `generative_ui` | Render a generative UI result from the workflow |
| `approve` | Pause for human decision |
| `output` | Terminal node that defines the public `result` |
Workflows should end in an **output** node so runners get a clear final result.
### Map (loop over items)
`apigene.map` follows an n8n-style **Loop Over Items** pattern:
* **Loop** (`main[0]`) — runs once per item; use `$json` for the current item and `$index` for the 0-based index
* **Done** (`main[1]`) — runs after all items succeed; `$json` is the collected array (also available as `$node..json.items`)
* If any iteration fails, the map fails and **done does not run**
Wire enrichment steps on the loop port; bind tables, UI, or the final output on the done port.
### Expressions
Workflow expressions use `={{ ... }}` with:
* Arithmetic and compares (`+ - * /`, `== != > >= < <=`)
* Logical operators (`&&`, `||`) and nullish coalescing (`??`)
* Optional paths (`?.`, `?[`)
* Helpers such as `find(arr, field, matchValue[, returnField])` and `filter_by(arr, field, value)` for nested lookups (for example Gmail headers)
Example: `={{ $json.items?.length ?? 0 }}`
## Tips for demos and production
* Prefer **Dry run** + **Include step data** when rehearsing
* Use **Simulate** to walk the path on the graph after the run
* Keep HITL steps for irreversible actions
* Store defaults in workflow `inputs`; pass overrides at run time
## Related
* [Workflow History](/user-guide/workflow-history) — org-wide run log, share, and simulation replay
* [Agents](/user-guide/agents) — workflows live on an agent
* [Tasks](/user-guide/tasks) — scheduled prompts (not graphs)
* [Skills](/user-guide/skills) — procedural guidance for agents
* [MCP Gateway Tools](/user-guide/mcp-gateway/mcp-gateway-tools) — full tool reference
* [MCP vs Agent Modes](/user-guide/mcp-gateway/mcp-gateway-modes) — workflows require Agent mode