---
title: "Create and provision an agent"
method: POST
path: "/agents"
tags: ["Agents"]
---

# Create and provision an agent

`POST /agents`

## Request

- Base URL: `https://api-docs.jackhamr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.jackhamr.ai/agents`
- Auth: none declared

Create a new agent in the caller's org and start provisioning.

Returns 201 with the pending agent record; provisioning (Proxmox
container, WireGuard, SSH) then runs in a background task. Poll
``GET /agents/{id}`` to track provisioning status (``pending`` →
``provisioning`` → ``running``). Requires ``owner`` or ``admin`` role.

## Request body

- AgentCreate: Request body for ``POST /api/v1/agents``.
  - `name` string, required
  - `description` string, nullable
  - `template_id` string, nullable
  - `os_template` string, nullable
  - `cores` integer
  - `memory` integer
  - `disk_size` integer
  - `hostname` string, nullable
  - `tags` object, nullable
  - `avatar_id` integer, nullable
  - `subtitle` string, nullable
  - `size_preset_id` string, nullable

## Response `201`

Successful Response

- AgentOut: An agent as returned by ``GET/POST /api/v1/agents``.
  - `id` string, required
  - `organization_id` string, required
  - `name` string, required
  - `description` string, nullable
  - `status` string, required
  - `owner_user_id` string, nullable
  - `allow_cloning` boolean
  - `visible_to_org` boolean
  - `cores` integer, nullable
  - `memory` integer, nullable
  - `disk_size` integer, nullable
  - `template_id` string, nullable
  - `os_template` string, nullable
  - `size_preset_id` string, nullable
  - `sort_order` integer
  - `is_board_clone` boolean
  - `clone_of_agent_id` string, nullable
  - `avatar_image_url` string, nullable
  - `avatar_color` string, nullable
  - `subtitle` string, nullable
  - `tags` object, nullable
  - `metadata` object, nullable
  - `subagent_max_iterations` integer, nullable
  - `error_message` string, nullable
  - `last_error_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `provisioned_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `stopped_at` string, date-time, nullable
  - `hibernated_at` string, date-time, nullable

## Other responses

- `422`: Validation Error

---

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