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

curl -X POST "https://api.qoder.com/api/v1/cloud/agents/agent_019eXXXX.../archive" \
  -H "Authorization: Bearer $QODER_PAT"

Example response

HTTP 200 OK

{
  "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	Tool configuration list
mcp_servers	array of MCP server	MCP server configuration
skills	array of Skill binding	Skill bindings
metadata	Metadata object	Custom metadata
multiagent	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 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

Agent setup

Create a reusable, versioned agent configuration.