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.
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.