> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Archive an agent

> Archive an Agent. Archived Agents are hidden from default listings but can still be retrieved by ID.

`POST /api/v1/cloud/agents/{agent_id}/archive`

Archives the specified Agent. Archived Agents are hidden from the default list but remain retrievable by ID.

## Headers

| Header          | Required | Description    |
| --------------- | -------- | -------------- |
| `Authorization` | Yes      | `Bearer <PAT>` |

## Path parameters

| Parameter  | Type   | Required | Description             |
| ---------- | ------ | -------- | ----------------------- |
| `agent_id` | string | Yes      | Agent unique identifier |

## Request body

No request body.

## Example request

```bash theme={null}
curl -X POST "https://api.qoder.com/api/v1/cloud/agents/agent_019eXXXX.../archive" \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "Used for API documentation testing",
  "model": "ultimate",
  "system": "You are an updated documentation testing assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 2,
  "archived_at": "2026-05-18T15:27:22.698411Z",
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:22.698411Z"
}
```

## Response fields

Returns the full Agent object after archival. `updated_at` reflects the time of the archive operation.

| Field         | Type                                                                     | Description                                       |
| ------------- | ------------------------------------------------------------------------ | ------------------------------------------------- |
| `type`        | string                                                                   | Always `"agent"`                                  |
| `id`          | string                                                                   | Agent unique identifier                           |
| `name`        | string                                                                   | Agent name                                        |
| `description` | string                                                                   | Agent description                                 |
| `model`       | string                                                                   | Model identifier                                  |
| `system`      | string                                                                   | System prompt                                     |
| `tools`       | array of [Agent tool](/cloud-agents/api/agents/schemas#agent-tool)       | Tool configuration list                           |
| `mcp_servers` | array of [MCP server](/cloud-agents/api/agents/schemas#mcp-server)       | MCP server configuration                          |
| `skills`      | array of [Skill binding](/cloud-agents/api/agents/schemas#skill-binding) | Skill bindings                                    |
| `metadata`    | [Metadata object](/cloud-agents/api/conventions/schemas#metadata-object) | Custom metadata                                   |
| `multiagent`  | [Multiagent](/cloud-agents/api/agents/schemas#multiagent) \| null        | Agents configuration, `null` when not set         |
| `version`     | integer                                                                  | Current version                                   |
| `archived_at` | string\|null                                                             | Archive time (ISO 8601), `null` when not archived |
| `created_at`  | string                                                                   | Creation time (ISO 8601)                          |
| `updated_at`  | string                                                                   | Last update time (ISO 8601), refreshed on archive |

## Errors

| HTTP | Type                   | Trigger                                |
| ---- | ---------------------- | -------------------------------------- |
| 401  | `authentication_error` | PAT invalid or expired                 |
| 403  | `permission_error`     | Not authorized to archive this Agent   |
| 404  | `not_found_error`      | Agent with the given ID does not exist |

See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope.

## Notes

* Archive retains Agent data.
* Archived Agents are excluded from the default list returned by `GET /api/v1/cloud/agents`.
* Pass `include_archived=true` on `GET /api/v1/cloud/agents` to include archived Agents in list results.
* They remain retrievable via `GET /api/v1/cloud/agents/{agent_id}`.
* The operation is idempotent; archiving an already-archived Agent does not raise an error.
* Archiving does not increment the Agent `version` and does not create a version snapshot.

## Related

<CardGroup cols={2}>
  <Card title="Agent setup" icon="user-gear" href="/cloud-agents/define-agent">
    Create a reusable, versioned agent configuration.
  </Card>
</CardGroup>