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

Abonnez un endpoint HTTPS aux événements de tâches et Krokanti Tasks vous pousse les changements dès qu'ils surviennent. C'est la façon supportée de synchroniser un système externe (GitHub Issues, Linear, un bot Slack, votre propre base).

Événements

Un envoi par changement : chaque webhook reçoit l'événement le plus spécifique auquel il s'est abonné. Un webhook qui ne connaît que task.updated reçoit toujours un envoi quand une tâche est déplacée, assignée ou archivée — les anciennes intégrations continuent de fonctionner.

Payload

Les envois sont des POST avec un corps JSON. L'objet task est toujours complet (statut, assignés, libellés, dates), vous n'avez donc presque jamais besoin d'une lecture supplémentaire.

{
  "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..." } }
  }
}

En-têtes

Chaque envoi de plateforme personnalisée porte ces en-têtes. Utilisez X-Krokanti-Delivery pour dédupliquer les reprises.

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

Vérifier la signature

La signature est un HMAC-SHA256 du corps brut exact de la requête, avec le secret du webhook comme clé. Comparez-la en temps constant et sur le corps brut — parser puis re-sérialiser ne correspondra pas.

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
}

Sémantique de livraison

Un envoi expire après 4 s et est réessayé une fois en cas de timeout, erreur réseau, 5xx ou 429. Un 4xx est considéré comme un refus définitif et n'est pas réessayé. Après 10 échecs consécutifs le webhook est désactivé automatiquement — réactivez-le depuis les réglages de l'espace.

Gérer les webhooks

Error codes

Error responses include an error field and optionally a 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%Claudeclaude_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.