> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt > Use this file to discover all available pages before exploring further. # Set agent incognito > Set whether every new task on a custom agent must run incognito. The caller needs update access on the agent. Enabling (`enforced: true`) requires Enterprise and the Incognito agents role permission (`organization:enforce_agent_incognito`), separate from the Incognito tasks permission. Disabling requires only update access, including after a downgrade. Existing sessions keep their original mode. Incognito does not save message content for history or search, but task metadata and temporary message caches can remain. Returns the full updated agent, including `agent.incognito.enforced`. Generic `PATCH /agents/{agent_id}` rejects top-level `incognito` with `400 invalid_request`. ## OpenAPI ````yaml patch /agents/{agent_id}/incognito openapi: 3.0.0 info: title: Public API version: 1.0.0 servers: - url: https://api.gumloop.com/api/v1 security: [] paths: /agents/{agent_id}/incognito: patch: tags: - Agents summary: Set agent incognito description: > Set whether every new task on a custom agent must run incognito. The caller needs update access on the agent. Enabling (`enforced: true`) requires Enterprise and the Incognito agents role permission (`organization:enforce_agent_incognito`), separate from the Incognito tasks permission. Disabling requires only update access, including after a downgrade. Existing sessions keep their original mode. Incognito does not save message content for history or search, but task metadata and temporary message caches can remain. Returns the full updated agent, including `agent.incognito.enforced`. Generic `PATCH /agents/{agent_id}` rejects top-level `incognito` with `400 invalid_request`. operationId: setAgentIncognito parameters: - in: path name: agent_id required: true schema: type: string description: ID of a custom agent. Platform agents are not customizable. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - enforced properties: enforced: type: boolean description: Enable or disable incognito enforcement for new tasks. example: true examples: enable: summary: Enforce incognito for new tasks value: enforced: true disable: summary: Stop enforcing incognito for new tasks value: enforced: false responses: '200': description: >- The full updated agent. The example focuses on incognito fields; other agent fields are omitted for readability. content: application/json: schema: type: object required: - agent properties: agent: $ref: '#/components/schemas/Agent' example: agent: id: abc123DEFghiJKL name: Private research agent incognito: enforced: true '400': description: >- Invalid request body (`invalid_request`), or the agent is a platform agent (`agent_not_customizable`). '401': description: 'Unauthorized: missing or invalid credentials.' '403': description: >- Forbidden: missing update access (`item_access_required`), or enabling is denied by the Enterprise tier (`subscription_tier_required`) or the Incognito agents role permission (`organization_permission_required`). '404': description: Agent not found. '500': description: Internal server error. security: - bearerAuth: [] x-codeSamples: - lang: bash label: cURL source: > curl -X PATCH 'https://api.gumloop.com/api/v1/agents/abc123DEFghiJKL/incognito' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"enforced": true}' components: schemas: Agent: type: object description: >- An agent and its whole configuration. Single-agent retrieve, create and update return this shape; the list endpoint does not populate the inlined collections, abilities or version. Collection-specific writes return their own result shapes. properties: id: type: string example: abc123DEFghiJKL name: type: string example: Sales research agent description: type: string nullable: true example: Researches accounts and drafts outreach team_id: type: string example: team_4f8c92ab is_active: type: boolean example: true version: type: integer nullable: true description: >- Latest configuration version. Send it back as `version` on `PATCH` to refuse the update if the agent changed in between. example: 4 model_name: type: string nullable: true example: anthropic/claude-sonnet-4 system_prompt: type: string nullable: true example: You are a B2B sales research assistant. tools: type: array description: >- Connectors, workflows and native abilities the agent can call. Secret references are stripped and custom MCP URLs are redacted. Prefer the `abilities` and `mcp-servers` endpoints over editing this list. items: $ref: '#/components/schemas/AgentTool' metadata: $ref: '#/components/schemas/AgentMetadata' abilities: allOf: - $ref: '#/components/schemas/AgentAbilities' nullable: true description: Native abilities, derived from `tools`. `null` on the list endpoint. incognito: $ref: '#/components/schemas/AgentIncognito' skill_ids: type: array nullable: true description: >- IDs of attached skills. `null` when the caller cannot view skills or on the list endpoint; `[]` when none are attached. items: type: string example: - skill_2b9c - skill_7f1a knowledge_sources: type: array nullable: true description: >- Attached Brain sources and their scope. `null` when the caller cannot view knowledge sources or on the list endpoint. items: $ref: '#/components/schemas/AgentKnowledgeSource' triggers: type: array nullable: true description: >- Triggers the caller can see. `null` when the caller cannot view triggers or on the list endpoint. Webhook URLs are never included here. items: $ref: '#/components/schemas/AgentTrigger' resources: type: array items: type: object folder_id: type: string nullable: true example: folder_91ab type: type: string nullable: true description: Internal agent type discriminator. created_at: type: string format: date-time nullable: true example: '2026-05-15T14:32:00Z' last_used_at: type: string format: date-time nullable: true last_updated_at: type: string format: date-time nullable: true active_trigger_count: type: integer nullable: true description: Number of enabled triggers. Only populated on the list endpoint. creator: type: object nullable: true properties: id: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true email: type: string nullable: true profile_picture: type: string nullable: true AgentTool: type: object description: >- One entry of an agent's `tools` list. `type` decides which fields apply. Unknown fields are kept as sent. required: - type properties: type: type: string description: >- `gumcp_server` and `gumstack_server` are connectors from your catalog; `mcp_server` is a custom MCP server keyed by its secret; `saved_item`, `web_search`, `web_fetch`, `image_generator`, `interaction_search`, `human_input`, `browser`, `manage_evals`, `manage_wiki`, `sandbox`, and `chat_widget` are native abilities. Chat Widgets requires only `{"type": "chat_widget"}`. Any other value is a remembered "don't ask again" decision for a native tool family (for example `trigger_creation`) and requires `approval_mode`, with optional `tool_approval_modes`. Unknown entry fields are preserved. server_id: type: string description: Catalog ID for `gumcp_server` and `gumstack_server`. example: gmail mcp_server_url: type: string nullable: true description: >- Custom MCP endpoint for mcp_server. URLs are redacted in agent responses. secret_id: type: string nullable: true writeOnly: true description: >- Saved custom MCP connection ID for mcp_server. Secret IDs are removed recursively from agent responses. name: type: string nullable: true credentials_to_use: type: object description: >- Per-credential-type account selection, e.g. `{"gmail_access_token": {"is_default": true}}`. additionalProperties: type: object properties: secret_id: type: string is_default: type: boolean is_personal_credential: type: boolean credential_mode: type: string enum: - end_user - agent_owned description: >- Whose credential the connector runs with. `agent_owned` pins the configured account for everyone who uses the agent. approval_mode: type: string enum: - inherit - 'off' - all - write - custom description: >- When the agent must ask before calling this connector. `custom` uses `tool_approval_modes`. tool_approval_modes: type: object additionalProperties: type: string enum: - inherit - 'off' - all - write - custom description: 'Per-tool approval modes for `approval_mode: custom`.' restricted_tools: type: array items: type: string description: Tool names the agent may not call on this connector. is_incognito: type: boolean is_disabled: type: boolean description: On `human_input`, `true` turns Ask Question off. saved_item_id: type: string description: Workflow ID for `saved_item`. saved_item_version_id: type: string nullable: true description: Optional version pin for a stored saved_item entry. metadata: type: object description: >- Ability settings. `web_search` / `web_fetch`: `preferred_provider`. `image_generator`: `model`. `browser`: `proxy` (`enabled`, `country`), `profile_id`. AgentMetadata: type: object description: >- Agent settings, grouped as the agent panel groups them. On PATCH, objects merge and arrays and scalars replace, except model_settings, which replaces the saved object whole. Unknown keys are dropped. properties: icon_url: type: string nullable: true max_steps: type: number nullable: true description: Maximum tool-calling steps per turn. Omit for the platform default. example: 30 model_settings: type: object description: >- Advanced model parameters. On PATCH, this object replaces the saved model_settings whole; send every field you want to keep. Valid options depend on the model; GET /models lists them. suggested_prompts: type: array items: type: object required: - title - message properties: title: type: string message: type: string icon: type: string nullable: true servers: type: array description: Connector badges for this suggested prompt. items: type: object required: - server_id - server_type properties: server_id: type: string server_type: type: string default: [] self_modification: type: object description: Whether the agent may edit its own instructions. properties: enabled: type: boolean app_rules: type: object nullable: true description: Whether the agent may create app rules. properties: creation_enabled: type: boolean nullable: true app_discovery: type: object description: >- Whether the agent may discover and use connectors beyond those attached. properties: enabled: type: boolean skills: type: object description: Whether the agent may create skills. properties: creation_enabled: type: boolean triggers: type: object description: Whether the agent may create triggers. properties: creation_enabled: type: boolean tool_discovery: type: object properties: mode: type: string enum: - auto - enabled tool_approval: type: object description: >- Default approval behaviour for connector calls, before per-connector `approval_mode`. properties: default_mode: type: string enum: - inherit - 'off' - all - write - custom reason: type: string approver_user_id: type: string nullable: true subagent: type: object properties: allow_self_clone: type: boolean allowed_gummie_ids: type: array items: type: string description: >- Accepted during creation, but ignored by PATCH /agents/{agent_id}. After creation, attach and detach subagents with the subagents endpoints. artifacts: type: object description: Default sharing for files the agent creates. properties: default_access: type: string enum: - default - organization - anyone voice: type: object properties: enabled: type: boolean voice: type: string nullable: true speaking_style: type: string nullable: true maxLength: 500 description: Instructions for how the agent should speak. compaction: type: object description: Chat summarization. Omit to keep the automatic defaults. properties: override_auto_compaction: type: boolean summary_model: type: string context_limit: type: integer output_reserve_tokens: type: integer prune_protect_tokens: type: integer summary_max_tokens: type: integer proactive_trigger_percent: type: integer fallback: type: object description: Model fallback when the primary model is unavailable. properties: enabled: type: boolean override_auto_fallback: type: boolean fallback_models: type: array items: type: string image_generation: type: object properties: model: type: string self_improvement: type: object description: >- Reflections. Requires the Reflections tier; the server turns it off otherwise. properties: enabled: type: boolean cron_expression: type: string timezone: type: string slack: type: object properties: thread_response_trigger: type: string nullable: true enum: - on_mention - on_any_message - auto attribution_stamp_enabled: type: boolean show_detailed_steps: type: boolean email: type: object properties: attribution_stamp_enabled: type: boolean AgentAbilities: type: object description: >- Native abilities. On `PATCH /agents/{agent_id}/abilities` send only the ones you want to change; each is a small object so settings travel with the toggle. properties: web_search: type: object properties: enabled: type: boolean provider: type: string nullable: true description: Preferred search connector, e.g. `exa`. Omit for automatic. web_fetch: type: object properties: enabled: type: boolean provider: type: string nullable: true image_generation: type: object properties: enabled: type: boolean model: type: string nullable: true search_past_conversations: type: object properties: enabled: type: boolean ask_question: type: object description: Whether the agent may pause to ask the person a question. properties: enabled: type: boolean tool_discovery: type: object properties: mode: type: string enum: - auto - enabled manage_evaluations: type: object properties: enabled: type: boolean chat_widgets: type: object additionalProperties: false required: - enabled description: >- Compact visuals in web chats. On by default for new custom agents; enable explicitly on older agents. Represented in `tools` by `{"type": "chat_widget"}`. properties: enabled: type: boolean example: true browser: type: object properties: enabled: type: boolean proxy_country: type: string nullable: true description: >- ISO 3166 alpha-2 country the browser appears to browse from. `null` turns the proxy off. example: us profile_id: type: string nullable: true description: >- Browser profile whose sign-ins the agent uses. Pinning one switches the browser to agent-owned credentials, as the panel does; `null` clears both. AgentIncognito: type: object description: >- Incognito enforcement for new tasks on this agent. Included in create, retrieve, update, and list agent responses. Existing sessions retain their original mode. required: - enforced properties: enforced: type: boolean default: false description: Whether every new task on the agent must run incognito. example: false AgentKnowledgeSource: type: object properties: connector_id: type: string description: Brain source ID, as returned by `GET /brain/sources`. example: PFqdAMir8PA2Xc6qcszSN9 config: $ref: '#/components/schemas/KnowledgeSourceScope' AgentTrigger: type: object properties: id: type: string example: trg_7f1a2b agent_id: type: string example: abc123DEFghiJKL type: type: string description: >- `schedule` and `webhook` can be created, fully edited and deleted through the API. Other types (connector events, agent-built triggers) can be renamed, reworded, paused and resumed, but their settings live on the trigger page. example: schedule name: type: string nullable: true prompt: type: string nullable: true description: The message the agent receives when the trigger fires. cron_expression: type: string nullable: true description: Five-field cron, for recurring schedules. example: 0 9 * * 1-5 run_at: type: string format: date-time nullable: true description: One-time run, for `schedule` triggers created with `run_at`. timezone: type: string nullable: true example: America/Los_Angeles pass_raw_data: type: boolean nullable: true description: >- Webhook only. `true` forwards the request body to the agent instead of `prompt`. enabled: type: boolean status: type: string nullable: true max_failures: type: integer nullable: true description: Consecutive failures before the trigger disables itself. webhook_url: type: string nullable: true description: >- Only on the create response. Fetch it later with `GET /agents/{agent_id}/triggers/{trigger_id}/webhook-url`; it embeds the trigger's secret. created_at: type: string format: date-time nullable: true last_run_at: type: string format: date-time nullable: true KnowledgeSourceScope: type: object nullable: true description: >- Which part of a Brain source the agent reads. `null` is the whole source. Without `mode`, everything except `exclusions`; with `include_only`, only `inclusions`. properties: mode: type: string enum: - denylist - include_only inclusions: type: array items: $ref: '#/components/schemas/KnowledgeScopeRule' exclusions: type: array items: $ref: '#/components/schemas/KnowledgeScopeRule' KnowledgeScopeRule: type: object required: - type - id properties: type: type: string enum: - container - document description: '`container` is a folder, channel or similar; `document` is one file.' id: type: string description: >- The item's ID in the source, as returned by `GET /brain/sources/{connector_id}/files`. name: type: string nullable: true securitySchemes: bearerAuth: type: http scheme: bearer description: >- A personal API key or an [OAuth 2.0](/api-reference/oauth) access token. Personal API keys also require the `x-auth-key` header with your user ID. ````