Create an AI agent via API

Overview

The Create Agent API endpoint lets you build and deploy AI agents directly from your application. Instead of manually configuring agents in the Swiftask interface, you can automate agent creation with a single REST request. This is ideal for platforms that integrate Swiftask, SaaS products that need white-label agents, or teams that manage many agents across different projects.

Each agent you create is a complete, independent AI assistant with its own name, system prompt, objectives, and optional knowledge bases and skills. You control every aspect through the API.

Prerequisites

Before calling the Create Agent API, ensure you have:

1. A Swiftask workspace on a paid plan (Starter, Professional, or Enterprise)

2. Owner or Admin role in your workspace

3. API key (see "Getting your API key" below)

4. Basic HTTP knowledge – Understanding of REST API requests and JSON

5. Required agent information:

• Agent name

• Description (English)

• Description (French)

• System prompt

• Greeting message (English)

• Greeting message (French)

Getting your API key

To authenticate API requests, you must create an API key from your account settings:

• Click on your account settings in the bottom-left menu

• Go to account settings > API

• Click on "Create a new API key"

• Copy the generated API key and store it securely

Important: Keep your API key secure—anyone with access to it can make API requests on behalf of your account and consume your credits. Treat it like a password.

Step-by-step guide

Step 1: Prepare your agent configuration

Define all required properties for your agent. The API requires six mandatory fields:

• name – A clear, descriptive name (e.g., "Customer Support Bot")

• description – English description of what the agent does

• descriptionFR – French description of what the agent does

• systemPrompt – Detailed instructions that define the agent's role, behavior, and rules

• greetingMessage – Welcome message in English when users start a chat

• greetingMessageFR – Welcome message in French when users start a chat

Example configuration:

{  
   "name": "Customer Support Agent",  
   "description": "Handles customer inquiries and provides product information",  
   "descriptionFR": "Gère les demandes des clients et fournit des informations 
                     sur les produits",  
   "systemPrompt": "You are a helpful customer support specialist. Answer 
                    questions about our products with accuracy and 
                    professionalism. Always be polite and offer solutions. If you 
                    don't know the answer, ask the customer to contact our 
                    support team.",  
   "greetingMessage": "Hello! How can I help you today?",  
   "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?"
}

Step 2: Make the API request

Endpoint: POST https://api.swiftask.fr/admin/agent/create

Headers:

Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json

Optional header:

x-workspace-id: {workspaceId}

Important: The x-workspace-id header is optional. Include it only if you want to create the agent in a specific workspace where you have Admin or Owner access. Without it, the agent will be created in your default workspace.

Request body (required fields only):

{  
   "name": "Customer Support Agent",  
   "description": "Handles customer inquiries and provides product information",  
   "descriptionFR": "Gère les demandes des clients et fournit des informations   
                     sur les produits",  
   "systemPrompt": "You are a helpful customer support specialist. Answer 
                     questions about our products with accuracy and 
                     professionalism. Always be polite and offer solutions. If 
                     you don't know the answer, ask the customer to contact our 
                     support team.",  
   "greetingMessage": "Hello! How can I help you today?",
   "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?"
}

Request body (with optional fields):

{  
   "name": "Customer Support Agent",  
   "description": "Handles customer inquiries and provides product information",  
   "descriptionFR": "Gère les demandes des clients et fournit des informations 
                     sur les produits", 
   "systemPrompt": "You are a helpful customer support specialist. Answer 
                    questions about our products with accuracy and 
                    professionalism. Always be polite and offer solutions. If you 
                    don't know the answer, ask the customer to contact our 
                    support team.",  
   "greetingMessage": "Hello! How can I help you today?",  
   "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?",  
   "profilePicture": "https://example.com/agent-avatar.png",  
   "departement": "Support",  
   "model": "gpt-4o",  
   "temperature": 0.7,  
   "ragRetrievalTopKChunk": 5, 
   "ragDefaultChunkSize": 512,  
   "enableMemorySession": true,   
   "questionStarter": [    
      "What are your office hours?",    
      "How do I reset my password?"  
    ]
}

Complete cURL example:

curl -X POST \  https://graphql.swiftask.ai/admin/agent/create \  -H "Authorization: Bearer sk_YOUR_API_KEY_HERE" \  -H "Content-Type:  
 application/json" \  -d '{    
    "name": "Customer Support Agent",    
    "description": "Handles customer inquiries and provides product information",        
    "descriptionFR": "Gère les demandes des clients et fournit des informations 
                     sur les produits",    
    "systemPrompt": "You are a helpful customer support specialist. Answer 
                      questions about our products with accuracy and 
                      professionalism. Always be polite and offer solutions. If 
                      you do not know the answer, ask the customer to contact our 
                      support team.",
    "greetingMessage": "Hello! How can I help you today?",       
    "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?",    
    "model": "gpt-4o",    
    "temperature": 0.7,    
    "enableMemorySession": true  
}'

Step 3: Handle the response

Success response (201):

{  
   "success": true,  
   "data": {    
      "id": "agent_789",    
      "name": "Customer Support Agent",    
      "slug": "customer-support-agent-xyz",    
      "description": "Handles customer inquiries and provides product 
                      information",    
      "descriptionFR": "Gère les demandes des clients et fournit des informations 
                        sur les produits",    
      "systemPrompt": "You are a helpful customer support specialist...",      
      "greetingMessage": "Hello! How can I help you today?",    
      "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?",    
      "createdAt": "2026-04-20T08:11:03.356Z",    
      "status": "active"  
   }
}

Save the agent id and slug for future API calls. The slug is the unique identifier you'll use to reference this agent.

Error response (400):

{  
   "success": false,  
   "error": {    
      "code": "INVALID_REQUEST",    
      "message": "Missing required field: descriptionFR"  
    }
}

Available API fields

The Create Agent API supports the following fields:

Required fields

Optional fields

Field recommendations by use case

temperature – Controls response creativity:

• 0.0–0.3: Deterministic (ideal for customer support, FAQ answering)

• 0.4–0.7: Balanced (ideal for general tasks, default is 0.7)

• 0.8–1.0: Creative (ideal for brainstorming, content creation)

ragRetrievalTopKChunk – Number of knowledge base chunks to retrieve:

• Higher values = more context but may include irrelevant information

• Recommended: 5 for most cases, 10 for complex topics

• Increase if answers are incomplete

ragDefaultChunkSize – Size of knowledge base chunks:

• Higher = larger chunks with more context per chunk

• Lower = smaller chunks with more focused information

• Default 512 works well for most documents

enableMemorySession – Let agents remember conversation context:

• Useful for multi-turn conversations and personalized interactions

• Disable for stateless agents (FAQ answering) or privacy-sensitive applications

questionStarter – List of example questions to help users:

"questionStarter": [  
     "What are your office hours?",  
     "How do I reset my password?",  
     "What products do you offer?"
]

Practical use cases

Customer support automation

Create a support agent with your product documentation as a knowledge base. The agent answers FAQs, troubleshoots issues, and escalates complex problems to human agents.

{  
    "name": "Support Bot",  
    "description": "Answers customer questions about our product",   
    "descriptionFR": "Répond aux questions des clients sur notre produit",  
    "systemPrompt": "You are a support specialist. Use only the provided 
                     knowledge base to answer questions. If the answer is not in 
                     the knowledge base, tell the customer to contact 
                     support@company.com.",  
     "greetingMessage": "Hi! How can I help you?",  
     "greetingMessageFR": "Bonjour ! Comment puis-je vous aider ?",  
     "model": "gpt-4o",  
     "temperature": 0.3,  
     "enableMemorySession": true
}

Sales qualification

Build a sales agent that qualifies leads by asking qualifying questions and gathering contact information.

{  
     "name": "Sales Qualification Bot",  
     "description": "Qualifies sales leads and collects information",       
     "descriptionFR": "Qualifie les prospects et collecte les informations",  
     "systemPrompt": "You are a sales specialist. Qualify leads by asking about  
                      their company size, industry, and budget. Be friendly and 
                      professional. Collect their name and email before ending 
                      the conversation.", 
     "greetingMessage": "Hi! I'm here to learn about your needs. What brings you 
                         here today?",  
     "greetingMessageFR": "Bonjour ! Je suis ici pour en savoir plus sur vos 
                           besoins. Qu'est-ce qui vous amène ?",  
     "model": "gpt-4o",  
     "temperature": 0.6,  
     "questionStarter": [    
              "Tell me about your company",    
              "What's your budget range?",    
              "When do you need this solution?"  ]
}

Internal knowledge assistant

Create an agent that helps employees find company information, policies, and procedures from your internal knowledge base.

{  
    "name": "Internal Knowledge Assistant",  
    "description": "Helps employees find company information and policies",   
    "descriptionFR": "Aide les employés à trouver les informations et les 
                      politiques de l'entreprise",  
    "systemPrompt": "You are an internal knowledge assistant. Help employees find    
                     company policies, procedures, and information. Be helpful 
                     and accurate. Direct them to HR or management if they have 
                     questions outside your scope.",  
    "greetingMessage": "Hello! I'm here to help you find company information.",  
    "greetingMessageFR": "Bonjour ! Je suis ici pour vous aider à trouver les 
                          informations de l'entreprise.",  
    "model": "gpt-4o",  
    "temperature": 0.3,  
    "enableMemorySession": true,  
    "departement": "HR"
}

Troubleshooting

Error: "Missing required field: descriptionFR"

Cause: You didn't include the descriptionFR field in your request body.

Solution: Add a descriptionFR field with a French description of your agent. Example: "descriptionFR": "Un assistant utile pour répondre aux questions."

Error: "Missing required field: greetingMessageFR"

Cause: You didn't include the greetingMessageFR field in your request body.

Solution: Add a greetingMessageFR field with a French greeting message. Example: "greetingMessageFR": "Bonjour ! Comment puis-je vous aider ?"

Error: "Invalid authorization token"

Cause: Your API key is missing, expired, or incorrect.

Solution:

1. Verify you created the API key from Profile / Info-user → API / Developer section

2. Ensure the API key is passed in the Authorization: Bearer {API_KEY} header

3. Check that you copied the entire key correctly (no extra spaces)

4. Create a new API key if the current one is compromised

Error: "Missing header: Content-Type"

Cause: The Content-Type header is missing from your request.

Solution: Add the Content-Type: application/json header to all requests.

Additional resources

• API introduction – Get your authentication credentials and learn the basics

• API agent - How use agent from an Api

• Available Models - Select the LLM model for your agent