Krokanti Tasks API

Authentication

All API requests must include an Authorization header with a personal API token. Generate tokens in Settings → API Tokens. Tokens start with kt_ and are shown once on creation.

curl https://tasks.krokanti.com/api/spaces 
  -H "Authorization: Bearer kt_your_token_here" 
  -H "Content-Type: application/json"

Spaces

Projects

Tasks

Webhooks

Subscribe an HTTPS endpoint to task events and Krokanti Tasks pushes changes to you the moment they happen. This is the supported way to keep an external system (GitHub Issues, Linear, a Slack bot, your own database) in sync.

Events

One delivery per change: each webhook receives the most specific event it subscribed to. A webhook that only knows task.updated still gets a delivery when a task is moved, assigned or archived — so older integrations keep working unchanged.

Payload

Deliveries are POSTs with a JSON body. The task object is always fully hydrated (status, assignees, labels, dates) so you rarely need a follow-up read.

{
  "id": "b1e1c0de-...",                  // delivery id — de-duplicate on this
  "event": "task.moved",
  "timestamp": "2026-07-27T09:14:22.104Z",
  "data": {
    "task": {
      "id": "6f0c...", "title": "Ship the webhook docs",
      "description": "<p>...</p>",
      "priority": "high",
      "statusId": "2a91...",
      "status": { "id": "2a91...", "name": "In progress", "type": "in_progress" },
      "dueDate": "2026-07-30T00:00:00.000Z",
      "startDate": null,
      "completedAt": null,
      "isArchived": false,
      "parentTaskId": null,
      "createdAt": "2026-07-20T08:00:00.000Z",
      "updatedAt": "2026-07-27T09:14:22.041Z",
      "assignees": [{ "id": "9c2f...", "name": "Edgar" }],
      "labels": [{ "id": "77aa...", "name": "docs", "color": "#c07f3a" }],
      "url": "https://tasks.krokanti.com/en/app/my-space/my-project?taskId=6f0c..."
    },
    "project": { "id": "4d5e...", "name": "My project", "slug": "my-project" },
    "space":   { "id": "1a2b...", "slug": "my-space" },
    "actor":   { "id": "9c2f...", "name": "Edgar" },
    "comment": null,
    "assignee": null,
    "changes": { "statusId": { "from": "1f00...", "to": "2a91..." } }
  }
}

Headers

Every custom-platform delivery carries these headers. Use X-Krokanti-Delivery to de-duplicate retries.

X-Krokanti-Event:         task.moved
X-Krokanti-Delivery:      b1e1c0de-...          # unique per delivery
X-Krokanti-Timestamp:     2026-07-27T09:14:22.104Z
X-Krokanti-Signature:     3f8a...               # HMAC-SHA256 hex of the raw body
X-Krokanti-Signature-256: sha256=3f8a...        # same value, GitHub-style prefix
User-Agent:               Krokanti-Tasks-Webhook/1

Verifying the signature

The signature is an HMAC-SHA256 of the exact raw request body, keyed with the webhook secret. Compare it in constant time, on the raw body — parsing first and re-serializing will not match.

import crypto from "crypto";

export async function POST(req: Request) {
  const raw = await req.text();                  // raw body, before JSON.parse
  const sent = req.headers.get("x-krokanti-signature") ?? "";
  const expected = crypto
    .createHmac("sha256", process.env.KROKANTI_WEBHOOK_SECRET!)
    .update(raw)
    .digest("hex");

  const a = Buffer.from(sent), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return new Response("invalid signature", { status: 401 });
  }

  const payload = JSON.parse(raw);
  // ... handle payload.event, de-duplicate on payload.id
  return new Response("ok");                     // respond 2xx fast; queue slow work
}

Delivery semantics

A delivery times out after 4 s and is retried once on a timeout, network error, 5xx or 429. A 4xx is treated as a permanent rejection and is not retried. After 10 consecutive failures the webhook is disabled automatically — re-enable it from Space settings once your endpoint is healthy.

Managing webhooks

Error codes

Error responses include an error field. Some errors also include a machine-readable code field.

// Error response body
{ "error": "Unauthorized" }

// With machine-readable subcode
{ "error": "API access requires a Pro or Team plan", "code": "pro_required" }

Rate limits

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{ "error": "Rate limit exceeded" }

Code examples

Replace kt_your_token_here with your actual token.

cURL

# List your spaces
curl "https://tasks.krokanti.com/api/spaces" 
  -H "Authorization: Bearer kt_your_token_here"

# List projects in a space
curl "https://tasks.krokanti.com/api/projects?spaceId=SPACE_ID" 
  -H "Authorization: Bearer kt_your_token_here"

# List tasks in a project
curl "https://tasks.krokanti.com/api/tasks?projectId=PROJECT_ID" 
  -H "Authorization: Bearer kt_your_token_here"

# Create a task
curl -X POST "https://tasks.krokanti.com/api/tasks" 
  -H "Authorization: Bearer kt_your_token_here" 
  -H "Content-Type: application/json" 
  -d '{ "projectId": "PROJECT_ID", "title": "My new task", "priority": "high" }'

# Complete a task
curl -X PATCH "https://tasks.krokanti.com/api/tasks/TASK_ID" 
  -H "Authorization: Bearer kt_your_token_here" 
  -H "Content-Type: application/json" 
  -d '{ "completedAt": "2026-02-22T10:00:00.000Z" }'

JavaScript / Node

const BASE = "https://tasks.krokanti.com/api";
const TOKEN = "kt_your_token_here";
const headers = {
  Authorization: `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};

// List spaces
const spaces = await fetch(`${BASE}/spaces`, { headers }).then(r => r.json());

// List projects in first space
const projects = await fetch(
  `${BASE}/projects?spaceId=${spaces[0].id}`,
  { headers }
).then(r => r.json());

// Create a task
const { task } = await fetch(`${BASE}/tasks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    projectId: projects[0].id,
    title: "Review pull request",
    priority: "high",
    dueDate: new Date(Date.now() + 86400000).toISOString(),
  }),
}).then(r => r.json());

// Mark it done
await fetch(`${BASE}/tasks/${task.id}`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({ completedAt: new Date().toISOString() }),
});

Python

import requests
from datetime import datetime, timedelta, timezone

BASE = "https://tasks.krokanti.com/api"
TOKEN = "kt_your_token_here"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# List spaces
spaces = requests.get(f"{BASE}/spaces", headers=HEADERS).json()

# List projects
projects = requests.get(
    f"{BASE}/projects", headers=HEADERS,
    params={"spaceId": spaces[0]["id"]}
).json()

# Create a task
tomorrow = (datetime.now(timezone.utc) + timedelta(days=1)).isoformat()
resp = requests.post(f"{BASE}/tasks", headers=HEADERS, json={
    "projectId": projects[0]["id"],
    "title": "Deploy new release",
    "priority": "urgent",
    "dueDate": tomorrow,
})
task = resp.json()["task"]
print(f"Created task: {task['id']}")

# Complete the task
requests.patch(f"{BASE}/tasks/{task['id']}", headers=HEADERS, json={
    "completedAt": datetime.now(timezone.utc).isoformat()
})

MCP — AI Integration

Krokanti Tasks ships with a built-in MCP (Model Context Protocol) server. Connect Claude Code, Claude Desktop, or Cursor to your tasks and let AI create, update, and query tasks on your behalf — using the same API token.

Claude Code

Create a .mcp.json file in the root of your project (or add to an existing one):

// .mcp.json (project root)
{
  "mcpServers": {
    "krokanti-tasks": {
      "type": "http",
      "url": "https://tasks.krokanti.com/api/mcp",
      "headers": {
        "Authorization": "Bearer kt_your_token_here"
      }
    }
  }
}

Claude Code also needs the server enabled. Create .claude/settings.local.json in the same directory:

// .claude/settings.local.json
{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["krokanti-tasks"]
}

Claude Desktop

Add to your Claude Desktop configuration file. On macOS the file is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json.

// claude_desktop_config.json
{
  "mcpServers": {
    "krokanti-tasks": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://tasks.krokanti.com/api/mcp",
        "--header",
        "Authorization: Bearer kt_your_token_here"
      ]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (project-level) or ~/.cursor/mcp.json for global access:

// .cursor/mcp.json  (or ~/.cursor/mcp.json for global)
{
  "mcpServers": {
    "krokanti-tasks": {
      "type": "http",
      "url": "https://tasks.krokanti.com/api/mcp",
      "headers": {
        "Authorization": "Bearer kt_your_token_here"
      }
    }
  }
}

Available tools

All write operations (create, update, complete, add_comment, assign) require at least Member role in the space. Viewer role is read-only.

Built-in prompts

Prompts guide the AI to use multiple tools together for common workflows.