Integrations

Overview

Praxiom AI integrates with GitHub, Linear, Jira, and Google Drive. Issue tracker integrations follow the same pattern: OAuth connect, resource selection, issue creation from recommendations or execution tickets, and periodic sync. Google Drive provides file search, read, write, and folder listing.

---

GitHub Integration

All GitHub endpoints use the prefix /api/integrations/github.

Connect GitHub

POST /api/integrations/github/connect

Initiate the GitHub OAuth flow. Returns an authorization URL to redirect the user.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace to connect

Response (200 OK)

{
  "auth_url": "https://github.com/login/oauth/authorize?client_id=...&state=...",
  "state": "550e8400-..."
}

OAuth Callback

GET /api/integrations/github/callback

Handles the GitHub OAuth redirect. Exchanges the authorization code for an access token and stores it encrypted. Redirects to the frontend settings page.

Disconnect GitHub

DELETE /api/integrations/github/disconnect

Remove the GitHub connection for a workspace.

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID (query param)

Get Status

GET /api/integrations/github/status

Check if GitHub is connected for a workspace.

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID (query param)

Response (200 OK)

{
  "connected": true,
  "login": "acme-org",
  "repos_selected": 3
}

List Repos

GET /api/integrations/github/repos

List GitHub repositories accessible to the connected account.

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID (query param)

Select Repos

POST /api/integrations/github/repos/select

Select which repositories to use for issue creation and sync.

Create Issue

POST /api/integrations/github/issues

Create a GitHub issue from a recommendation.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
recommendation_id	UUID	Yes	Recommendation to create issue from
repo_full_name	string	Yes	GitHub repo (e.g., "acme/dashboard")
title	string	No	Override title (defaults to recommendation title)
labels	string[]	No	GitHub labels to apply

Response (200 OK)

{
  "issue_url": "https://github.com/acme/dashboard/issues/42",
  "issue_number": 42,
  "link_id": "a1b2c3d4-..."
}

List Links

GET /api/integrations/github/links

List all recommendation-to-GitHub-issue links for a workspace.

Sync

POST /api/integrations/github/sync

Sync GitHub issue statuses back to recommendation statuses.

---

Linear Integration

All Linear endpoints use the prefix /api/integrations/linear.

Connect Linear

POST /api/integrations/linear/connect

Initiate the Linear OAuth flow.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace to connect

OAuth Callback

GET /api/integrations/linear/callback

Handles the Linear OAuth redirect.

Disconnect Linear

DELETE /api/integrations/linear/disconnect

Get Status

GET /api/integrations/linear/status

List Teams

GET /api/integrations/linear/teams

List Linear teams accessible to the connected account.

Select Team

POST /api/integrations/linear/teams/select

Select the default Linear team for issue creation.

Create Issue

POST /api/integrations/linear/issues

Create a Linear issue from a recommendation.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
recommendation_id	UUID	Yes	Recommendation to create issue from
team_id	string	Yes	Linear team ID
title	string	No	Override title
label_ids	string[]	No	Linear label IDs
project_id	string	No	Linear project ID
state_id	string	No	Linear workflow state ID

List Links

GET /api/integrations/linear/links

List all recommendation-to-Linear-issue links.

Sync

POST /api/integrations/linear/sync

Sync Linear issue statuses back to recommendation statuses.

---

Jira Integration

All Jira endpoints use the prefix /api/integrations/jira. Requires: has_integrations plan feature.

Connect Jira

POST /api/integrations/jira/connect

Initiate the Jira OAuth 2.0 (3LO) flow.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace to connect

Response (200 OK)

{
  "auth_url": "https://auth.atlassian.com/authorize?...",
  "state": "550e8400-..."
}

OAuth Callback

GET /api/integrations/jira/callback

Handles the Atlassian OAuth redirect. Exchanges code for tokens, extracts cloud_id, encrypts and stores.

Disconnect Jira

POST /api/integrations/jira/disconnect

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID (request body)

Get Status

GET /api/integrations/jira/status

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID (query param)

Response (200 OK)

{
  "connected": true,
  "connected_at": "2026-03-27T10:00:00Z",
  "cloud_id": "abc123-..."
}

List Projects

GET /api/integrations/jira/projects

List accessible Jira projects for the connected account.

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID (query param)

---

Google Drive Integration

All Google Drive endpoints use the prefix /api/integrations/google-drive.

Connect Google Drive

POST /api/integrations/google-drive/connect

Initiate the Google OAuth flow.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace to connect

Response (200 OK)

{
  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "state": "550e8400-..."
}

OAuth state tokens expire after 600 seconds (10 minutes) and are single-use.

OAuth Callback

GET /api/integrations/google-drive/callback

Handles the Google OAuth redirect. Exchanges code for access and refresh tokens, encrypts and stores.

Disconnect Google Drive

DELETE /api/integrations/google-drive/disconnect

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Get Status

GET /api/integrations/google-drive/status

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID (query param)

Response (200 OK)

{
  "connected": true,
  "google_email": "user@company.com",
  "google_name": "Jane Doe",
  "google_avatar_url": "https://...",
  "last_synced_at": "2026-03-27T14:00:00Z"
}

Agent Tools

Once connected, the AI agent gains access to four Google Drive tools in chat conversations:

Tool	Description
google_drive_search	Search files by query
google_drive_read	Read file contents
google_drive_write	Write or update a file
google_drive_list_folder	List files in a folder

These are invoked automatically by the agent when relevant — e.g., "Find the Q2 roadmap in Drive."