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

Subscreve um endpoint HTTPS aos eventos de tarefas e o Krokanti Tasks envia-te as alterações no momento em que acontecem. É a forma suportada de manter um sistema externo (GitHub Issues, Linear, um bot de Slack, a tua própria base de dados) sincronizado.

Eventos

Um envio por alteração: cada webhook recebe o evento mais específico a que subscreveu. Um webhook que só conhece task.updated continua a receber um envio quando uma tarefa é movida, atribuída ou arquivada — as integrações antigas continuam a funcionar.

Payload

Os envios são POST com corpo JSON. O objeto task vem sempre completo (estado, atribuídos, etiquetas, datas), pelo que raramente precisas de uma leitura adicional.

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

Cabeçalhos

Todos os envios de plataforma personalizada trazem estes cabeçalhos. Usa X-Krokanti-Delivery para desduplicar repetições.

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

Verificar a assinatura

A assinatura é um HMAC-SHA256 do corpo bruto exato do pedido, com o segredo do webhook como chave. Compara-a em tempo constante e sobre o corpo bruto — se fizeres parse e voltares a serializar não vai coincidir.

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
}

Semântica de entrega

Cada envio expira aos 4 s e é repetido uma vez em caso de timeout, erro de rede, 5xx ou 429. Um 4xx é tratado como rejeição permanente e não é repetido. Ao fim de 10 falhas seguidas o webhook é desativado automaticamente — reativa-o nas definições do espaço.

Gerir 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.