Tasks API

API endpoints for creating, reading, updating, and deleting tasks.

Pro Feature

The Tasks API provides full CRUD operations for managing tasks programmatically.

Get Task

Retrieve a specific task with its subtasks.

Endpoint

GET /tasks/:id

Parameters

Parameter Type Description
id string Task UUID

Required Scope

read

Response

{
  "task": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "label": "Design landing page",
    "status": 1,
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "workflow_lane_id": null,
    "position": "aaa",
    "description": "Create responsive landing page design",
    "subtasks": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440000",
        "label": "Create wireframe",
        "is_completed": true
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440001",
        "label": "Design mockup",
        "is_completed": false
      }
    ],
    "created_at": "2024-01-15T10:40:00Z",
    "updated_at": "2024-01-18T16:30:00Z"
  }
}

Example

curl https://api.kanman.de/v1/tasks/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer km_your_api_token"

Create Task

Create a new task in a project.

Endpoint

POST /tasks

Required Scope

write

Request Body

{
  "projectId": "660e8400-e29b-41d4-a716-446655440000",
  "label": "New task from API",
  "description": "Optional description text",
  "status": 0
}

Body Parameters

Parameter Type Required Description
projectId string Yes Target project UUID
label string Yes Task name
description string No Task description
status number No Initial status (0, 1, or 2). Default: 0

Response

{
  "task": {
    "id": "770e8400-e29b-41d4-a716-446655440010",
    "label": "New task from API",
    "status": 0,
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "workflow_lane_id": null,
    "position": "aad",
    "description": "Optional description text",
    "subtasks": [],
    "created_at": "2024-01-21T10:00:00Z",
    "updated_at": "2024-01-21T10:00:00Z"
  }
}

Example

curl -X POST https://api.kanman.de/v1/tasks \
  -H "Authorization: Bearer km_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "660e8400-e29b-41d4-a716-446655440000",
    "label": "New task from API"
  }'

Errors

Status Error Description
400 invalid_request Missing required fields
404 project_not_found Project doesn’t exist
429 quota_exceeded Task quota reached

Update Task

Update an existing task.

Endpoint

PATCH /tasks/:id

Parameters

Parameter Type Description
id string Task UUID

Required Scope

write

Request Body

All fields are optional. Only include fields you want to update.

{
  "label": "Updated task name",
  "status": 1,
  "description": "Updated description",
  "projectId": "660e8400-e29b-41d4-a716-446655440001"
}

Body Parameters

Parameter Type Description
label string New task name
status number New status (0, 1, or 2)
description string New description
projectId string Move to different project

Response

{
  "task": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "label": "Updated task name",
    "status": 1,
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "workflow_lane_id": null,
    "position": "aaa",
    "description": "Updated description",
    "subtasks": [],
    "created_at": "2024-01-15T10:40:00Z",
    "updated_at": "2024-01-21T10:30:00Z"
  }
}

Example: Change Status

curl -X PATCH https://api.kanman.de/v1/tasks/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer km_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"status": 2}'

Example: Move to Different Project

curl -X PATCH https://api.kanman.de/v1/tasks/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer km_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "660e8400-e29b-41d4-a716-446655440001"}'

Delete Task

Soft-delete a task (moves to trash).

Endpoint

DELETE /tasks/:id

Parameters

Parameter Type Description
id string Task UUID

Required Scope

delete

Response

{
  "success": true
}

Example

curl -X DELETE https://api.kanman.de/v1/tasks/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer km_your_api_token"

Notes

  • Deleted tasks go to trash for 40 days
  • Subtasks are deleted with the parent task
  • Can be recovered via the web UI

Task Object

Complete task object structure:

Field Type Description
id string Unique identifier (UUID)
label string Task name
status number 0=open, 1=in progress, 2=done
project_id string Parent project UUID
workflow_lane_id string Kanban lane UUID (nullable)
position string Order position (LexoRank)
description string Task description (nullable)
subtasks array Array of subtask objects
created_at string ISO 8601 timestamp
updated_at string ISO 8601 timestamp

Subtask Object

Field Type Description
id string Unique identifier (UUID)
label string Subtask name
is_completed boolean Completion status

Status Values

Value Name Description
0 Open Not started
1 In Progress Currently being worked on
2 Done Completed

Common Use Cases

Create Task from External Form

async function createTaskFromForm(formData) {
  const response = await fetch('https://api.kanman.de/v1/tasks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.KANMAN_API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      projectId: 'your-project-id',
      label: formData.title,
      description: formData.details
    })
  });
  return response.json();
}

Mark Task Complete

async function completeTask(taskId) {
  const response = await fetch(`https://api.kanman.de/v1/tasks/${taskId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${process.env.KANMAN_API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ status: 2 })
  });
  return response.json();
}

Sync Tasks to Another System

async function syncTasks(projectId) {
  // Get all tasks
  const response = await fetch(
    `https://api.kanman.de/v1/projects/${projectId}/tasks`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.KANMAN_API_TOKEN}`
      }
    }
  );
  const { tasks } = await response.json();

  // Sync to your system
  for (const task of tasks) {
    await yourSystem.createOrUpdate({
      externalId: task.id,
      title: task.label,
      status: ['todo', 'doing', 'done'][task.status],
      description: task.description
    });
  }
}

Last updated: January 1, 0001

Try Kanman