---
title: "Set Agent Home"
method: PUT
path: "/api/agents/{agent_id}/home"
tags: ["agents"]
---

# Set Agent Home

`PUT /api/agents/{agent_id}/home`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/agents/{agent_id}/home`
- Auth: none declared

Move an agent to another home folder (TOS-2150). Active owners only.

Deliberately NOT a field on `PUT /api/agents/{id}`. A home folder is not
part of the agent's self-description; it is the OWNER filing an object in
their namespace, and authorizing it needs a second axis the profile
endpoint does not check: write reach on the TARGET folder, exactly like
moving a document or an integration between folders. So this endpoint takes
the ownership axis (an explicit owner grant - an agent may not re-file
itself) plus that reach check.

The agent's address changes and it lists under a different folder. For an
agent whose owners are its folder's administrators (every agent created
since home-folder authority), moving it CHANGES WHO OWNS IT: the owners
become the destination folder's administrators, and the previous folder's
administrators lose ownership unless they also administer the destination.
To add a co-owner without losing anyone, use agent_share instead.

## Path parameters

- `agent_id` string, uuid, required

## Headers

- `x-impersonate-identity-id` string, nullable

## Request body

- SetAgentHomeBody
  - `home_library_id` string, uuid, required

## Response `200`

Successful Response

- AgentResponse
  - `can_receive_chat` boolean
  - `funding_selection` object, nullable
  - `id` string, uuid, required
  - `display_name` string, required
  - `avatar_url` string, nullable, required
  - `description` string, nullable, required
  - `tagline` string, nullable
  - `visual_brand_guidelines` string, nullable
  - `visual_brand_logo_url` string, nullable
  - `system_prompt` string, nullable, required
  - `operating_instructions` string, nullable
  - `charter_creation` object, nullable
  - `can_edit_charter` boolean, nullable: Owner-only advisory for this detail request's charter edit authority. Missing/null is unknown; writes still recheck authority and charter version.
  - `config` object, required
  - `status` 'active' | 'archived', required
  - `connection_policy` 'off' | 'request' | 'auto', required
  - `owners` AgentOwnerResponse[], required
    - `owner_identity_id` string, uuid, required
    - `granted_at` string, required
    - `granted_by` string, uuid, nullable, required
    - `revoked_at` string, nullable, required
    - `revoked_by` string, uuid, nullable, required
    - `source` 'folder_admin' | 'controller'
  - `owned_by_caller` boolean
  - `relationship` 'myself' | 'built' | 'hired' | 'connected' | 'public'
  - `listing` ListingConsentResponse: TOS-3663 / TOS-5058: the owner's remaining Marketplace listing consent. ``available`` and ``disclosed`` were removed: whether an identity is listed, and whether its profile shows once listed, both derive from ``Identity.connection_policy`` (``off`` = not listed; otherwise listed with its profile shown). Stored at ``identity_config.config["listing"]``; a missing key reads as False.
    - `priced` boolean
  - `registration_ids` string[]
  - `tts_voice` string, nullable
  - `tts_voice_backup` string, nullable
  - `browser_automation_enabled` boolean
  - `web_browse_enabled` boolean
  - `communication_profile` CommunicationProfile
    - `preset` 'adaptive' | 'clear_direct' | 'warm_expressive' | 'formal_precise'
    - `schema_version` 1
    - `overrides` object
  - `reply_workflow` 'manual' | 'draft' | 'send'
  - `unreviewed_information_scope` 'limited' | 'full'
  - `learning_scope` 'private' | 'discretion' | 'open': TOS-6036: what an agent carries from one person it serves to the next. Owner-only, agent-level, stored at ``identity_config.config.learning_scope``. Distinct from :class:`UnreviewedInformationScope`, which only widens READ access for auto-sent replies and says nothing about what a teach WRITE is scoped to. * ``private`` keeps every learned item partitioned to the person who said it (the pre-TOS-6036 behaviour). * ``discretion`` (default) shares items classified ``about_work`` with everyone the agent serves and keeps ``about_person`` items private. * ``open`` shares everything the agent learns with everyone it serves.
  - `self_improvement_policy` 'off' | 'review' | 'minor'
  - `default_mode` 'human' | 'agent_augmented' | 'agent'
  - `self_improvement_mode` 'manual' | 'augmented' | 'autonomous'
  - `is_global` boolean
  - `kind` 'person' | 'agent'
  - `agent_key` string, nullable
  - `deleted_at` string, nullable
  - `archetype` string, nullable
  - `tags` string[]
  - `classification_source` string, nullable
  - `classified_at` string, nullable
  - `model_bundle` IdentityModelBundleResponse
    - `template_id` string, uuid, required
    - `template_name` string, required
    - `provider_family` string, required
    - `template_version` integer, required
    - `template_version_id` string, uuid, nullable
  - `home_library_id` string, uuid, nullable
  - `address` string, nullable
  - `home_domain_label` string, nullable
  - `ownership_source` 'home_folder' | 'controllers'
  - `home_folder` AgentHomeFolderResponse: The folder an agent lives in, named for the viewer who may see it (TOS-7857).
    - `id` string, uuid, required
    - `name` string, nullable, required
    - `is_private` boolean, required
  - `disclose_capabilities` boolean
  - `disclose_reputation` boolean
  - `warnings` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/ce2c2ce318b1?raw)