---
title: "Archive the agent — read-only, sessions keep running, new sessions rejected [admin]"
method: POST
path: "/agents/{id}/archive"
---

# Archive the agent — read-only, sessions keep running, new sessions rejected \[admin\]

`POST /agents/{id}/archive`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/agents/{id}/archive`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Response `200`

OK

- object
  - `agent` AgentDetail, required: Everything in the list item, plus configuration state.
    - `id` string: The agent id (agent_…) — the only address
    - `name` string
    - `displayName` string
    - `agentType` string
    - `llm` string
    - `harnessVersion` string, nullable
    - `reasoningEffort` 'none' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'null', nullable
    - `version` integer
    - `archived` boolean
    - `sessionCount` integer
    - `createdAt` string
    - `description` string, nullable
    - `prompt` string, nullable: The user prompt layer
    - `promptVersion` integer, nullable
    - `capabilities` string[]: The built-in capabilities this agent is granted — the exact set its sessions may execute (enforced; empty = none). Ids are listed at /docs/capabilities.
    - `capabilityPolicies` object: Per-capability permission policy map; omitted when no entries exist. always_allow: invoke without user confirmation. always_ask: prompt the session owner before every invocation. auto: reserved for future policy evaluation; currently prompts the session owner like always_ask.
    - `nativeToolPolicy` 'always_allow' | 'always_ask': Native pod-tool permission, independent of capabilities. Returned on create and detail responses; omitted legacy settings mean always_allow. Only the agent owner can change it, while sessions are idle.
    - `hiringPolicy` 'allow' | 'deny': Whether this agent's sessions may bring in other agents as helpers. allow unless set to deny. Returned on create and detail responses.
    - `mcpServers` object[]: Declared remote MCP server references, including tool filters; runtime authentication fields are never returned
      - `type` 'url'
      - `name` string, required
      - `url` string, uri, required
      - `tools` object
        - `include` string[]
        - `exclude` string[]
    - `hooks` object[]: Shell commands run in the session's pod at lifecycle events
      - `event` 'pre_session_start' | 'session_start' | 'user_prompt_submit' | 'pre_tool_use' | 'post_tool_use' | 'stop' | 'session_end', required
      - `command` string, required
      - `matcher` string
      - `timeout_s` integer
    - `metadata` object: Your key-merged client metadata
    - `environmentId` string, nullable: The environment sessions of this agent boot in when their create names none; ahead of the workspace default
    - `vaultId` string, nullable: The vault every session of this agent carries, after the vaults its create names and ahead of the workspace default
    - `defaultSessionId` string, nullable: The session conversation verbs target when addressed by agent id
    - `universe` string: Resolved universe slug

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 11 warning, 7 info
  - added the new `code-review` enum value to the `agent/capabilities/items/` response property for the response status `200`
  - added the new `dictionary.define` enum value to the `agent/capabilities/items/` response property for the response status `200`
  - added the new `elevenlabs.music` enum value to the `agent/capabilities/items/` response property for the response status `200`
  - added the new `elevenlabs.tts` enum value to the `agent/capabilities/items/` response property for the response status `200`
  - …14 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/agents/:id/archive/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)