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

# Create an agent

`POST /agents`

## Request

- Base URL: `https://api.modjo.ai/v2`
- URL: `https://api.modjo.ai/v2/agents`
- Auth: HTTP bearer

Creates an agent in your workspace. The name must be unique within the workspace, and the name of a deleted agent cannot be reused.

## Request body

- CreateAgentRequest
  - `name` string, required: Agent name. Must be unique within the workspace, deleted agents included.
  - `emoji` string, required: Emoji displayed next to the agent name in Modjo
  - `description` string: Short description of what the agent does
  - `instructions` string, required: Instructions the AI follows when the agent is used
  - `enabledTools` string[]: Tools the agent can use: `websearch` searches the web, `call-review` reads the call reviews.

## Response `201`

Agent created

- Agent
  - `uuid` string, uuid, required: Agent UUID
  - `name` string, required: Agent name
  - `emoji` string, required: Agent emoji
  - `description` string, required: Short description of what the agent does
  - `instructions` string, required: Instructions the AI follows when the agent is used
  - `creatorOrigin` 'modjo' | 'user', required: Origin of the agent: `modjo` for agents provided by Modjo, which are read-only, `user` for agents created in your workspace
  - `enabledTools` string[], required: Tools the agent can use
  - `createdById` number, nullable, required: ID of the user who created the agent
  - `createdOn` string, nullable, required: Creation timestamp in ISO 8601 format
  - `modifiedOn` string, nullable, required: Last modification timestamp in ISO 8601 format

## Other responses

- `400`: Invalid request body
- `401`: Authentication failed. The API key is missing or invalid.
- `409`: An agent with this name already exists
- `429`: Rate limit exceeded. Retry after the X-RateLimit-Reset interval.

## Changes

- **2026-10-14** `5aa3b3f47a13`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/modjo/apis/modjo-public-api/changes/agents/post.md)

---

[API](https://skmtc.dev/modjo/apis/modjo-public-api.md) - [All operations](https://skmtc.dev/modjo/apis/modjo-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/modjo/apis/modjo-public-api/revisions/9d2a0a6a5a20?raw)