# Create agent

> Create an agent in a team or workspace

- Source: https://www.taskade.com/docs/actions/create-agent
- Section: Action API
- Endpoint: `POST /createAgent` (API v2)
- Index of all pages: https://www.taskade.com/docs/llms.txt

## POST `/createAgent`

Create an agent in a team or workspace

Base URL: `https://www.taskade.com/api/v2`

### Authentication

Send a personal access token or an OAuth 2.0 access token as a bearer token. Create a personal access token at [taskade.com/settings/api](https://www.taskade.com/settings/api).

```http
Authorization: Bearer tskdp_your_token_here
```

### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `folderId` | `string` | Yes | — |
| `name` | `string` | Yes | — |
| `data` | `object` | Yes | — |
| `data.type` | `string` | Yes | Allowed values: `data`, `template`. |
| `data.data` | `object` | Depends | Required when `type` is `data`. |
| `data.data.commands` | `object[]` | Yes | — |
| `data.data.commands[].name` | `string` | Yes | Human-readable name of the command in title case. This should probably be a verb. |
| `data.data.commands[].description` | `string` | No | Short summary for discovery (e.g. progressive disclosure / skill listing). The full instruction stays in `prompt`. |
| `data.data.commands[].prompt` | `string` | Yes | Tell the agent what this command will do. It should be positioned as a direct instruction to the agent. At least 30 words. |
| `data.data.commands[].id` | `string` | Yes | ID based on the name in snake case. |
| `data.data.commands[].mode` | `string` | No | Allowed values: `default`, `plan-and-execute-v1`, `plan-and-execute-v2`. |
| `data.data.description` | `string` | No | Role and purpose of agent, positioned as a direct instruction to the agent. Example: "You are a doctor that helps save lives.". At least 100 words. |
| `data.data.tone` | `string` | No | Allowed values: `authoritative`, `clinical`, `cold`, `confident`, `cynical`, `emotional`, `empathetic`, `formal`, `friendly`, `humourous`, `informal`, `ironic`, `optimistic`, `pessimistic`, `playful`, `sarcastic`, `serious`, `sympathetic`, `tentative`, `warm`, `creative`, `inspiring`, `casual`. |
| `data.data.avatar` | `object` | No | — |
| `data.data.avatar.type` | `string` | Yes | Allowed values: `emoji`. |
| `data.data.avatar.data` | `object` | Yes | — |
| `data.data.avatar.data.value` | `string` | Yes | Pick the most suitable emoji for this agent. |
| `data.data.knowledgeEnabled` | `boolean` | No | — |
| `data.data.language` | `string` | No | The language of the agent, e.g. en-US, zh-Hans |
| `data.data.inputPlaceholder` | `string` | No | — |
| `data.template` | `object` | Depends | Required when `type` is `template`. |
| `data.template.type` | `string` | Yes | Allowed values: `Tasker`, `Researcher`, `Marketer`, `EmailWriter`, `Sales`, `CustomerSupport`, `ProjectManager`, `ContentCreator`, `Copywriter`, `LegalAdvisor`, `SeoSpecialist`, `ProductivityCoach`, `EngineeringExpert`, `Translator`, `Summarizer`, `ResumeBuilder`, `Storyteller`, `Tutor`, `BrandStrategist`, `SocialMediaSpecialist`, `BusinessStrategist`, `FinancialAnalyst`, `HumanResourcesManager`, `DataScientist`, `ITConsultant`, `FinancialAdvisor`, `HealthCoach`, `SustainabilityConsultant`, `UXDesigner`, `QualityAssuranceAnalyst`, `ProductManager`, `GrowthHacker`, `BusinessDevelopmentManager`, `PublicRelationsSpecialist`, `EventPlanner`, `DataAnalyst`, `Editor`, `CEO`, `InterviewCoach`, `TechSupportAdvisor`, `Doctor`, `BlogExpert`, `TweetOptimizer`, `EmailMarketer`, `CourseCreator`, `ScriptCreator`, `ScreenplayWriter`, `Proofreader`, `SalesColdEmailCoach`, `CodeExplainer`, `CreativeWritingCoach`, `AdvertisingCopywriter`, `VideoScriptWriter`, `ProjectArchitect`, `AICouncil`, `Negotiator`, `VCAssociate`, `Books`, `StartupMentor`, `SmallBusiness`, `WebDevelopment`, `PromptEngineer`, `ArticleWriter`, `WorkflowAgent`, `StrategyAgent`, `ViralAgent`, `SOPOnboardingAgent`, `PressReleaseAgent`, `Designer`, `Brainstormer`, `Builder`, `ResearchAnalyst`, `OperationsManager`, `CodeReviewer`, `LeadScorer`, `ContactEnricher`, `ContentStrategist`, `DealMover`, `Estimator`, `DigitalTwin`, `WatchFloorBriefer`, `AnomalySpotter`, `RestockAdvisor`, `AppDoctor`, `RenewalChaser`, `WinBackSpecialist`, `NoShowRescuer`, `AbandonedCartRecoverer`, `ReviewResponder`, `TestimonialHarvester`, `SponsorshipManager`, `CourseLaunchStrategist`, `CurriculumAuthor`, `PersonalizedRoadmapGenerator`, `DispatchCoordinator`, `ProviderNetworkBuilder`, `ClaimsClerk`, `ListingMarketer`, `GrantWriter`, `ComplianceKeeper`, `LeadQualifier`, `ClientOnboardingConcierge`, `PipelineReporter`, `LearnerCoach`. |
| `data.template.avatar` | `object` | No | — |
| `data.template.avatar.type` | `string` | Yes | Allowed values: `emoji`. |
| `data.template.avatar.data` | `object` | Yes | — |
| `data.template.avatar.data.value` | `string` | Yes | Pick the most suitable emoji for this agent. |

A nested field marked Yes is required whenever its parent object is present.

### Example request

```bash
curl -X POST "https://www.taskade.com/api/v2/createAgent" \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folderId":"<folderId>","name":"<name>","data":{"type":"data","data":{"commands":[]}}}'
```

### Responses

#### `200` — Default response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` | Yes | — |
| `item` | `object` | Yes | — |
| `item.id` | `string` | Yes | — |
| `item.name` | `string` | Yes | — |
| `item.space_id` | `string` | Yes | — |
| `item.data` | `object` | Yes | — |
| `item.data.commands` | `object[]` | Yes | — |
| `item.data.commands[].name` | `string` | Yes | Human-readable name of the command in title case. This should probably be a verb. |
| `item.data.commands[].description` | `string` | No | Short summary for discovery (e.g. progressive disclosure / skill listing). The full instruction stays in `prompt`. |
| `item.data.commands[].prompt` | `string` | Yes | Tell the agent what this command will do. It should be positioned as a direct instruction to the agent. At least 30 words. |
| `item.data.commands[].id` | `string` | Yes | ID based on the name in snake case. |
| `item.data.commands[].mode` | `string` | No | Allowed values: `default`, `plan-and-execute-v1`, `plan-and-execute-v2`. |
| `item.data.description` | `string` | No | Role and purpose of agent, positioned as a direct instruction to the agent. Example: "You are a doctor that helps save lives.". At least 100 words. |
| `item.data.tone` | `string` | No | Allowed values: `authoritative`, `clinical`, `cold`, `confident`, `cynical`, `emotional`, `empathetic`, `formal`, `friendly`, `humourous`, `informal`, `ironic`, `optimistic`, `pessimistic`, `playful`, `sarcastic`, `serious`, `sympathetic`, `tentative`, `warm`, `creative`, `inspiring`, `casual`. |
| `item.data.avatar` | `object` | No | — |
| `item.data.avatar.type` | `string` | Yes | Allowed values: `emoji`. |
| `item.data.avatar.data` | `object` | Yes | — |
| `item.data.avatar.data.value` | `string` | Yes | Pick the most suitable emoji for this agent. |
| `item.data.knowledgeEnabled` | `boolean` | No | — |
| `item.data.language` | `string` | No | The language of the agent, e.g. en-US, zh-Hans |
| `item.data.inputPlaceholder` | `string` | No | — |

### Errors

Errors return an `ok: false` envelope. Rate limiting returns `429` with `x-rate-limit-limit`, `x-rate-limit-remaining` and `x-rate-limit-reset` headers. `x-rate-limit-reset` is the number of seconds until the window reopens. `Retry-After` is not sent, so schedule retries from `x-rate-limit-reset`; retrying sooner will fail again.

```json
{ "ok": false, "message": "Unauthorized", "code": "UNAUTHORIZED" }
```

Rate limits for this version: enforced per endpoint; ceilings are not published and can change without notice. A `429` response carries `x-rate-limit-limit`, `x-rate-limit-remaining`, and `x-rate-limit-reset` (seconds until the window reopens). Back off from those headers rather than hardcoding numbers. If you need sustained throughput, prefer batching (operations like `/createTask` accept arrays) over tightening polling loops. See [Rate limits](https://www.taskade.com/docs/getting-started/action-api-guide#rate-limits).