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, 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 (name)

• Description (description)

• System prompt (systemPrompt)

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 the properties for your agent. The API requires only three mandatory fields:

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

• description – Summary of what the agent does

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

All other fields, such as multilingual messages and model configuration, are optional.

Minimal configuration example:

{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries and provides product information",
  "systemPrompt": "You are a helpful customer support specialist. Answer questions about our products with accuracy and professionalism. Always be polite and offer clear solutions."
}

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",  
   "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."
}

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 clear solutions.",
  "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://api.swiftask.fr/admin/agent/create \
  -H "Authorization: Bearer xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries and provides product information",
    "systemPrompt": "You are a helpful customer support specialist. Answer questions about our products with accuracy and professionalism.",
    "greetingMessage": "Hello! How can I help you today?",
    "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. Answer questions about our products with accuracy and professionalism.",
    "greetingMessage": "Hello! How can I help you today?",
    "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?",
    "createdAt": "2026-04-20T08:11:03.356Z"
  }
}

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

Error response (400):

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

Available API fields

The Create Agent API supports the following fields:

Required fields

Optional fields

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",  "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?",  "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",
  "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.",
  "model": "claude-sonnet-4-6",
  "temperature": 0.6,
  "questionStarter": [
    "Tell me about your company",
    "What is your budget range?",
    "When do you need this solution?"
  ]
}

Strategic analysis assistant

Deploy high-reasoning analytical agents for internal intelligence and reporting.

{
  "name": "Strategic Analyst",
  "description": "Synthesizes market data and structures analytical reports",
  "systemPrompt": "You are an internal strategic analyst. Synthesize information accurately, identify edge cases, and highlight key recommendations.",
  "model": "claude-opus-4-6",
  "temperature": 0.3,
  "enableMemorySession": true,
  "departement": "Strategy"
}

Tips & best practices

• Keep system prompts detailed: Clearly outline boundaries, tone, and what the agent should do when information is unavailable.

• Select the right model: Use fast models like gpt-4o or gemini-3.1-pro for high-volume customer queries, and deep reasoning models like claude-opus-4-6 for complex analysis.

• Save agent slugs: Keep the generated agent slug to connect it to workflows, chat sessions, or automations.

Troubleshooting

Error: "Missing required field: systemPrompt"

Cause: One of the mandatory fields (name, description, or systemPrompt) was omitted in the request body.

Solution: Ensure all three mandatory properties are included with valid string values.

Error: "Invalid authorization token"

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

Solution:

1. Verify you created the API key from Account settings > API

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

3. Check that you copied the entire key correctly without leading or trailing spaces

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 to use agents from an API

• Available models – Select the LLM model for your agent