API Reference

Vortask exposes a hosted Model Context Protocol (MCP) server at https://mcp.vortask.app. AI assistants (Claude, Cursor, etc.) can connect to it and manage your tasks and projects using natural language — no custom code required.

Connect from Claude.ai

Claude.ai supports remote MCP servers directly. No installation needed.

1. 1Go to Settings → Integrations → Add MCP Server
2. 2Enter URL: https://mcp.vortask.app
3. 3When prompted, paste your vt_ API token

Connect from Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "vortask": {
      "command": "npx",
      "args": ["-y", "vortask-mcp"],
      "env": {
        "VORTASK_API_URL": "https://api.vortask.app/api",
        "VORTASK_TOKEN": "vt_your_token_here"
      }
    }
  }
}

Authentication

For direct HTTP access, pass your API token as a Bearer token. The server uses the Streamable HTTP transport (JSON-RPC + SSE).

POST https://mcp.vortask.app
Authorization: Bearer vt_your_token
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
  "protocolVersion":"2024-11-05",
  "capabilities":{},
  "clientInfo":{"name":"my-agent","version":"1.0"}
}}

The response includes an mcp-session-id header. Pass it on all subsequent requests.

Available Tools

The MCP server exposes 14 tools. Call tools/list on the server to retrieve the full schema at any time.

Agent Workflow

Recommended sequence for an AI agent accessing Vortask for the first time:

Token Scopes

Create scoped tokens to limit what an agent can do. Tokens with no scopes have full access (bounded by project role).

Authentication

All API requests authenticate with a Personal API token created from your account dashboard. Tokens have a vt_ prefix. Pass the token in the Authorization header on every request.

Authorization: Bearer vt_<your_token>

Base URL & Headers

https://your-domain.com/api

All requests must include the following headers:

Errors

The API uses standard HTTP status codes. Error responses include a JSON body:

{
  "errors": ["Title is required."],
  "message": "Validation failed"
}

Profile

{
  "id": "uuid",
  "email": "alice@example.com",
  "displayName": "Alice",
  "avatarUrl": null,
  "createdAt": "2026-03-17T12:00:00Z"
}

{
  "displayName": "Alice Smith",
  "avatarUrl": "https://example.com/avatar.jpg"
}

Projects

[
  {
    "id": 1,
    "name": "My Project",
    "description": "...",
    "taskCount": 12,
    "myRole": "Admin",
    "createdAt": "2026-03-01T10:00:00Z"
  }
]

{
  "name": "My Project",       // required
  "description": "Optional desc"
}

{
  "name": "New Name",
  "description": "Updated desc"
}

Members

Manage who has access to a project. Roles: Admin · Member · Viewer

[{
  "id": 1,
  "userId": "uuid",
  "email": "bob@example.com",
  "displayName": "Bob",
  "role": "Member",
  "joinedAt": "2026-03-10T08:00:00Z"
}]

{
  "email": "bob@example.com",
  "role": "Member"  // Admin | Member | Viewer
}

{ "role": "Viewer" }

Tasks

GET /api/projects/1/tasks?status=Active&priority=High

{
  "id": 42,
  "title": "Implement login",
  "description": "...",
  "status": "Active",
  "priority": "High",
  "dueDate": "2026-03-20T00:00:00Z",
  "tags": ["backend", "auth"],
  "assignees": [{
    "userId": "uuid",
    "email": "alice@example.com",
    "displayName": "Alice"
  }],
  "createdAt": "2026-03-01T09:00:00Z",
  "updatedAt": "2026-03-15T14:22:00Z"
}

{
  "title": "Add dark mode",       // required
  "description": "Support system theme",
  "priority": "Medium",            // required
  "dueDate": "2026-04-01",
  "tags": ["frontend", "ui"],
  "assigneeIds": ["uuid1", "uuid2"]
}

{
  "title": "Updated title",
  "description": "New description",
  "status": "Closed",
  "priority": "High",
  "dueDate": "2026-05-01",
  "tags": ["backend"],
  "assigneeIds": ["uuid1"]
}

Task History

Returns an audit log of all changes to a task, newest first.

[{
  "id": 7,
  "actorId": "uuid",
  "actorName": "Alice",
  "action": "StatusChanged",
  "detail": "New → Active",
  "createdAt": "2026-03-15T14:22:00Z"
}]

Invitations

When a project Admin invites a user by email, an invitation token is sent. These endpoints let you preview and accept that invitation.

{
  "projectName": "My Project",
  "email": "bob@example.com",
  "role": "Member",
  "expiresAt": "2026-04-01T00:00:00Z"
}

{
  "projectId": 1,
  "projectName": "My Project"
}

API Tokens

Personal API tokens let you authenticate without a session. Tokens have a vt_ prefix and act as the authenticated user on all requests.

[{
  "id": "uuid",
  "name": "CI Deploy",
  "tokenPrefix": "vt_abc123de",
  "isActive": true,
  "createdAt": "2026-03-01T12:00:00Z",
  "expiresAt": null
}]

{
  "name": "CI Deploy",       // required
  "expiresAt": "2027-01-01"  // optional
}

{
  "id": "uuid",
  "name": "CI Deploy",
  "token": "vt_abc123...",  // full value, once only
  "createdAt": "2026-03-17T..."
}

Webhooks

Webhooks fire a POST request to your URL when task events occur. Requires Admin role.

{
  "callbackUrl": "https://your-server.com/hook",
  "secret": "optional_hmac_secret"
}

{
  "callbackUrl": "https://new-url.com/hook",
  "isActive": false
}

Data Models

"New" | "Active" | "Blocked" | "Closed"

"Low" | "Medium" | "High"

"Admin" | "Member" | "Viewer"

ISO 8601 strings
e.g. "2026-03-17T12:00:00Z"
or   "2026-03-17" (date only)

Webhook Events

When an event fires, Vortask sends a POST to your registered URL with this payload. If you provided a secret, an X-Vortask-Signature header is included (HMAC-SHA256 of the body).

{
  "event": "task.updated",
  "projectId": 1,
  "task": {
    "id": 42,
    "title": "Deploy to production",
    "status": "Closed",
    "priority": "High",
    "assignees": [{ "email": "alice@example.com" }],
    "tags": ["backend"],
    "updatedAt": "2026-03-17T14:00:00Z"
  }
}