API Endpoints
Relevant source files
The following files were used as context for generating this wiki page: - [src/app.controller.ts](https://github.com/clearfeed/quix/blob/HEAD/src/app.controller.ts) - [src/slack/slack.controller.ts](https://github.com/clearfeed/quix/blob/HEAD/src/slack/slack.controller.ts) - [src/integrations/integrations.controller.ts](https://github.com/clearfeed/quix/blob/HEAD/src/integrations/integrations.controller.ts) - [src/slack/slack-events-handler.service.ts](https://github.com/clearfeed/quix/blob/HEAD/src/slack/slack-events-handler.service.ts) - [README.md](https://github.com/clearfeed/quix/blob/HEAD/README.md) - [agent-packages/packages/assetpanda/README.md](https://github.com/clearfeed/quix/blob/HEAD/agent-packages/packages/assetpanda/README.md) - [agent-packages/packages/jumpcloud/README.md](https://github.com/clearfeed/quix/blob/HEAD/agent-packages/packages/jumpcloud/README.md) - [src/lib/constants.ts](https://github.com/clearfeed/quix/blob/HEAD/src/lib/constants.ts)The Quix application, built on the Nest.js framework, exposes a set of API endpoints primarily designed to facilitate integration with Slack and manage OAuth flows for various third-party services. These endpoints are the main entry points for external services to communicate with the Quix backend. The core functionality revolves around receiving events and interactions from Slack, handling the installation of the Slack app, and managing authentication callbacks for integrations like Jira, GitHub, and HubSpot.
This document outlines the API endpoints exposed by the main Quix application and also provides insight into the external API endpoints consumed by its integration packages. The system is architected around controllers, with each controller responsible for a specific domain of functionality, such as general application health, Slack communication, or integration management.
Application Endpoints
These endpoints are defined within the main Nest.js application and serve as the primary interface for the Quix service.
Health Check
A single endpoint is provided for monitoring the health of the application.
| Method | Path | Description |
|---|---|---|
GET | /health | A simple health check endpoint. |
Sources: README.md, src/app.controller.ts
Slack Integration Endpoints
These endpoints are crucial for the Quix Slack agent's functionality. They handle events, user interactions, and the app installation process initiated from Slack. The slack_app_manifest.yml file configures the Slack App to use these URLs.
Sources: src/slack/slack.controller.ts, README.md
| Method | Path | Description |
|---|---|---|
POST | /slack/events | Receives events from Slack via the Events API. This includes messages, app mentions, and other workspace activities. It performs URL verification on setup. |
POST | /slack/interactions | Handles interactive components from Slack, such as button clicks, modal submissions, and menu selections. |
GET | /slack/install | The redirect URL for the Slack OAuth flow. It handles the installation of the Quix app into a Slack workspace and saves the necessary credentials. |
GET | /slack/install/finish | A static page or redirect target shown to the user after the installation process is complete. |
Slack Event Handling Flow
The following diagram illustrates the sequence of events when a user mentions the Quix bot in a Slack channel.
This diagram shows how an app_mention event from Slack is processed by Quix, leading to a response generated by the LLM service.
Sources: src/slack/slack.controller.ts:16-18, src/slack/slack-events-handler.service.ts:205-242
Third-Party Integration Endpoints
This controller manages the OAuth 2.0 callbacks for various supported integrations. When a user connects a new tool from the Quix App Home in Slack, they are redirected to the respective service for authorization, which then calls back to one of these endpoints.
Sources: src/integrations/integrations.controller.ts, src/lib/constants.ts:20-193
| Method | Path | Integration | Description |
|---|---|---|---|
GET | /integrations/jira/callback | Jira | Handles the OAuth callback from Atlassian after a user authorizes the app. |
GET | /integrations/github/callback | GitHub | Handles the OAuth callback from GitHub after a user authorizes the app. |
GET | /integrations/hubspot/callback | HubSpot | Handles the OAuth callback from HubSpot after a user authorizes the app. |
GET | /integrations/salesforce/callback | Salesforce | Handles the OAuth callback from Salesforce after a user authorizes the app. |
Integration OAuth Flow (Example: Jira)
This diagram shows the typical flow for connecting a third-party tool that uses OAuth, using Jira as an example.
This diagram illustrates the user journey and backend process for authorizing the Jira integration.
Sources: src/integrations/integrations.controller.ts:23-30, src/slack/views/app_home.ts:422-427
External API Endpoints Consumed
Quix itself acts as a client to numerous external APIs to provide its functionality. The agent-packages contain the logic for these interactions. Below are examples of APIs consumed by some of the integration packages.
AssetPanda
The AssetPanda integration interacts with the AssetPanda v3 API to manage assets, employees, and licenses.
| Method | Endpoint | Description |
|---|---|---|
GET | /v3/users | List users. |
POST | /v3/users | Create a user. |
GET | /v3/groups | List asset groups (e.g., Hardware). |
POST | /v3/groups/{group_id}/objects/search | Search for objects like assets or licenses. |
PATCH | /v3/groups/{group_id}/objects/{object_id} | Update an object (e.g., assign an asset). |
Sources: agent-packages/packages/assetpanda/README.md
JumpCloud
The JumpCloud integration uses its API to manage users, groups, and devices.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/systemusers | List users. |
POST | /api/systemusers | Create a user. |
GET | /api/usergroups | List groups. |
POST | /api/usergroups | Create a group. |
POST | /api/usergroups/{group_id}/members | Assign a user to a group. |
DELETE | /api/usergroups/{group_id}/members | Unassign a user from a group. |
GET | /api/systems | List all devices in the organization. |
Sources: agent-packages/packages/jumpcloud/README.md
Slack
The Slack agent package (@clearfeed-ai/quix-slack-agent) makes extensive use of the Slack Web API to perform actions on behalf of the user.
Function (SlackService) | Slack API Method | Description |
|---|---|---|
listChannels | conversations.list | Lists public channels in the workspace. |
postMessage | chat.postMessage | Posts a new message to a channel. |
replyToThread | chat.postMessage (with thread_ts) | Replies to a specific message thread. |
addReaction | reactions.add | Adds a reaction emoji to a message. |
getChannelHistory | conversations.history | Gets recent messages from a channel. |
getThreadReplies | conversations.replies | Gets all replies in a message thread. |
getUsers | users.list | Gets a list of all users in the workspace. |
getUserProfile | users.profile.get | Gets detailed profile info for a user. |
joinChannel | conversations.join | Joins a Slack channel. |
leaveChannel | conversations.leave | Leaves a Slack channel. |
Sources: agent-packages/packages/slack/src/index.ts, agent-packages/packages/slack/src/tools.ts
Summary
The API endpoints of the Quix application are narrowly focused on enabling its core function as a Slack-integrated AI agent. The primary endpoints handle incoming webhooks from Slack for events and interactions, alongside OAuth callbacks to securely connect with third-party services. This architecture allows the main application to remain a lean and secure gateway, while the complex logic of interacting with external APIs is encapsulated within the modular agent-packages. This separation of concerns is key to the platform's extensibility and maintainability.