API Reference

Build powerful integrations with Magnus

Getting Started

The Magnus API allows you to programmatically interact with your virtual workspace, AI agents, and integrations. All API requests should be made to:

https://getmagnus.co/api

Authentication is handled via session cookies or API keys. Most endpoints require authentication. Admin-only endpoints require CEO role access.

Authentication

POST /api/auth/signup Public

Create a new user account. Requires email, password, and name.

POST /api/auth/login Public

Authenticate with email and receive a magic link, or use password authentication.

POST /api/auth/logout Authenticated

End the current session and invalidate the auth token.

GET /api/auth/me Authenticated

Get the currently authenticated user's information.

POST /api/auth/change-password Authenticated

Change the current user's password. Requires current and new password.

Agents

GET /api/agents Public

List all AI agents in the workspace with their details and positions.

GET /api/agents/:id Public

Get detailed information about a specific agent by ID.

POST /api/agents Employee

Create a new AI agent with custom name, role, personality, and system prompt.

POST /api/agents/:id/update Employee

Update an existing agent's properties including avatar, personality, and settings.

DELETE /api/agents/:id Admin

Delete an agent and all associated data.

GET /api/agents/hierarchy Employee

Get the organizational hierarchy of all agents.

GET /api/agents/leaderboard Public

Get agent performance leaderboard with interaction statistics.

Conversations

GET /api/conversations/:userId Owner/Admin

Get all conversations for a user across all agents.

GET /api/conversations/:userId/:agentId Owner/Admin

Get conversation history between a user and specific agent.

POST /api/conversations/message Authenticated

Send a message to an AI agent and receive a response.

POST /api/conversations/clear Authenticated

Clear conversation history with a specific agent.

POST /api/tts Rate Limited

Convert text to speech using ElevenLabs integration.

Users

GET /api/users Admin

List all users in the workspace.

PUT /api/users/:id/role Admin

Update a user's role (guest, employee, admin).

PUT /api/users/:id/avatar Owner/Admin

Upload or update a user's avatar image.

GET /api/users/:id/preferences Owner/Admin

Get user preferences and settings.

PUT /api/users/:id/preferences Owner/Admin

Update user preferences and settings.

Company

GET /api/company Public

Get company information including name, description, and branding.

POST /api/company Admin

Update company information and settings.

POST /api/company/logo Admin

Upload a new company logo.

GET /api/company/goals Public

Get company goals and mission statement.

POST /api/company/goals Admin

Update company goals and mission statement.

Files

GET /api/files Admin

List all files in the workspace.

POST /api/files/upload Authenticated

Upload a file to the workspace (max 10MB).

DELETE /api/files/:fileId Authenticated

Delete a file from the workspace.

GET /api/cabinet-files/:cabinet Admin

List files in a specific filing cabinet.

POST /api/cabinet-files/:cabinet/upload Authenticated

Upload a file to a specific filing cabinet (max 50MB).

Tasks

GET /api/tasks Authenticated

List all tasks in the workspace.

GET /api/tasks/agent/:agentId Authenticated

Get tasks assigned to a specific agent.

POST /api/tasks Authenticated

Create a new task and assign it to an agent.

PUT /api/tasks/:taskId Authenticated

Update a task's properties.

POST /api/tasks/:taskId/run Authenticated

Execute a task immediately.

DELETE /api/tasks/:taskId Authenticated

Delete a task.

Integrations

GET /api/integrations/status Authenticated

Get status of all integrations (GitHub, Google, Dropbox, Slack, etc.).

GET /api/integrations/:provider/status Public

Check if a specific integration is connected.

GET /api/integrations/:provider/auth Public

Start OAuth flow for an integration.

POST /api/integrations/:provider/disconnect Admin

Disconnect an integration.

GET /api/integrations/github/repos Admin

List connected GitHub repositories.

GET /api/integrations/google/drive Admin

List files in connected Google Drive.

GET /api/integrations/dropbox/files Admin

List files in connected Dropbox account.

GET /api/integrations/slack/channels Public

List Slack channels from connected workspace.

Swarm Intelligence

POST /api/swarm/start Authenticated

Start a new swarm session with multiple agents working together.

GET /api/swarm/:swarmId Authenticated

Get the status and results of a swarm session.

GET /api/swarms Authenticated

List all swarm sessions.

POST /api/swarm/:swarmId/cancel Authenticated

Cancel a running swarm session.

POST /api/swarm/:swarmId/share Authenticated

Generate a shareable link for swarm results.

Need Help?

Have questions about the API or need enterprise access? Get in touch with our team.

Contact Us