# Create a new agent

> You're reading the Mindset v3 documentation. v3 is no longer sold; this is reference for existing customers. Mindset 4 docs are at /docs.

Create a new agent with full configuration options including personality, formatting, policies, and memory settings.

**POST** `/api/v2/appuid/{appUid}/agents`

Create a new agent with full configuration options including personality, formatting, policies, and memory settings.

## Base URL

Requests go to your region's API host, for example `https://a.api.mindset.ai`. Hosts: `https://a.api.mindset.ai`, `https://b.api.mindset.ai`, `https://c.api.mindset.ai`, `https://d.api.mindset.ai`.

## Authorization

- `x-api-key` (string, required, header)

  Your API key.

## Path parameters

- `appUid` (string, required, path)

  Your application's uid

## Request body

Content type: `application/json`.

- `agentName` (string, required, body)

  Name of the agent

* `agentPurpose` (string, required, body)

  Purpose of the agent

- `templateAgentUid` (string, body)

  UID of an existing agent to use as a template for sources presentation options (citations, references etc)

* `personality` (object, body)

  Agent personality configuration

- `formatting` (object, body)

  Agent response formatting configuration

* `policies` (object, body)

  Agent policy configuration with 10 toggleable policies

- `additionalPolicyRules` (string, body)

  Additional free-form policy rules

* `additionalInformation` (string, body)

  Additional context information for the agent

- `iceBreakerMessage` (string, body)

  Invisible instruction to prompt the agent to greet users in a specific way

* `memory` (object, body)

  Agent memory configuration. Note: Memory access must be enabled at the app level for these settings to take effect.

- `options` (object, body)

  SDK3 display options. Only present for apps with SDK3 enabled (labsSDKV3Beta: true).

* `live` (boolean, body)

  Agent is active and live for end users

  Default: `false`.

- `showPromptLibrary` (boolean, body)

  Show prompt library in SDK UI

  Default: `false`.

* `contextUids` (string\[], body)

  Array of existing context UIDs (max 30)

- `mcpserverUids` (string\[], body)

  Array of existing MCP server UIDs (max 5)

* `planUids` (string\[], body)

  Array of existing plan UIDs (max 20)

- `skillUids` (string\[], body)

  Array of existing skill UIDs (max 20)

* `tags` (string\[], body)

  Array of tags (max 10)

- `access` (string, body)

  Access control mode for this agent

  One of: `openAccess`, `restrictedAccess`. Default: `"restrictedAccess"`.

* `externalTenantId` (string, body)

  External tenant identifier (alphanumeric, underscore, hyphen only)

```json
{
  "agentName": "string",
  "agentPurpose": "string",
  "templateAgentUid": "string",
  "personality": {
    "preset": "friendly",
    "customText": "string"
  },
  "formatting": {
    "preset": "conversational",
    "customText": "string"
  },
  "policies": {
    "focusAndScope": {
      "enabled": true,
      "scope": "string"
    },
    "knowledgeLimits": {
      "enabled": true,
      "themeSpecificAllowance": "string"
    },
    "nonContextSegmentMessage": {
      "enabled": true,
      "message": "string"
    },
    "clarification": {
      "enabled": true
    },
    "recommendations": {
      "enabled": true
    },
    "neutrality": {
      "enabled": true
    },
    "professionalConduct": {
      "enabled": true
    },
    "legalFinancial": {
      "enabled": true
    },
    "safeguarding": {
      "enabled": true,
      "email": "string"
    },
    "feedback": {
      "enabled": true
    }
  },
  "additionalPolicyRules": "string",
  "additionalInformation": "string",
  "iceBreakerMessage": "string",
  "memory": {
    "allowAccess": true,
    "allowContribution": true,
    "miningGuidance": "string"
  },
  "options": {
    "showSourceContent": true,
    "sourceDisplayStyle": "compact",
    "sourceCardType": "segments",
    "showSpeakers": true,
    "showFollowUpQuestions": true,
    "showCitations": true,
    "showQuickReplies": true
  },
  "live": true,
  "showPromptLibrary": true,
  "contextUids": [
    "string"
  ],
  "mcpserverUids": [
    "string"
  ],
  "planUids": [
    "string"
  ],
  "skillUids": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "access": "openAccess",
  "externalTenantId": "string"
}
```

## Responses

### 201

Agent created successfully

```json
{
  "uid": "string",
  "agentName": "string",
  "agentPurpose": "string",
  "personality": {
    "preset": "friendly",
    "customText": "string"
  },
  "formatting": {
    "preset": "conversational",
    "customText": "string"
  },
  "policies": {
    "focusAndScope": {
      "enabled": true,
      "scope": "string"
    },
    "knowledgeLimits": {
      "enabled": true,
      "themeSpecificAllowance": "string"
    },
    "nonContextSegmentMessage": {
      "enabled": true,
      "message": "string"
    },
    "clarification": {
      "enabled": true
    },
    "recommendations": {
      "enabled": true
    },
    "neutrality": {
      "enabled": true
    },
    "professionalConduct": {
      "enabled": true
    },
    "legalFinancial": {
      "enabled": true
    },
    "safeguarding": {
      "enabled": true,
      "email": "string"
    },
    "feedback": {
      "enabled": true
    }
  },
  "additionalPolicyRules": "string",
  "additionalInformation": "string",
  "iceBreakerMessage": "string",
  "memory": {
    "allowAccess": true,
    "allowContribution": true,
    "miningGuidance": "string"
  },
  "options": {
    "showSourceContent": true,
    "sourceDisplayStyle": "compact",
    "sourceCardType": "segments",
    "showSpeakers": true,
    "showFollowUpQuestions": true,
    "showCitations": true,
    "showQuickReplies": true
  },
  "live": true,
  "showPromptLibrary": true,
  "contextUids": [
    "string"
  ],
  "mcpserverUids": [
    "string"
  ],
  "planUids": [
    "string"
  ],
  "skillUids": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "access": "openAccess",
  "externalTenantId": "string",
  "createdAt": "string"
}
```

### 400

Bad Request - Invalid input

### 401

Unauthorized

### 403

Forbidden

### 404

Not Found - Template agent does not exist

### 422

Unprocessable Entity - Validation error

### 500

Internal Server Error

## Example request

```bash
curl -X POST "https://a.api.mindset.ai/api/v2/appuid/{appUid}/agents" \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"agentName":"string","agentPurpose":"string","templateAgentUid":"string","personality":{"preset":"friendly","customText":"string"},"formatting":{"preset":"conversational","customText":"string"},"policies":{"focusAndScope":{"enabled":true,"scope":"string"},"knowledgeLimits":{"enabled":true,"themeSpecificAllowance":"string"},"nonContextSegmentMessage":{"enabled":true,"message":"string"},"clarification":{"enabled":true},"recommendations":{"enabled":true},"neutrality":{"enabled":true},"professionalConduct":{"enabled":true},"legalFinancial":{"enabled":true},"safeguarding":{"enabled":true,"email":"string"},"feedback":{"enabled":true}},"additionalPolicyRules":"string","additionalInformation":"string","iceBreakerMessage":"string","memory":{"allowAccess":true,"allowContribution":true,"miningGuidance":"string"},"options":{"showSourceContent":true,"sourceDisplayStyle":"compact","sourceCardType":"segments","showSpeakers":true,"showFollowUpQuestions":true,"showCitations":true,"showQuickReplies":true},"live":true,"showPromptLibrary":true,"contextUids":["string"],"mcpserverUids":["string"],"planUids":["string"],"skillUids":["string"],"tags":["string"],"access":"openAccess","externalTenantId":"string"}'
```