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

# Create an agent

`POST /v1/agents`

Create a new draft agent owned by the given organization.

`organization_id` is required and you must be a member of it. The agent is created
as a `draft`; publish it with `POST /v1/agents/{agent_id}/publish` once its graph
is ready.

## Request body

- CreateAgentRequest — Request body for creating a draft agent.
  - `organization_id` string, uuid, required — ID of the organization that will own the agent. Required — Profound API keys are user-scoped, so the owning organization must be chosen explicitly. The caller must be a member of this organization.
  - `name` string, required — Display name for the agent. Must be non-empty.
  - `description` string, nullable — Short description of the agent.
  - `graph` object, nullable — Initial workflow graph for the agent's draft version. Optional — an agent can be created empty and have its graph filled in later.

## Response `201`

Successful Response

- Agent — Summary information for an agent.
  - `id` string, uuid, required — Unique ID for the agent.
  - `organization_id` string, uuid, required — Unique ID of the organization that owns the agent.
  - `name` string, required — Display name of the agent.
  - `status` 'draft' | 'published' | 'unknown', required — Current availability status for an agent.
  - `created_at` string, date-time, required — When the agent was created.
  - `description` string, nullable — Short description of the agent, if provided.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cooper-square-technologies/apis/external-api.md) · [All operations](https://skmtc.net/cooper-square-technologies/apis/external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cooper-square-technologies/external-api/revisions/ab03b3c80494/schema)