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

Suscribe un endpoint HTTPS a los eventos de tareas y Krokanti Tasks te envía los cambios en el momento en que ocurren. Es la forma soportada de mantener sincronizado un sistema externo (GitHub Issues, Linear, un bot de Slack, tu propia base de datos).

Eventos

Un envío por cambio: cada webhook recibe el evento más específico al que se ha suscrito. Un webhook que solo conoce task.updated sigue recibiendo un envío cuando una tarea se mueve, se asigna o se archiva — las integraciones antiguas siguen funcionando igual.

Payload

Los envíos son POST con cuerpo JSON. El objeto task viene siempre completo (estado, asignados, etiquetas, fechas), así que rara vez necesitarás una lectura 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..." } }
  }
}

Cabeceras

Todo envío de plataforma personalizada incluye estas cabeceras. Usa X-Krokanti-Delivery para deduplicar reintentos.

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 la firma

La firma es un HMAC-SHA256 del cuerpo crudo exacto de la petición, con el secreto del webhook como clave. Compárala en tiempo constante y sobre el cuerpo crudo — si parseas y vuelves a serializar no 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 envío caduca a los 4 s y se reintenta una vez ante timeout, error de red, 5xx o 429. Un 4xx se considera rechazo permanente y no se reintenta. Tras 10 fallos consecutivos el webhook se desactiva automáticamente — reactívalo desde los ajustes del espacio cuando tu endpoint esté sano.

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