# iblai-api-agent-setting

> Mirrored from [`iblai/base`](https://github.com/iblai/base) · [`skills/agents/iblai-api-agent-setting/SKILL.md`](https://github.com/iblai/base/blob/main/skills/agents/iblai-api-agent-setting/SKILL.md). This page is generated — edit it in the repository, not here.

> ★ **Core family.** **With a screen:** `/iblai-vibe-agent-setting` mounts the agent Settings tab — this skill is the headless twin (same data, exact endpoints).

Read and write an agent's core settings: identity (name, description, category,
profile image), discovery/visibility, and capability flags (anonymous, featured,
LTI, attachments, voice, memory, multi-query RAG, reasoning, prompt caching,
incognito, forkable, additional agents) — all of which save
through the single `settings/` endpoint — plus forking (copy) and deletion. Use
when configuring an agent's basic identity and capabilities.

## Auth & conventions

- **Base URL:** `https://api.iblai.app`
- **Header:** `Authorization: Api-Token $IBLAI_API_KEY` on every request.
- **Path vars:** `{org}` = `$IBLAI_ORG`, `{username}` = `$IBLAI_USERNAME`,
  `{mentor}` = the agent's unique id (e.g. `d17dc729-60fd-4363-81a0-f67d9318b03e`).
- **Settings writes** go through one endpoint —
  **PUT** `…/users/{username}/mentors/{mentor}/settings/` with
  `multipart/form-data` — sending **only the changed field(s)**.
- Not connected yet? Run **`/iblai-api-login`** first to populate `IBLAI_ORG`,
  `IBLAI_USERNAME`, and `IBLAI_API_KEY`.

## Reads

- **GET** `https://api.iblai.app/dm/api/ai-mentor/orgs/{org}/users/{username}/mentor/categories/` — category options.
- **GET** `https://api.iblai.app/dm/api/ai-mentor/orgs/{org}/users/{username}/mentors/{mentor}/settings/` — load all current field values.
- **GET** `https://api.iblai.app/dm/api/ai-mentor/orgs/{org}/mentors/{mentor}/claw-config/` — detect sandbox wiring (404 = not connected).

## Writes

- **PUT** `…/users/{username}/mentors/{mentor}/settings/` — update settings (`multipart/form-data`, send only changed keys):
  ```json
  {
    "mentor_name": "string",
    "mentor_description": "string",
    "categories": "number[]",
    "uploaded_profile_image": "File",
    "mentor_visibility": "string",
    "allow_anonymous": "boolean",
    "is_featured": "boolean",
    "is_lti_accessible": "boolean",
    "show_attachment": "boolean",
    "show_voice_call": "boolean",
    "show_voice_record": "boolean",
    "enable_claw": "boolean",
    "enable_virtual_machine": "boolean",
    "virtual_machine_egress": "none | registries | public | custom",
    "virtual_machine_network_policy_id": "number | null (required when egress is custom)",
    "virtual_machine_secret_ids": "number[] (egress must be public or custom)",
    "enable_memory_component": "boolean",
    "enable_multi_query_rag": "boolean",
    "show_reasoning": "boolean",
    "enable_prompt_caching": "boolean",
    "disable_chathistory": "boolean",
    "forkable": "boolean",
    "show_explore_mentors": "boolean"
  }
  ```
  `mentor_visibility` is one of `viewable_by_tenant_admins` (only org admins,
  the creator and people given access find and chat with it),
  `viewable_by_tenant_students` (every org member) or `viewable_by_anyone`
  (every member, and it is listed in the public catalog for non-members).
  `allow_anonymous` is separate: `true` lets anyone with the link chat without
  signing in, whatever the visibility.
  `show_explore_mentors` shows the additional-agents section on the agent's
  welcome screen ("Show additional agents"). `disable_chathistory` makes every
  conversation with this agent incognito; the Privacy tab’s Incognito policy
  sets it (see `/iblai-vibe-incognito`). `show_reasoning` shows the agent’s
  reasoning steps while it responds; `enable_prompt_caching` caches repeated
  prompt context to cut latency and cost on Anthropic models, and also turns
  off document retrieval, memory and the current date/time in the system
  prompt; `enable_multi_query_rag` is "Enhanced document retrieval". The
  embed-widget counterparts of `show_attachment` / `show_voice_record` /
  `show_voice_call` (`embed_show_*`) save through the same PUT — see
  `/iblai-api-agent-embed`.
  The three `virtual_machine_*` keys configure the agent's Linux VM sandbox;
  the networks and environment variables they reference are managed per
  organization — see `/iblai-vibe-agent-sandbox` ("Virtual machine networks &
  environment variables").
- **POST** `…/users/{username}/mentors/{mentor}/fork/` — copy / duplicate agent:
  ```json
  {
    "new_mentor_name": "string (required)",
    "destination_platform_key": "string (required)",
    "clone_documents": "boolean"
  }
  ```
- **DELETE** `https://api.iblai.app/dm/api/ai-mentor/orgs/{org}/users/{username}/{mentor}/` — delete agent (user-scoped path; no body). Destructive — confirm with the user first.

## Example

Rename an agent and make it featured (only the two changed fields are sent):

```bash
curl -X PUT \
  "https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/$MENTOR/settings/" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  -F "mentor_name=Joseph (Prod)" \
  -F "is_featured=true"
```

## Notes

- A field left out of the PUT is left unchanged — never resend the whole object.
- `categories` expects numeric category ids from the categories endpoint, not names.
- Deletion and forking are scoped to `{username}`; settings reads/writes use the
  `users/{username}/mentors/{mentor}/` path.
