---
title: "Create an agent (or get-or-create by name)"
method: POST
path: "/v1/agents"
---

# Create an agent (or get-or-create by name)

`POST /v1/agents`

## Request

- Base URL: `https://api.plori.ai`
- URL: `https://api.plori.ai/v1/agents`
- Auth: HTTP bearer

Creates a cloud agent owned by the authenticated account. With `if_exists: "return"` this is get-or-create: if an agent with the same name exists, it is returned (200, `existing: true`) instead of creating a duplicate. Prefer this and one long-lived agent. The owner is always the credential's account; a `user_id` in the body is ignored.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `name` string, required
  - `model` string: Model slug; omit for the Plori Router default.
  - `config` object: Opaque agent config; defaults to {}.
  - `if_exists` 'return' | 'error': "return" = get-or-create by name; "error" (default) = always create.
  - `kind` 'compatibility' | 'independent': Independent identities run only as Workspace members. Omit for a compatibility Agent.

## Response `200`

Existing agent returned (get-or-create hit).

- object
  - `id` string, uuid
  - `user_id` string, uuid
  - `name` string
  - `backend` string
  - `model` string
  - `config` object
  - `entity_disk_id` string
  - `status` string: Warm-session state when known: warming, ready, or sleeping.
  - `deleting` boolean: True while this agent's disk is still being erased. The agent offers no actions except deletion itself, which is idempotent and the only way to finish a stuck one.
  - `deleting_since` string, date-time, nullable: When the erasure was first asked for. Absent when the agent is not being deleted.
  - `created_at` string, date-time
  - `existing` boolean

## Other responses

- `201`: Agent created.
- `400`: Malformed request.
- `401`: Missing or invalid credential.
- `403`: Plan does not allow the requested model tier.
- `429`: Per-plan agent cap reached. `Retry-After: 60`.

## Changes

- **2026-10-20** `2234a20f0150`: 2 warning
  - removed the optional property `allOf[#/components/schemas/Agent]/moving` from the response with the `200` status
  - removed the optional property `moving` from the response with the `201` status

[Operation history](https://skmtc.dev/plori/apis/plori-rest-api/changes/v1/agents/post.md)

---

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