# Folder create agent

> Create an agent in a team or workspace.

- Source: https://www.taskade.com/docs/rest/folder-create-agent
- Section: REST API
- Endpoint: `POST /folders/{folderId}/agents` (API v1)
- Index of all pages: https://www.taskade.com/docs/llms.txt

## POST `/folders/{folderId}/agents`

Create an agent in a team or workspace.

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

### 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
```

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `folderId` | path | `string` | Yes | — |

### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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/v1/folders/<folderId>/agents" \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"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 | — |

#### `4XX` — Error description

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` | Yes | — |
| `message` | `string` | Yes | — |
| `code` | `string` | Yes | — |
| `statusMessage` | `string` | Yes | — |
| `featureId` | `string` | No | The plan entitlement the request needs, set on some PAYMENT_REQUIRED errors. |

### 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. Bundle import and export run under tighter limits than regular reads and writes, so schedule bulk transfers accordingly. See [Rate limits](https://www.taskade.com/docs/getting-started/rest-api-guide#rate-limits).