Access AI and agent through API

Swiftask API Documentation

Swiftask is an AI aggregator platform that allows users to access AI capabilities from multiple vendors through a unified interface. This guide provides developers with the information needed to interact with the Swiftask API for sending and receiving AI-generated responses.

Note: "AI", "Bot", and "Agent" refer to the same concept with the Swiftask API.

Authentication

All requests to the Swiftask API require authentication and authorization using an API key. Include the API key in the request headers as follows:

• Header: Authorization: Bearer <swiftask_api_key>

---

Obtaining an API Key

Create an Account:

• Sign up for an account on the Swiftask website if you do not already have one.

• Click on Workspace Information and go to Setting

• In the API section, you can create a new key.

Store Your API Key Safely: The API key is displayed only once following its generation. Be sure to copy and store it securely. If lost, you must generate a new key.

---

Base URL

The base URL for the Swiftask API is:

$$\texttt{https://graphql.swiftask.ai/api}$$

---

API Endpoint

POST /ai/:slug

This endpoint allows you to interact with a specific AI bot identified by its unique slug.

• HTTP Method: POST

• URL Parameter:

  • slug: Unique identifier string for the AI bot (e.g., chatpdf, gpt4).

To find the slug for a specific AI, please go to List of AI and agents accessible via API

• Headers:

  • Content-Type: application/json

  • Authorization: Bearer <swiftask_api_key>

---

Request & Response Details

Request Body

API Request Body Specification

This API endpoint expects the following request body. The body is defined using a Joi schema, which outlines the required fields, optional fields, data types, and constraints.

Request Body Schema

Field	Type	Required	Allowed Values	Description
sessionId	number	No	—	An optional session identifier for tracking.
input	string	Yes	—	The required input message text.
files	array (of BotFileSchema)	No	—	An optional array of file objects following the BotFileSchema structure.
documentAnalysisMode	string	No	SIMPLE, ADVANCED	Optional mode to specify the level of document analysis.
messageHistory	array of objects	No	—	An optional array representing the conversation history. Each entry adheres to the object schema below.

messageHistory Object Schema

Field	Type	Required	Allowed Values	Description
role	string	Yes	user, assistant, system	The role of the message sender.
content	string	Yes	—	The text content of the message.
files	array	No	—	An optional array of file objects following the BotFileSchema.

Files schema (BotFileSchema)

Field Details

Field	Type	Required	Allowed Values / Format	Description
url	string	Yes	Valid URI	The URL of the file. Must be a valid URI.
type	string	No	—	The type or MIME type of the file (e.g., "image/png", "application/pdf").
size	number	No	—	The size of the file in bytes.
name	string	No	—	The name of the file.
id	number	No	—	An identifier for the file.

Example Request JSON

Below is an example of how the request body might be structured:

{
  "sessionId": 12345,
  "input": "Hello, how can I help you?",
  "files": [
    {
      "name": "example.txt",
      "size": 1024,
      "url": "http://example.com/file/example.txt"
    }
  ],
  "documentAnalysisMode": "SIMPLE",
  "messageHistory": [
    {
      "role": "user",
      "content": "What is the weather today?",
      "files": []
    },
    {
      "role": "assistant",
      "content": "It's sunny today!",
      "files": []
    }
  ]
}

CURL example

curl -X POST 'https://swiftask.com/api/ai/{slug}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_key>' \
  -d '{
    "input": "Hello, how can I help you today?",
    "documentAnalysisMode": "SIMPLE",
    "files": [],
    "messageHistory": [
      {
        "role": "user",
        "content": "Hello, how can I help you today?"
      }
    ]
  }'

Replace {slug} with the AI bot slug and <api_key> with your API key.

Python Example

Copyimport requests
import json

url = "https://swiftask.com/api/ai/{slug}"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <api_key>"
}

payload = {
    "input": "Hello, how can I help you today?",
    "documentAnalysisMode": "SIMPLE",
    "files": [],
    "messageHistory": [
        {
            "role": "user",
            "content": "Hello, how can I help you today?"
        }
    ]
}

response = requests.post(url.format(slug="your_slug_here"), headers=headers, data=json.dumps(payload))
print(response.status_code)
print(response.json())

Replace your_slug_here with the AI bot slug and <api_key> with your API key.

---

Node.js Example (Using Axios)

Copyconst axios = require('axios');

const url = "https://swiftask.com/api/ai/{slug}";
const headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer <api_key>"
};

const payload = {
  input: "Hello, how can I help you today?",
  documentAnalysisMode: "SIMPLE",
  files: [],
  messageHistory: [
    {
      role: "user",
      content: "Hello, how can I help you today?"
    }
  ]
};

axios.post(url.replace("{slug}", "your_slug_here"), payload, { headers })
  .then(response => {
    console.log("Status:", response.status);
    console.log("Data:", response.data);
  })
  .catch(error => {
    console.error("Error:", error.response ? error.response.data : error.message);
  });

Replace "your_slug_here" with the AI bot slug and <api_key> with your API key.

Response JSON

• Field Descriptions:

  • $text: AI-generated response.

  • $botSlug: Identifier of the AI bot used.

  • $files: Any associated file data returned by the AI.

  • $additionalMessages: Additional messages provided by the bot.

  • $isBotError: Indicates if there was an error during processing.

  • $sessionId: Unique session identifier.

  • $totalBotUsage: Overall usage count for the session.

  • $usageDetail: Token usage details including input and output tokens.

  • $isSubscriptionUsageLimitReachedMessage: Indicates if subscription limits are reached.

  • $sourceMetadatas: Metadata about information sources used by the bot.

This API documentation covers the main aspects needed to integrate with various AI bots via Swiftask. For further details or support, contact the Swiftask support team.