API Introduction

The Swiftask API allows developers to programmatically interact with Swiftask AI agents. You can send messages, manage conversations, attach files, and receive AI-generated responses through simple HTTP endpoints.

Overview

The Swiftask API enables you to:

• Send messages to AI agents and receive responses

• Manage conversation history across sessions

• Attach and process files (documents, images, etc.)

• Configure document analysis modes (SIMPLE or ADVANCED) for file processing

• Track usage and credit consumption per request

• Manage widget conversations and feedback

The API is designed for developers who want to integrate Swiftask AI agents into their own applications, automate workflows, or build custom solutions on top of Swiftask.

Prerequisites

To use the Swiftask API, you need:

• A Swiftask account (sign up at swiftask.ai)

• Access to a workspace

• An AI agent created in your workspace

• Your agent's Client Token and Slug (unique identifier)

Step-by-Step Guide

1. Get Your API Credentials

Each AI agent in Swiftask has its own API credentials that you'll need for authentication.

Find your API token and slug:

1. Open your agent in Swiftask

2. Navigate to the agent's settings

3. Click on Développeur (Developer) in the left sidebar

4. You'll see two important values:

• Client token de l'agent: Your API authentication token (e.g., 91ae5e07-1e98-466e-af41-e88b550692b8)

• Slug unique de l'agent: Your agent's unique identifier (e.g., blank-templatexlxjz)

Important: Keep your token secure. Anyone with access to your token can make API requests on behalf of your agent and consume your credits.

2. Understand Authentication

All API requests must include authentication. There are two authentication methods depending on your use case:

Authentication Method 1: Bearer Token (for server-to-server)

Include the token in your request headers:

Authorization: Bearer YOUR_CLIENT_TOKEN
Content-Type: application/json

Authentication Method 2: Client Token in Query (for widget requests)

Include the token as a query parameter:

?clientToken=YOUR_CLIENT_TOKEN 

3. API Base URL

All API requests should be sent to:

https://graphql.swiftask.ai/api

4. Make Your First API Request

Here's a basic example of sending a message to your AI agent:

cURL example:

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

Replace:

• blank-templatexlxjz with your agent's slug

• YOUR_CLIENT_TOKEN with your client token

Available APIs

1. Chat API

Send messages to your AI agent and receive responses.

Endpoint: POST /api/ai/{slug}

Authentication: Bearer token in Authorization header

Request body:

Response:

{
  "text": "Agent response here",
  "botId": 123,
  "botSlug": "agent-slug",
  "sessionId": 1001,
  "totalBotUsage": 45,
  "files": [],
  "isBotError": false,
  "tokenUsage": {
    "inputTokens": 150,
    "outputTokens": 300,
    "totalTokens": 450
  }
}

Key features:

• Send text messages to your agent

• Attach files for analysis (documents, images, etc.)

• Maintain conversation context with message history

• Configure document analysis modes (SIMPLE or ADVANCED)

• Track sessions across multiple requests

• Monitor token usage and credit consumption

2. Widget Chat API

Send messages from a public widget or embedded interface.

Endpoint: POST /api/widget/ai

Authentication: clientToken in query parameter

Request body:

Example:

curl -X POST 'https://graphql.swiftask.ai/api/widget/ai?clientToken=YOUR_CLIENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": "Tell me about your products",
    "sessionId": "user-session-123"
  }'

3. Widget Configuration API

Retrieve widget appearance and configuration.

Endpoint: GET /api/widget/config

Authentication: clientToken in query parameter

Example:

curl 'https://graphql.swiftask.ai/api/widget/config?clientToken=YOUR_CLIENT_TOKEN'

Response: Widget appearance settings (colors, avatar, etc.)

4. Widget Feedback API

Send feedback on agent responses.

Endpoint: POST /api/widget/feedback

Authentication: clientToken in query parameter

Request body:

Example:

curl -X POST 'https://graphql.swiftask.ai/api/widget/feedback?clientToken=YOUR_CLIENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "feedback": "POSITIVE",
    "comment": "Very helpful response!",
    "sessionId": 12345
  }'

5. Message Like/Dislike API

Send like or dislike feedback on individual messages.

Endpoint: POST /api/widget/like-dislike

Request body:

Example:

curl -X POST 'https://graphql.swiftask.ai/api/widget/like-dislike' \
  -H 'Content-Type: application/json' \
  -d '{
    "messageId": 5678,
    "feedback": "POSITIVE"
  }'

6. Get Conversation API

Retrieve a conversation by session ID.

Endpoint: GET /api/widget/conversation

Query parameters:

Example:

curl 'https://graphql.swiftask.ai/api/widget/conversation?sessionId=user-session-123'

7. Delete Conversation API

Delete a conversation by session ID.

Endpoint: POST /api/widget/conversation/delete

Query parameters:

Example:

curl -X POST 'https://graphql.swiftask.ai/api/widget/conversation/delete?sessionId=user-session-123' 

8. S3 Signed URL API

Get a signed URL for uploading files to S3.

Endpoint: GET /widget/get-signed-url

Query parameters:

Example:

curl 'https://graphql.swiftask.ai/widget/get-signed-url?fileName=document.pdf' 

Response:

{
  "signedUrl": "https://s3.amazonaws.com/...",
  "fileUrl": "https://..."
}

Authentication & Security

Secure Your API Token

Your API token grants full access to your AI agent. Follow these security best practices:

Do:

• Store tokens in environment variables

• Use secure vaults or secrets management systems

• Rotate tokens regularly

• Implement token-based access controls

Don't:

• Expose tokens in client-side code

• Commit tokens to version control (Git)

• Share tokens publicly

• Hardcode tokens in your application

Environment Variable Example

# .env file
SWIFTASK_API_KEY=91ae5e07-1e98-466e-af41-e88b550692b8
SWIFTASK_AGENT_SLUG=blank-templatexlxjz

import os

api_key = os.getenv('SWIFTASK_API_KEY')
agent_slug = os.getenv('SWIFTASK_AGENT_SLUG')

Request & Response Format

Request Structure

All API requests use JSON format and must include the following headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY  (for /api/ai/*)

Error Handling

Error response format:

{
  "error": "Error message describing what went wrong"
}

Common HTTP status codes:

Troubleshooting

"Unauthorized" Error (401)

Cause: Invalid or missing API token

Solution:

• Verify your token is correct

• Ensure the Authorization header is properly formatted: Bearer YOUR_TOKEN

• Check that your token hasn't been revoked

"Bad Request" Error (400)

Cause: Invalid request body or missing required fields

Solution:

• Verify all required fields are included

• Check that field types match (e.g., input must be a string)

• Validate your JSON formatting

Validation Errors

Session ID must be a string: Ensure sessionId is a string, not a number

Input must be a string: Ensure input is a string, not an object or array

Support & Resources

Need help?

• Developer Community: Join our Discord for API support

• Email Support: Contact support@swiftask.ai

• Documentation: Browse guides at docs.swiftask.ai

• Open a ticket: Help → Open a ticket in the dashboard

Ready to integrate? Start with the Chat API (POST /api/ai/{slug}) to send your first message.