Ways to send requests to Swiftask agents

Overview

Swiftask offers several methods to send requests to your AI agents. Each approach is optimized for different use cases: integrations into existing applications, external automations, or interactions via email. You can choose the method that best fits your architecture and needs.

1. OpenAI SDK (Recommended method)

What it is

The simplest and most flexible method. Your Swiftask agents are compatible with official OpenAI SDKs (Python, JavaScript, Node.js, TypeScript, etc.). You can use the OpenAI code you already know, but point it to Swiftask.

When to use it

• You already have OpenAI code and want to reuse the same patterns

• You're integrating agents into existing applications

• You're batch processing documents with Python or JavaScript

• You want real-time streaming for better UX

Configuration

Base URL: https://api.swiftask.fr/v1

Authentication: Swiftask API key (available in Account Settings → API)

Model parameter: Your agent's slug (available in Agent Settings → API tab)

Python example

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.swiftask.fr/v1"
)

response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[{"role": "user", "content": "Hello, how can I help you ?"}]
)

print(response.choices[0].message.content)

JavaScript example

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'YOUR_API_KEY',
    baseURL: 'https://api.swiftask.fr/v1',
});

const response = await client.chat.completions.create({
    model: 'AGENT_SLUG',
    messages: [{ role: 'user', content: 'Hello, how can you help me ?' }]
});

console.log(response.choices[0].message.content);

With streaming (real-time)

# Python with streaming
response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[{"role": "user", "content": "Analyze this document"}],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="")

Full documentation: Access Swiftask agents via OpenAI SDK (recommended)

2. Direct API Access (REST)

What it is

Direct access to the Swiftask REST API for developers who prefer to work without an SDK. You send HTTP POST requests directly to Swiftask endpoints.

When to use it

• You prefer raw HTTP requests without an SDK

• You work in a language not supported by OpenAI SDK

• You have very specific authentication needs

• You're integrating with legacy systems

Configuration

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

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

cURL example

curl -X POST 'https://graphql.swiftask.ai/api/ai/YOUR_AGENT_SLUG' \  -H 'Content-Type: application/json' \  -H 'Authorization: Bearer YOUR_CLIENT_TOKEN' \  -d '{    "input": "Hello, how can you help me?",    "sessionId": 12345,    "messageHistory": [],    "files": [],    "documentAnalysisMode": "SIMPLE"  }'

Main parameters

Full documentation: Access AI and Agent through API

3. Webhook Triggers (External automations)

What it is

A unique HTTP endpoint for your agent. External systems send POST data to this endpoint, and your agent automatically triggers to process the data. Ideal for integrations with external services.

When to use it

• An external system must trigger your agent (Zendesk, Typeform, Stripe, etc.)

• You need event-based automations from external sources

• You're integrating with no-code tools (Zapier, Make, etc.)

• You're processing webhooks from third-party services

Configuration

Create a webhook trigger

1. Navigate to the agent you want to automate

2. In the left sidebar, look for the Automations section

3. Click Triggers (marked as NEW)

4. Click the New Trigger button (red button with + icon)

5. A dialog opens showing trigger type options

6. Select Webhook ("Trigger via HTTP webhook URL. Perfect for integrating with external services.")

7. Enter a descriptive Trigger Name (examples: "Customer Support Ticket", "New Form Submission", "Payment Received")

8. Click Next to review your configuration

9. Click Create Trigger

Get your webhook URL

Once the trigger is created:

1. In the Triggers list, find your webhook trigger

2. Click on it to open the details panel

3. Locate the Webhook URL (POST) field

4. Copy the full URL; this is what your external systems will call

The generated URL looks like this:

https://graphql.swiftask.ai/api/agent-automation/webhook/[unique-id]

The [unique-id] is automatically generated by the system and unique to your trigger.

Example of sending data

curl -X POST https://graphql.swiftask.ai/api/agent-automation/webhook/[unique-id] \
  -H "Content-Type: application/json" \
  -d '{
    "data": "Data you want to send to the agent"
  }'

Common use cases

1. Support ticket automation

• Zendesk creates a ticket → Webhook triggers your agent → Agent responds automatically

2. Form submission processing

• Typeform receives a submission → Webhook triggers your agent → Agent categorizes and routes the request

3. Payment notifications

• Stripe sends a payment notification → Webhook triggers your agent → Agent updates DB and sends confirmation

4. Data enrichment

• CRM creates a lead → Webhook triggers your agent → Agent enriches the lead with external data

Full documentation: Triggers from webhook

4. Email Communication

What it is

Each agent receives a unique email address. You can send emails directly to your agent, which processes them and responds automatically according to its configuration.

When to use it

• You want your agent to process incoming emails

• You are integrating with email management systems (Gmail, Outlook, etc.)

• You need to automatically process documents sent via email

• You want a no-code approach to trigger your agent

Configuration

Each agent has a unique email address (format: agent-slug@swiftask.ai). You can find it in Agent Settings → Triggers.

Common use cases

1. Document processing – Send an invoice by email → Agent processes it automatically

2. Lead capture – Inquiry email → Agent qualifies the lead and updates the CRM

3. Customer support triage – Support email → Agent categorizes and routes to the appropriate team

4. Content collection – Send articles → Agent analyzes and creates a summary

5. Event management – Registration email → Agent processes the registration and sends a confirmation

Capabilities

• Processes all email formats (plain text, HTML, multipart)

• Supports attachments (documents, images, files)

• Handles email conversations (threads)

• Generates intelligent responses based on the knowledge base

• Multi-language

Full documentation: Direct Email Communication with AI Agents

Comparison table

Security best practices

• Secure your API keys: Treat them like passwords. Use environment variables, never hardcode them.

• Set an expiration date: When creating an API key, set an expiration date for security.

• Name your keys: Use descriptive names (ex: "Production Bot", "Testing Bot") to track usage.

• Rotate regularly: Change your API keys periodically.

Next steps

1. Choose your method based on your use case

2. Consult the specific documentation via the provided links

3. Test with cURL or Postman before integrating into your code

4. Implement error handling in your application

5. Monitor credit usage of your Swiftask agents