API reference

Complete reference for all GraphQL types, queries, mutations, and subscriptions in the Swiftask Public Bot API. Use this as a lookup guide when building your integration.

Overview

This reference documents every GraphQL type, input type, query, mutation, and subscription available in the Swiftask API. Each entry includes the GraphQL schema, field descriptions, and common usage examples. Use this guide alongside the practical examples in other guides.

The API is organized into three main categories: data types (what the API returns), input types (what you send to the API), and operations (queries, mutations, and subscriptions).

GraphQL types

TodoChatMessage

Represents a single message in a chat session.

GraphQL Type:

type TodoChatMessage {
  id: Int!
  message: String
  createdAt: DateTime!
  updatedAt: DateTime!
  sessionId: Int!
  sentBy: User!
  isBotReply: Boolean
  files: [File]
  parentMessageId: Int
}

Field descriptions:

Example usage:

const message = {
  id: 12345,
  message: 'What is your pricing?',
  createdAt: '2024-01-29T19:50:13.631Z',
  updatedAt: '2024-01-29T19:50:13.631Z',
  sessionId: 67890,
  sentBy: {
    id: 1,
    firstName: 'John',
    lastName: 'Doe',
  },
  isBotReply: false,
  files: null,
  parentMessageId: null,
};

TodoChatSession

Represents a chat session containing multiple messages.

GraphQL Type:

type TodoChatSession {
  id: Int!
  title: String
  createdAt: DateTime!
  updatedAt: DateTime!
  todoId: Int!
  defaultBotId: Int
  messages: [TodoChatMessage]
  uiLayout: String
}

Field descriptions:

Example usage:

const session = {
  id: 67890,
  title: 'Customer Support',
  createdAt: '2024-01-29T19:50:13.631Z',
  updatedAt: '2024-01-29T20:15:45.123Z',
  todoId: 12345,
  defaultBotId: 789,
  messages: [
    { id: 1, message: 'Hello', isBotReply: false },
    { id: 2, message: 'Hi there!', isBotReply: true },
  ],
  uiLayout: 'DEFAULT',
};

ChatStreamMessage

Represents a chunk of a streaming message.

GraphQL Type:

type ChatStreamMessage {
  messageChunk: String!
  userId: Int!
  id: Int!
  botId: Int!
  botResponseMessageId: Int!
  isStoppable: Boolean!
}

Field descriptions:

Example usage:

// Each subscription event looks like this:
const streamChunk = {
  messageChunk: 'Hello, ',
  userId: 1,
  id: 54321,
  botId: 789,
  botResponseMessageId: 12345,
  isStoppable: true,
};

// Next chunk:
const nextChunk = {
  messageChunk: 'how can I help?',
  userId: 1,
  id: 54322,
  botId: 789,
  botResponseMessageId: 12345,
  isStoppable: true,
};

AgentToolCall

Represents an agent tool call event.

GraphQL Type:

type AgentToolCall {
  tool: String!
  toolImage: String
  botId: Int!
  id: Int!
  status: String!
}

Field descriptions:

Common tool names:

• web_search — Web searching

• calculator — Mathematical calculations

• knowledge_base — Knowledge base lookup

• api_call — External API calls

• database_query — Database queries

• file_search — File searching

Example usage:

const toolCall = {
  tool: 'web_search',
  toolImage: 'https://...',
  botId: 789,
  id: 99999,
  status: 'START',
};

// Later:
const toolEnd = {
  tool: 'web_search',
  toolImage: 'https://...',
  botId: 789,
  id: 100000,
  status: 'END',
};

SyncBotResponse

Response from a synchronous bot request.

GraphQL Type:

type SyncBotResponse {
  text: String!
  botId: Int
  botSlug: String
  isBotError: Boolean
  sessionId: Int
  files: JSON
  sourceMetadatas: JSON
  sources: JSON
  responseJson: JSON
  jobId: String
}

Field descriptions:

Example usage:

const response = {
  text: 'The capital of France is Paris.',
  botId: 789,
  botSlug: 'knowledge-bot',
  isBotError: false,
  sessionId: 67890,
  sources: [
    { title: 'Wikipedia', url: 'https://...' },
    { title: 'Britannica', url: 'https://...' },
  ],
  sourceMetadatas: { count: 2 },
  files: null,
  responseJson: { answer: 'Paris', confidence: 0.99 },
  jobId: 'job_123456',
};

User

Represents a user in the system.

GraphQL Type:

type User {
  id: Int!
  firstName: String
  lastName: String
  email: String
}

Field descriptions:

Input types

NewMessageInput

Input for sending a new message.

GraphQL Input Type:

input NewMessageInput {
  message: String
  todoChatId: Int
  fileIds: [Int]
  mentionedUserId: Int
  mentionedUserIds: [Int]
  mentionedBotId: Int
  parentMessageId: Int
  botPromptId: Int
  sessionId: Int
  command: String
  extraConfig: JSON
  isForAiReply: Boolean
}

Field descriptions:

Example usage:

const messageInput = {
  message: 'What is the weather?',
  sessionId: 67890,
  isForAiReply: true,
};

const messageWithFiles = {
  message: 'Analyze these documents',
  sessionId: 67890,
  fileIds: [101, 102, 103],
  isForAiReply: true,
};

const threadedReply = {
  message: 'Can you elaborate?',
  sessionId: 67890,
  parentMessageId: 12345,
  isForAiReply: true,
};

TodoChatSessionInput

Input for creating or updating a session.

GraphQL Input Type:

input TodoChatSessionInput {
  title: String
  todoChatId: Int
  todoId: Int
  createFromChatAsDataSourceId: Int
  defaultBotId: Int
  fromBotPromptId: Int
  toogleChatGptVersion: Boolean
  autoReplyLMM: Boolean
  chatCollectionId: Int
  uiLayout: String
}

Field descriptions:

Example usage:

const basicSession = {
  title: 'Support Chat',
  todoId: 12345,
};

const sessionWithBot = {
  title: 'Sales Inquiry',
  todoId: 12345,
  defaultBotId: 789,
};

const compactSession = {
  title: 'Quick Chat',
  todoId: 12345,
  uiLayout: 'COMPACT',
};

BotCustomConfigInput

Input for custom bot configuration.

GraphQL Input Type:

input BotCustomConfigInput {
  botId: Int!
  sessionId: Int
  model: String
  temperature: Float
}

Field descriptions:

Example usage:

const botConfig = {
  botId: 123,
  sessionId: 67890,
  model: 'gpt-4',
  temperature: 0.7,
};

Queries

getTodoChatSessions

Get a paginated list of chat sessions.

GraphQL Query:

query GetTodoChatSessions($todoId: Float!, $limit: Int, $offset: Int) {
  getTodoChatSessions(todoId: $todoId, limit: $limit, offset: $offset) {
    sessions {
      id
      title
      createdAt
      updatedAt
      defaultBotId
    }
    totalCount
  }
}

Parameters:

Returns: Object with sessions array and totalCount

Example:

const result = await client.query({
  query: gql`
    query GetTodoChatSessions($todoId: Float!, $limit: Int, $offset: Int) {
      getTodoChatSessions(todoId: $todoId, limit: $limit, offset: $offset) {
        sessions {
          id
          title
          createdAt
        }
        totalCount
      }
    }
  `,
  variables: { todoId: 12345, limit: 20, offset: 0 },
});

console.log(`Total sessions: ${result.data.getTodoChatSessions.totalCount}`);

getOneTodoChatSession

Get details of a specific session including all messages.

GraphQL Query:

query GetOneTodoChatSession($sessionId: Float!) {
  getOneTodoChatSession(sessionId: $sessionId) {
    id
    title
    createdAt
    updatedAt
    defaultBotId
    todoId
    messages {
      id
      message
      createdAt
      sentBy {
        id
        firstName
      }
      isBotReply
    }
  }
}

Parameters:

Returns: Complete TodoChatSession object with messages

getOrCreateUserStartTodoChatSession

Get or create the default starter session for a user.

GraphQL Query:

query GetOrCreateUserStartTodoChatSession($botSlug: String) {
  getOrCreateUserStartTodoChatSession(botSlug: $botSlug) {
    id
    title
    defaultBotId
    todoId
  }
}

Parameters:

Returns: TodoChatSession object (created if doesn't exist)

getSearchTodoChatSessions

Search chat sessions by query string.

GraphQL Query:

query GetSearchTodoChatSessions($todoId: Float!, $searchQuery: String) {
  getSearchTodoChatSessions(todoId: $todoId, searchQuery: $searchQuery) {
    id
    title
    createdAt
  }
}

Parameters:

Returns: Array of matching TodoChatSession objects

getSpeechFromText

Get audio URL for text-to-speech conversion.

GraphQL Query:

query GetSpeechFromText($messageId: Float!) {
  getSpeechFromText(messageId: $messageId)
}

Parameters:

Returns: Audio URL string

Mutations

sendNewMessage

Send a new message and trigger streaming response.

GraphQL Mutation:

mutation SendNewMessage($newMessageData: NewMessageInput!) {
  sendNewMessage(newMessageData: $newMessageData) {
    id
    message
    createdAt
    sessionId
    sentBy {
      id
      firstName
      lastName
    }
    isBotReply
  }
}

Parameters:

Returns: TodoChatMessage object

Example:

const { data } = await client.mutate({
  mutation: gql`
    mutation SendNewMessage($newMessageData: NewMessageInput!) {
      sendNewMessage(newMessageData: $newMessageData) {
        id
        message
      }
    }
  `,
  variables: {
    newMessageData: {
      message: 'Hello!',
      sessionId: 67890,
      isForAiReply: true,
    },
  },
});

syncBotRequest

Send message and get complete response (non-streaming).

GraphQL Mutation:

mutation SyncBotRequest($newMessageData: NewMessageInput!) {
  syncBotRequest(newMessageData: $newMessageData) {
    text
    botId
    botSlug
    isBotError
    sessionId
    files
    sourceMetadatas
    sources
    responseJson
    jobId
  }
}

Parameters:

Returns: SyncBotResponse object

regenerateResponse

Regenerate the bot's response for a message.

GraphQL Mutation:

mutation RegenerateResponse($messageId: Float!) {
  regenerateResponse(messageId: $messageId) {
    id
    message
    createdAt
  }
}

Parameters:

Returns: TodoChatMessage object (new response)

stopAIResponse

Stop ongoing AI response generation.

GraphQL Mutation:

mutation StopAIResponse($sessionId: Float!, $botId: Float!) {
  stopAIResponse(sessionId: $sessionId, botId: $botId)
}

Parameters:

Returns: Boolean (true if stopped successfully)

retryBotMessage

Retry sending a message that failed.

GraphQL Mutation:

mutation RetryBotMessage($sessionId: Float!) {
  retryBotMessage(sessionId: $sessionId)
}

Parameters:

Returns: Boolean (true if retry succeeded)

createTodoChatSession

Create a new chat session.

GraphQL Mutation:

mutation CreateTodoChatSession($data: TodoChatSessionInput!) {
  createTodoChatSession(data: $data) {
    id
    title
    createdAt
    defaultBotId
    todoId
  }
}

Parameters:

Returns: TodoChatSession object

updateTodoChatSession

Update an existing session.

GraphQL Mutation:

mutation UpdateTodoChatSession($data: TodoChatSessionInput!, $id: Float!) {
  updateTodoChatSession(data: $data, id: $id) {
    id
    title
    updatedAt
  }
}

Parameters:

Returns: TodoChatSession object

deleteTodoChatSession

Delete a single session.

GraphQL Mutation:

mutation DeleteTodoChatSession($id: Float!) {
  deleteTodoChatSession(id: $id) {
    id
  }
}

Parameters:

Returns: TodoChatSession object

deleteManyTodoChatSession

Delete multiple sessions in one operation.

GraphQL Mutation:

mutation DeleteManyTodoChatSession($ids: [Int!]!) {
  deleteManyTodoChatSession(ids: $ids)
}

Parameters:

Returns: Number of deleted sessions

updateTodoChatSessionCustomBotConfig

Update bot configuration for a session.

GraphQL Mutation:

mutation UpdateCustomBotConfig($data: BotCustomConfigInput!) {
  updateTodoChatSessionCustomBotConfig(data: $data) {
    id
  }
}

Parameters:

Returns: TodoChatSession object

Subscriptions

onMessageStream

Subscribe to real-time message streaming.

GraphQL Subscription:

subscription OnMessageStream($sessionId: Float!) {
  onMessageStream(sessionId: $sessionId) {
    messageChunk
    userId
    id
    botId
    botResponseMessageId
    isStoppable
  }
}

Parameters:

Emits: ChatStreamMessage objects

newMessage

Subscribe to new complete messages.

GraphQL Subscription:

subscription NewMessage($sessionId: Float!) {
  newMessage(sessionId: $sessionId) {
    id
    message
    createdAt
    sentBy {
      firstName
    }
    isBotReply
  }
} 

Parameters:

Emits: TodoChatMessage objects

newIntermediateMessage

Subscribe to intermediate messages (thinking steps).

GraphQL Subscription:

subscription NewIntermediateMessage($sessionId: Float!) {
  newIntermediateMessage(sessionId: $sessionId) {
    id
    message
    createdAt
    isBotReply
  }
}

Parameters:

Emits: TodoChatMessage objects

onAgentToolCall

Subscribe to agent tool call events.

GraphQL Subscription:

subscription OnAgentToolCall($sessionId: Float!) {
  onAgentToolCall(sessionId: $sessionId) {
    tool
    toolImage
    botId
    id
    status
  }
}

Parameters:

Emits: AgentToolCall objects

userTyping

Subscribe to user typing events.

GraphQL Subscription:

subscription UserTyping($sessionId: Float!) {
  userTyping(sessionId: $sessionId) {
    id
    firstName
    lastName
  }
}

Parameters:

Emits: User objects

botAnalyzingDatasources

Subscribe to bot analyzing datasource events.

GraphQL Subscription:

subscription BotAnalyzingDatasources($sessionId: Float!) {
  botAnalyzingDatasources(sessionId: $sessionId) {
    id
    firstName
  }
}

Parameters:

Emits: User objects

API endpoints

REST endpoints

Base URL: https://graphql.swiftask.ai

GraphQL endpoints

Base URL: https://graphql.swiftask.ai (HTTP) or wss://graphql.swiftask.ai (WebSocket)

Required headers

All GraphQL requests must include these headers:

WebSocket connections use connectionParams instead of headers:

connectionParams: {
  authorization: `Bearer ${accessToken}`,
  workspaceId: workspaceId,
}

Common patterns

Pagination

When listing sessions, use limit and offset for pagination:

// Get first 20 sessions
const page1 = await client.query({
  variables: { todoId, limit: 20, offset: 0 },
});

// Get next 20 sessions
const page2 = await client.query({
  variables: { todoId, limit: 20, offset: 20 },
});

// Get total count
const totalCount = page1.data.getTodoChatSessions.totalCount;
const totalPages = Math.ceil(totalCount / 20);Error handling

All operations can fail. Handle errors consistently:

try {
  const { data } = await client.mutate({ mutation });
  return data;
} catch (error) {
  if (error.graphQLErrors?.length > 0) {
    console.error('GraphQL Error:', error.graphQLErrors[0].message);
  } else if (error.networkError) {
    console.error('Network Error:', error.networkError);
  } else {
    console.error('Unknown Error:', error);
  }
  throw error;
}

Null handling

Some fields are optional. Always check for null:

const message = data.sendNewMessage;
if (message.files) {
  // Process files
}

if (message.parentMessageId) {
  // This is a threaded reply
}