REST API

Dokumentace REST API

Začínáme

Úvod

JSON přes HTTPS, vždy v rámci vašeho účtu. Hodí se pro skripty mezi servery, vlastní přehledy a nástroje bez MCP.

Základní adresa
https://mcptask.online/api
Kód účtu
{account} je krátký kód z vaší adresy v mcptask.online.
Tarify
Všechny. Hlášení chyb jen Professional, Enterprise a zkušební verze.

Připojení přes MCP popisuje stránka Integrace pro vývojáře.

Tohle volání nepotřebuje přihlášení. Odpověď je skutečná.

Požadavek
curl "https://mcptask.online/api"
Odpověď
{
  "message": "McpTask.online API v.0.10",
  "version": "16.9",
  "revision": "3756"
}

Přihlášení tokenem

Každé volání posílá token v hlavičce Authorization: Bearer <token>. Stejný token platí i pro MCP server.

Token získáte dvěma způsoby:

  • V aplikaci: Zobrazit uživatele → Rozšířené informace → API Token.
  • Voláním POST /api/sessions s e-mailem a heslem.

Výjimkou je hlášení chyb. To se přihlašuje klíčem projektu, ne tokenem uživatele.

Požadavek
curl "https://mcptask.online/api/$ACCOUNT/users/current" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 6,
  "first_name": "George",
  "last_name": "Owner",
  "email": "george.owner@example.com",
  "accounts": [
    {
      "code": "acme"
    }
  ],
  "avatar": null,
  "respect_working_hours": true
}

Která ID kde

Úkoly a projekty mají dvě čísla. relative_id je číslo, které vidíte v adrese. id je interní číslo.

KdeKteré číslo
{id} v /piecesrelative_id úkolu
project_id, parent_id v požadavkurelative_id projektu, nadřazeného úkolu
{id} v /users, assigned_user_idid uživatele
{effort_id}, {attachment_id}, sprint_idid záznamu

Pozor: GET /pieces/{id} vrací project_id jako interní číslo, POST /pieces jako relative_id.

Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/13" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 21,
  "relative_id": 13,
  "project_id": 2,
  "common_addition": {
    "assigned_user_id": 9,
    "assigned_user": "Peter Designer"
  }
}

Chyby

Chyba má vždy stejný tvar: pole errors s názvem a texty. Chyby validace navíc říkají, kterého pole se týkají, v attribute.

StavNázevVýznam
400missing_paramChybí povinný parametr.
401missing_tokenChybí hlavička Authorization.
401invalid_authorization_tokenToken je neplatný nebo zrušený.
402trial_expiredZkušební verze skončila a účet nemá kartu. Platí pro všechna volání na účtu, text obsahuje odkaz na platbu.
403forbiddenNa tuto akci nemáte oprávnění.
404not_foundZáznam neexistuje.
404wrong_email_or_passwordPřihlášení: špatný e-mail nebo heslo.
422validation_errorNeplatná data.
429Too Many RequestsPřekročený limit přihlášení nebo hlášení chyb. Tělo nese error a retry_after místo errors; počkejte tolik sekund, kolik udává hlavička Retry-After.
Odpověď
{
  "errors": [
    {
      "name": "missing_token",
      "message": [
        "Authorization Bearer token is missing!"
      ]
    }
  ]
}

Limity, stránky, jazyk

Limity
REST API počet volání neomezuje, až na dvě výjimky: hlášení chyb (30 za 10 minut na klíč) a přihlášení. Po překročení limitu odpovídá 429 s hlavičkou Retry-After.
Stránkování
GET /pieces bere limit (výchozí 20, nejvýš 100) a offset, v odpovědi je pagination.
Jazyk textů
Řídí se parametrem language (en, cs, sk), pak jazykem uživatele, pak hlavičkou Accept-Language.
Datum a čas
ISO 8601.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces?limit=2&offset=40&language=en" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "pieces": [
    "..."
  ],
  "pagination": {
    "limit": 2,
    "offset": 40,
    "total": 57,
    "has_more": true
  }
}

Přihlášení

Výměna e-mailu a hesla za token. Trvalý token z profilu tohle volání nepotřebuje.

Přihlásit se

POST/api/sessionsBez přihlášení

Vrátí token a uživatele. Špatné údaje vrací 404, ne 401. Obal session je v JSON nepovinný.

ParametrVýznam
session[email]v těle · povinnýE-mail uživatele.
session[password]v těle · povinnýHeslo.
Požadavek
curl -X POST "https://mcptask.online/api/sessions" \
  -H "Content-Type: application/json" \
  -d '{"session":{"email":"george.owner@example.com","password":"your-password"}}'
Odpověď
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 6,
    "first_name": "George",
    "last_name": "Owner",
    "email": "george.owner@example.com",
    "accounts": [
      {
        "code": "acme"
      }
    ],
    "avatar": null
  },
  "message": "Sign in was successful!"
}

Odhlásit se

DELETE/api/sessions/{id}

{id} je vaše vlastní ID uživatele. Cizí ID vrací 400.

ParametrVýznam
{id}v cestě · povinnýID přihlášeného uživatele.
Požadavek
curl -X DELETE "https://mcptask.online/api/sessions/6" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "message": "Logout was successful!"
}

Účet

Detail účtu

GET/api/{account}

Základní údaje a stav účtu.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 1,
  "code": "acme",
  "created_at": "2026-10-29T12:27:14.540+01:00",
  "updated_at": "2026-10-29T12:27:14.540+01:00",
  "state": "Active"
}

Úkoly

Piece je společné slovo pro Task, Story, Epic a Recurent, proto cesty říkají /pieces. {id} je vždy relative_id, tedy číslo z adresy úkolu.

Seznam úkolů

GET/api/{account}/pieces

Od naposledy změněných, po stránkách.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
project_idv dotazu · volitelnýJen úkoly tohoto projektu (relative_id).
limitv dotazu · volitelnýPočet na stránku, výchozí 20, nejvýš 100.
offsetv dotazu · volitelnýKolik záznamů přeskočit.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces?project_id=1&limit=20" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "pieces": [
    {
      "id": 21,
      "relative_id": 13,
      "type": "Task",
      "name": "Design for the Category page",
      "description": "Category page with a filter and the five best sellers.",
      "user_id": 6,
      "project_id": 2,
      "due_at": null,
      "created_at": "2026-10-29T12:27:14.540+01:00",
      "updated_at": "2026-10-29T12:27:14.540+01:00",
      "user": "George Owner",
      "project": "Sparks STORE",
      "common_addition": {
        "task_state_id": 2,
        "scrum_point_id": 3,
        "priority_id": 2,
        "sprint_id": 3,
        "assigned_user_id": 9,
        "task_state": "In progress",
        "scrum_point": "M",
        "priority": "Medium",
        "sprint": "1",
        "assigned_user": "Peter Designer"
      },
      "progress": 60.0,
      "worked_out": 4.5,
      "scrum_point": {
        "name": "M",
        "code": "M",
        "value": 5
      },
      "task_state": "In progress",
      "task_state_code": "inprogress",
      "task_type": "Task",
      "task_type_code": "task",
      "priority": "Medium",
      "priority_code": "medium",
      "new_effort_template": {
        "progress": 60,
        "begin_at": "2026-10-29T12:27:14.540+01:00"
      },
      "pinned": true
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1,
    "has_more": false
  }
}

Detail úkolu

GET/api/{account}/pieces/{id}

Úkol včetně příloh, nadřazeného úkolu a podúkolů.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/13" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 21,
  "relative_id": 13,
  "type": "Task",
  "name": "Design for the Category page",
  "description": "Category page with a filter and the five best sellers.",
  "user_id": 6,
  "project_id": 2,
  "due_at": null,
  "created_at": "2026-10-29T12:27:14.540+01:00",
  "updated_at": "2026-10-29T12:27:14.540+01:00",
  "user": "George Owner",
  "project": "Sparks STORE",
  "common_addition": {
    "task_state_id": 2,
    "scrum_point_id": 3,
    "priority_id": 2,
    "sprint_id": 3,
    "assigned_user_id": 9,
    "task_state": "In progress",
    "scrum_point": "M",
    "priority": "Medium",
    "sprint": "1",
    "assigned_user": "Peter Designer"
  },
  "progress": 60.0,
  "worked_out": 4.5,
  "scrum_point": {
    "name": "M",
    "code": "M",
    "value": 5
  },
  "task_state": "In progress",
  "task_state_code": "inprogress",
  "task_type": "Task",
  "task_type_code": "task",
  "priority": "Medium",
  "priority_code": "medium",
  "new_effort_template": {
    "progress": 60,
    "begin_at": "2026-10-29T12:27:14.540+01:00"
  },
  "pinned": true,
  "attachments": [
    {
      "id": 311,
      "filename": "category.png",
      "byte_size": 48213,
      "content_type": "image/png",
      "download_url": "https://mcptask.online/api/acme/pieces/13/attachments/311/download"
    }
  ],
  "parent": {
    "relative_id": 12,
    "type": "Story",
    "name": "Category pages"
  },
  "subtasks": []
}

Založit úkol

POST/api/{account}/pieces

Založí Task, Story, Epic nebo Recurent. parent_id musí patřit do stejného projektu, jinak vrací 422 parent_project_mismatch. Odpověď uvádí project_id jako relative_id projektu, detail úkolu vrací interní id.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
piece_typev těle · povinnýTask, Story, Epic nebo Recurent.
namev těle · povinnýNázev.
project_idv těle · povinnýrelative_id projektu.
descriptionv těle · volitelnýPopis.
parent_idv těle · volitelnýrelative_id nadřazeného úkolu.
task_type_codev těle · volitelnýKód typu, viz GET /api/task/types.
assigned_user_idv těle · volitelnýID uživatele, ne relative_id.
priority_codev těle · volitelnýPriorita, třeba medium.
scrum_point_codev těle · volitelnýNáročnost, třeba M.
sprint_idv těle · volitelnýID sprintu.
repeat_afterv těle · volitelnýRecurent: opakovat po dnech.
repeat_onv těle · volitelnýRecurent: dny v týdnu.
files[]multipart · volitelnýPřílohy.
for_errorsv těle · volitelnýJen Epic: je to Epic projektu pro chyby.
Požadavek
curl -X POST "https://mcptask.online/api/$ACCOUNT/pieces" \
  -H "Authorization: Bearer $MCPTASK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"piece_type":"Task","name":"Review PR","project_id":1}'
Odpověď
{
  "id": 22,
  "relative_id": 14,
  "type": "Task",
  "name": "Review PR",
  "description": null,
  "created_at": "2026-10-29T12:27:14.540+01:00",
  "project_id": 1,
  "project_name": "Sparks STORE",
  "url": "https://mcptask.online/acme/tasks/14",
  "task_state": "New",
  "task_state_code": "new",
  "assigned_user": null,
  "attachments": []
}

Upravit úkol

PATCH/api/{account}/pieces/{id}

Změní jen to, co pošlete. Vrací stejný tvar jako detail.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
namev těle · volitelnýNázev.
descriptionv těle · volitelnýPopis.
task_type_codev těle · volitelnýTyp.
assigned_user_idv těle · volitelnýID uživatele.
priority_codev těle · volitelnýPriorita.
scrum_point_codev těle · volitelnýNáročnost.
sprint_idv těle · volitelnýID sprintu.
for_errorsv těle · volitelnýJen Epic.
Požadavek
curl -X PATCH "https://mcptask.online/api/$ACCOUNT/pieces/13" \
  -H "Authorization: Bearer $MCPTASK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priority_code":"high"}'
Odpověď
{
  "id": 21,
  "relative_id": 13,
  "type": "Task",
  "name": "Design for the Category page",
  "description": "Category page with a filter and the five best sellers.",
  "user_id": 6,
  "project_id": 2,
  "due_at": null,
  "created_at": "2026-10-29T12:27:14.540+01:00",
  "updated_at": "2026-10-29T12:27:14.540+01:00",
  "user": "George Owner",
  "project": "Sparks STORE",
  "common_addition": {
    "task_state_id": 2,
    "scrum_point_id": 3,
    "priority_id": 2,
    "sprint_id": 3,
    "assigned_user_id": 9,
    "task_state": "In progress",
    "scrum_point": "M",
    "priority": "Medium",
    "sprint": "1",
    "assigned_user": "Peter Designer"
  },
  "progress": 60.0,
  "worked_out": 4.5,
  "scrum_point": {
    "name": "M",
    "code": "M",
    "value": 5
  },
  "task_state": "In progress",
  "task_state_code": "inprogress",
  "task_type": "Task",
  "task_type_code": "task",
  "priority": "Medium",
  "priority_code": "medium",
  "new_effort_template": {
    "progress": 60,
    "begin_at": "2026-10-29T12:27:14.540+01:00"
  },
  "pinned": true,
  "attachments": [
    {
      "id": 311,
      "filename": "category.png",
      "byte_size": 48213,
      "content_type": "image/png",
      "download_url": "https://mcptask.online/api/acme/pieces/13/attachments/311/download"
    }
  ],
  "parent": {
    "relative_id": 12,
    "type": "Story",
    "name": "Category pages"
  },
  "subtasks": []
}

Další úkol ve frontě

GET/api/{account}/pieces/next

Další úkol přihlášeného uživatele. Prázdná fronta je 200 s piece: null.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
project_idv dotazu · volitelnýJen z tohoto projektu (relative_id).
exclude_relative_idsv dotazu · volitelnýPřeskočit tyto úkoly, čísla oddělená čárkou.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/next?project_id=1" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "piece": {
    "id": 21,
    "relative_id": 13,
    "type": "Task",
    "name": "Design for the Category page",
    "description": "Category page with a filter and the five best sellers.",
    "user_id": 6,
    "project_id": 2,
    "due_at": null,
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "user": "George Owner",
    "project": "Sparks STORE",
    "common_addition": {
      "task_state_id": 2,
      "scrum_point_id": 3,
      "priority_id": 2,
      "sprint_id": 3,
      "assigned_user_id": 9,
      "task_state": "In progress",
      "scrum_point": "M",
      "priority": "Medium",
      "sprint": "1",
      "assigned_user": "Peter Designer"
    },
    "progress": 60.0,
    "worked_out": 4.5,
    "scrum_point": {
      "name": "M",
      "code": "M",
      "value": 5
    },
    "task_state": "In progress",
    "task_state_code": "inprogress",
    "task_type": "Task",
    "task_type_code": "task",
    "priority": "Medium",
    "priority_code": "medium",
    "new_effort_template": {
      "progress": 60,
      "begin_at": "2026-10-29T12:27:14.540+01:00"
    },
    "pinned": true
  }
}

Další podúkol ve Story

GET/api/{account}/pieces/{id}/next

Stejná pravidla jako další úkol, ale jen uvnitř Story. Když {id} není Story, vrací 404.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id Story.
exclude_relative_idsv dotazu · volitelnýPřeskočit tyto podúkoly.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/12/next" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "piece": {
    "id": 21,
    "relative_id": 13,
    "type": "Task",
    "name": "Design for the Category page",
    "description": "Category page with a filter and the five best sellers.",
    "user_id": 6,
    "project_id": 2,
    "due_at": null,
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "user": "George Owner",
    "project": "Sparks STORE",
    "common_addition": {
      "task_state_id": 2,
      "scrum_point_id": 3,
      "priority_id": 2,
      "sprint_id": 3,
      "assigned_user_id": 9,
      "task_state": "In progress",
      "scrum_point": "M",
      "priority": "Medium",
      "sprint": "1",
      "assigned_user": "Peter Designer"
    },
    "progress": 60.0,
    "worked_out": 4.5,
    "scrum_point": {
      "name": "M",
      "code": "M",
      "value": 5
    },
    "task_state": "In progress",
    "task_state_code": "inprogress",
    "task_type": "Task",
    "task_type_code": "task",
    "priority": "Medium",
    "priority_code": "medium",
    "new_effort_template": {
      "progress": 60,
      "begin_at": "2026-10-29T12:27:14.540+01:00"
    },
    "pinned": true
  }
}

Připnuté úkoly

GET/api/{account}/pieces/pinned

Úkoly, které si uživatel připnul.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/pinned" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 21,
    "relative_id": 13,
    "type": "Task",
    "name": "Design for the Category page",
    "description": "Category page with a filter and the five best sellers.",
    "user_id": 6,
    "project_id": 2,
    "due_at": null,
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "user": "George Owner",
    "project": "Sparks STORE",
    "common_addition": {
      "task_state_id": 2,
      "scrum_point_id": 3,
      "priority_id": 2,
      "sprint_id": 3,
      "assigned_user_id": 9,
      "task_state": "In progress",
      "scrum_point": "M",
      "priority": "Medium",
      "sprint": "1",
      "assigned_user": "Peter Designer"
    },
    "progress": 60.0,
    "worked_out": 4.5,
    "scrum_point": {
      "name": "M",
      "code": "M",
      "value": 5
    },
    "task_state": "In progress",
    "task_state_code": "inprogress",
    "task_type": "Task",
    "task_type_code": "task",
    "priority": "Medium",
    "priority_code": "medium",
    "new_effort_template": {
      "progress": 60,
      "begin_at": "2026-10-29T12:27:14.540+01:00"
    },
    "pinned": true
  }
]

Poslední úkoly

GET/api/{account}/pieces/last

Úkoly, na kterých uživatel naposledy pracoval.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/last" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 21,
    "relative_id": 13,
    "type": "Task",
    "name": "Design for the Category page",
    "description": "Category page with a filter and the five best sellers.",
    "user_id": 6,
    "project_id": 2,
    "due_at": null,
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "user": "George Owner",
    "project": "Sparks STORE",
    "common_addition": {
      "task_state_id": 2,
      "scrum_point_id": 3,
      "priority_id": 2,
      "sprint_id": 3,
      "assigned_user_id": 9,
      "task_state": "In progress",
      "scrum_point": "M",
      "priority": "Medium",
      "sprint": "1",
      "assigned_user": "Peter Designer"
    },
    "progress": 60.0,
    "worked_out": 4.5,
    "scrum_point": {
      "name": "M",
      "code": "M",
      "value": 5
    },
    "task_state": "In progress",
    "task_state_code": "inprogress",
    "task_type": "Task",
    "task_type_code": "task",
    "priority": "Medium",
    "priority_code": "medium",
    "new_effort_template": {
      "progress": 60,
      "begin_at": "2026-10-29T12:27:14.540+01:00"
    },
    "pinned": true
  }
]

Připnout úkol

POST/api/{account}/pieces/{id}/pin

Přidá úkol mezi připnuté.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
Požadavek
curl -X POST "https://mcptask.online/api/$ACCOUNT/pieces/13/pin" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
Bez obsahu

Odepnout úkol

DELETE/api/{account}/pieces/{id}/unpin

Odebere úkol z připnutých.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
Požadavek
curl -X DELETE "https://mcptask.online/api/$ACCOUNT/pieces/13/unpin" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "message": "Task successfully unpinned!"
}

Odpracovaný čas

Effort je záznam práce na úkolu: co se udělalo, od kdy do kdy a na kolik procent je úkol hotový.

Práce na úkolu

GET/api/{account}/pieces/{id}/efforts

Všechny záznamy práce na úkolu.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/13/efforts" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 98,
    "progress": 60,
    "description": "Drew the filter and the card grid.",
    "piece_id": 21,
    "user_id": 6,
    "project_id": 2,
    "begin_at": "2026-10-29T09:00:00.000+01:00",
    "end_at": "2026-10-29T11:00:00.000+01:00",
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "piece": "Design for the Category page",
    "user": "George Owner",
    "project": "Sparks STORE",
    "effort_state_code": "official",
    "effort_state": "Official work"
  }
]

Detail práce

GET/api/{account}/pieces/{id}/efforts/{effort_id}

Jeden záznam práce.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
{effort_id}v cestě · povinnýid záznamu práce.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/13/efforts/98" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 98,
  "progress": 60,
  "description": "Drew the filter and the card grid.",
  "piece_id": 21,
  "user_id": 6,
  "project_id": 2,
  "begin_at": "2026-10-29T09:00:00.000+01:00",
  "end_at": "2026-10-29T11:00:00.000+01:00",
  "created_at": "2026-10-29T12:27:14.540+01:00",
  "updated_at": "2026-10-29T12:27:14.540+01:00",
  "piece": "Design for the Category page",
  "user": "George Owner",
  "project": "Sparks STORE",
  "effort_state_code": "official",
  "effort_state": "Official work"
}

Zapsat práci

POST/api/{account}/pieces/{id}/efforts

Zapíše práci a posune stav úkolu podle progress. Obal effort je v JSON nepovinný.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
effort[description]v těle · povinnýCo se udělalo.
effort[progress]v těle · povinnýHotovo v procentech, 0 až 100.
effort[begin_at]v těle · povinnýZačátek, ISO 8601.
effort[end_at]v těle · povinnýKonec, ISO 8601.
Požadavek
curl -X POST "https://mcptask.online/api/$ACCOUNT/pieces/13/efforts" \
  -H "Authorization: Bearer $MCPTASK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"effort":{"description":"Drew the filter and the card grid.","progress":60,"begin_at":"2026-10-29T09:00:00+01:00","end_at":"2026-10-29T11:00:00+01:00"}}'
Odpověď
{
  "effort": {
    "id": 98,
    "progress": 60,
    "description": "Drew the filter and the card grid.",
    "piece_id": 21,
    "user_id": 6,
    "project_id": 2,
    "begin_at": "2026-10-29T09:00:00.000+01:00",
    "end_at": "2026-10-29T11:00:00.000+01:00",
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "piece": "Design for the Category page",
    "user": "George Owner",
    "project": "Sparks STORE",
    "effort_state_code": "official",
    "effort_state": "Official work"
  },
  "message": "Effort was successfully created."
}

Upravit práci

PATCH/api/{account}/pieces/{id}/efforts/{effort_id}

Změní jen to, co pošlete.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
{effort_id}v cestě · povinnýid záznamu práce.
effort[description]v těle · volitelnýCo se udělalo.
effort[progress]v těle · volitelnýHotovo v procentech.
effort[begin_at]v těle · volitelnýZačátek.
effort[end_at]v těle · volitelnýKonec.
Požadavek
curl -X PATCH "https://mcptask.online/api/$ACCOUNT/pieces/13/efforts/98" \
  -H "Authorization: Bearer $MCPTASK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"effort":{"progress":75}}'
Odpověď
{
  "effort": {
    "id": 98,
    "progress": 75,
    "description": "Drew the filter and the card grid.",
    "piece_id": 21,
    "user_id": 6,
    "project_id": 2,
    "begin_at": "2026-10-29T09:00:00.000+01:00",
    "end_at": "2026-10-29T11:00:00.000+01:00",
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "piece": "Design for the Category page",
    "user": "George Owner",
    "project": "Sparks STORE",
    "effort_state_code": "official",
    "effort_state": "Official work"
  },
  "message": "Effort was successfully updated."
}

Smazat práci

DELETE/api/{account}/pieces/{id}/efforts/{effort_id}

Smaže záznam práce.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
{effort_id}v cestě · povinnýid záznamu práce.
Požadavek
curl -X DELETE "https://mcptask.online/api/$ACCOUNT/pieces/13/efforts/98" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "message": "Effort was successfully destroyed."
}

Založit úkol a zapsat na něj práci

POST/api/{account}/projects/{project_id}/quick_efforts

Jedno volání založí v projektu nový úkol (Task) a zapíše na něj práci; když práci nejde uložit, nevznikne ani úkol. description se stane popisem úkolu i popisem práce. Odpoví 201 s úkolem ve tvaru jako Detail úkolu a s efforts: je to seznam, protože práce přes půlnoc nebo přes polední pauzu se rozdělí na víc záznamů. OAuth token potřebuje oba scopy, write_pieces i log_efforts. Odpoví 403, když v projektu nesmíte zakládat úkoly, a 404 pro neznámý projekt.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{project_id}v cestě · povinnýrelative_id projektu.
quick_effort[name]v těle · povinnýNázev nového úkolu.
quick_effort[description]v těle · povinnýCo se udělalo.
quick_effort[begin_at]v těle · volitelnýZačátek, ISO 8601. Bez něj konec vaší poslední práce plus jedna minuta.
quick_effort[end_at]v těle · volitelnýKonec, ISO 8601. Bez něj teď, nikdy dřív než začátek.
quick_effort[progress]v těle · volitelnýHotovo v procentech, 0 až 100. Bez něj stav nového úkolu.
Požadavek
curl -X POST "https://mcptask.online/api/$ACCOUNT/projects/1/quick_efforts" \
  -H "Authorization: Bearer $MCPTASK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quick_effort":{"name":"Fix the checkout total","description":"Rounded the VAT per line instead of per order.","begin_at":"2026-10-29T09:00:00+01:00","end_at":"2026-10-29T10:30:00+01:00","progress":100}}'
Odpověď
{
  "piece": {
    "id": 57,
    "relative_id": 31,
    "type": "Task",
    "name": "Fix the checkout total",
    "description": "Rounded the VAT per line instead of per order.",
    "user_id": 6,
    "project_id": 2,
    "due_at": null,
    "created_at": "2026-10-29T10:30:12.408+01:00",
    "updated_at": "2026-10-29T10:30:12.408+01:00",
    "user": "George Owner",
    "project": "Sparks STORE",
    "common_addition": {
      "task_state_id": 5,
      "scrum_point_id": 3,
      "priority_id": 2,
      "sprint_id": null,
      "assigned_user_id": 6,
      "task_state": "Done",
      "scrum_point": "M",
      "priority": "Medium",
      "sprint": "",
      "assigned_user": "George Owner"
    },
    "progress": 100.0,
    "worked_out": 1.5,
    "task_state": "Done",
    "task_state_code": "done",
    "task_type": "Task",
    "task_type_code": "task",
    "priority": "Medium",
    "priority_code": "medium",
    "attachments": [],
    "parent": null,
    "subtasks": []
  },
  "efforts": [
    {
      "id": 131,
      "progress": 100,
      "description": "Rounded the VAT per line instead of per order.",
      "piece_id": 57,
      "user_id": 6,
      "project_id": 2,
      "begin_at": "2026-10-29T09:00:00.000+01:00",
      "end_at": "2026-10-29T10:30:00.000+01:00",
      "created_at": "2026-10-29T10:30:12.420+01:00",
      "updated_at": "2026-10-29T10:30:12.420+01:00",
      "piece": "Fix the checkout total",
      "user": "George Owner",
      "project": "Sparks STORE",
      "effort_state_code": "official",
      "effort_state": "Official work"
    }
  ]
}

Zprávy

Přidat zprávu k úkolu

POST/api/{account}/pieces/{id}/messages

Přidá poznámku k úkolu. Řešitel dostane e-mail, pokud to má zapnuté.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
message[content]v těle · povinnýText zprávy.
message[message_type]v těle · volitelnýTyp zprávy, výchozí note.
Požadavek
curl -X POST "https://mcptask.online/api/$ACCOUNT/pieces/13/messages" \
  -H "Authorization: Bearer $MCPTASK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"content":"Tests pass, ready for review."}}'
Odpověď
{
  "id": 501,
  "piece_relative_id": 13,
  "created_at": "2026-10-29T12:27:14.540+01:00"
}

Přílohy

Nahrát přílohu

POST/api/{account}/pieces/{id}/attachments

Soubor posílejte jako multipart/form-data. Největší povolená velikost záleží na tarifu.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
filemultipart · povinnýSoubor.
Požadavek
curl -X POST "https://mcptask.online/api/$ACCOUNT/pieces/13/attachments" \
  -H "Authorization: Bearer $MCPTASK_TOKEN" \
  -F "file=@category.png"
Odpověď
{
  "id": 311,
  "filename": "category.png",
  "byte_size": 48213,
  "content_type": "image/png",
  "download_url": "https://mcptask.online/api/acme/pieces/13/attachments/311/download"
}

Stáhnout přílohu

GET/api/{account}/pieces/{id}/attachments/{attachment_id}/download

Vrátí obsah souboru. Adresu najdete v download_url u úkolu. Pošlete s ní JWT uživatele, který úkol smí číst. Bez JWT projde jen podepsaná adresa z MCP nástroje GetAttachmentTool, platí 15 minut. Vše ostatní dostane 401.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
{attachment_id}v cestě · povinnýid přílohy.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/pieces/13/attachments/311/download" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
<the file's bytes>

Smazat přílohu

DELETE/api/{account}/pieces/{id}/attachments/{attachment_id}

Odebere přílohu z úkolu.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýrelative_id úkolu.
{attachment_id}v cestě · povinnýid přílohy.
Požadavek
curl -X DELETE "https://mcptask.online/api/$ACCOUNT/pieces/13/attachments/311" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
Bez obsahu

Uživatelé

Člověk i AI vývojář je tu stejný uživatel se stejnými pravidly. {id} je ID uživatele, ne relative_id.

Seznam uživatelů

GET/api/{account}/users

Uživatelé účtu seřazení podle jména.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
qv dotazu · volitelnýFiltr podle jména, příjmení nebo e-mailu.
limitv dotazu · volitelnýKolik jich vrátit, výchozí 50, nejvýš 200.
offsetv dotazu · volitelnýKolik jich přeskočit.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/users?q=peter" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 9,
    "first_name": "Peter",
    "last_name": "Designer",
    "avatar": null
  }
]

Přihlášený uživatel bez účtu

GET/api/users/current

Kdo je vlastníkem tokenu a kódy všech jeho účtů. Nepotřebuje kód účtu, takže se tu klient svůj kód dozví nejdřív.

Požadavek
curl "https://mcptask.online/api/users/current" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 6,
  "first_name": "George",
  "last_name": "Owner",
  "email": "george.owner@example.com",
  "accounts": [
    {
      "code": "acme"
    },
    {
      "code": "sparks"
    }
  ],
  "avatar": null,
  "respect_working_hours": true
}

Přihlášený uživatel

GET/api/{account}/users/current

Kdo je vlastníkem tokenu.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/users/current" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 6,
  "first_name": "George",
  "last_name": "Owner",
  "email": "george.owner@example.com",
  "accounts": [
    {
      "code": "acme"
    }
  ],
  "avatar": null,
  "respect_working_hours": true
}

Detail uživatele

GET/api/{account}/users/{id}

Jeden uživatel účtu.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýID uživatele.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/users/6" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 6,
  "first_name": "George",
  "last_name": "Owner",
  "email": "george.owner@example.com",
  "accounts": [
    {
      "code": "acme"
    }
  ],
  "avatar": null,
  "respect_working_hours": true
}

Můj odpracovaný čas

GET/api/{account}/users/current/time_status

Dnes, tento týden, tento měsíc a celkový výkon, sečtené přes všechny vaše účty. state je success, warning nebo danger; v overall je great, good, warning, alert nebo danger. performance říká totéž slovy.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/users/current/time_status" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "respect_working_hours": true,
  "work_start": {
    "designation": "Work start",
    "value": "08:30"
  },
  "this_month": {
    "designation": "Worked this month",
    "state": "warning",
    "value": 92.5,
    "hour_goal": 160,
    "performance": "Small shortage"
  },
  "this_week": {
    "designation": "Worked this week",
    "state": "success",
    "value": 32.5,
    "hour_goal": 40,
    "performance": "Good work"
  },
  "today": {
    "designation": "Worked today",
    "state": "warning",
    "value": 4.5,
    "hour_goal": 8,
    "performance": "Small shortage"
  },
  "overall": {
    "designation": "Performance",
    "state": "good",
    "value": 4.5,
    "hour_goal": 24,
    "performance": "Good work"
  }
}

Odpracovaný čas uživatele

GET/api/{account}/users/{id}/time_status

Stejný tvar jako můj odpracovaný čas, počítá jen hodiny zapsané v tomto účtu.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýID uživatele.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/users/9/time_status" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "respect_working_hours": true,
  "work_start": {
    "designation": "Work start",
    "value": "09:00"
  },
  "this_month": {
    "designation": "Worked this month",
    "state": "success",
    "value": 120.0,
    "hour_goal": 160,
    "performance": "Good work"
  },
  "this_week": {
    "designation": "Worked this week",
    "state": "warning",
    "value": 22.0,
    "hour_goal": 40,
    "performance": "Small shortage"
  },
  "today": {
    "designation": "Worked today",
    "state": "danger",
    "value": 2.5,
    "hour_goal": 8,
    "performance": "That's bad!"
  },
  "overall": {
    "designation": "Performance",
    "state": "warning",
    "value": 22.0,
    "hour_goal": 24,
    "performance": "Small shortage"
  }
}

Sledovaní pracovníci

GET/api/{account}/users/tracked_workers

Koho vidíte v přehledu práce. Odpoví 403, pokud nemáte přehled práce zapnutý na nástěnce nebo ho vaše role v účtu nedovolují.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/users/tracked_workers" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 9,
    "first_name": "Peter",
    "last_name": "Designer"
  }
]

Přehled práce uživatele

GET/api/{account}/users/{id}/worker_tracking

Dnešní čas, aktuální úkol a dnešní úkoly jednoho uživatele. Potřebuje stejné oprávnění jako sledovaní pracovníci a uživatel musí být mezi vašimi sledovanými, pokud účet nespravujete. Uživatel mimo účet odpoví 404.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýID uživatele.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/users/9/worker_tracking" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "generated_at": "2026-10-29T12:27:14+01:00",
  "user": {
    "id": 9,
    "first_name": "Peter",
    "last_name": "Designer"
  },
  "today": {
    "work_start_at": "2026-10-29T08:30:00+01:00",
    "worked_seconds": 14400.0,
    "target_seconds": 28800,
    "progress": 0.5,
    "state_code": "warning"
  },
  "current_task": null,
  "today_worked_pieces": [
    {
      "piece": {
        "id": 21,
        "relative_id": 13,
        "type": "Task",
        "name": "Design for the Category page",
        "project_id": 2,
        "project": "Sparks STORE",
        "task_state": "In progress",
        "task_state_code": "inprogress",
        "progress": 60.0,
        "worked_seconds": 14400.0
      },
      "worked_seconds": 14400.0,
      "is_current": false
    }
  ],
  "recent_events": [],
  "heartbeat_at": "2026-10-29T12:25:00+01:00"
}

Projekty

Seznam projektů

GET/api/{account}/projects

Projekty, ke kterým máte přístup. relative_id použijete jako project_id jinde v API, id je interní. for_errors_epic_relative_ids jsou epiky, kam padají hlášení chyb. Ceny projektu (hour_price, target_price, old_hour_prices) jsou v options jen pro toho, kdo smí projekt upravovat; ostatní tam dostanou jen pracovní nastavení, třeba sprint_points.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/projects" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 2,
    "relative_id": 1,
    "type": null,
    "name": "Sparks STORE",
    "description": "Store for Sparks sale",
    "start_at": "2026-01-05T09:00:00.000+01:00",
    "is_template": false,
    "options": "{\"sprint_points\" => \"40\"}",
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "currency": "Kč",
    "project_type": "Agile project",
    "project_state": "In progress",
    "company": "Acme",
    "account": "acme",
    "for_errors_epic_relative_ids": [
      92
    ]
  }
]

Události

Poslední události

GET/api/{account}/events/last

Co se v účtu za posledních 24 hodin vytvořilo, změnilo nebo smazalo. originator říká odkud, jedno z web, api, mcp, runner, gitlab nebo git_hub. Pokud je data, obsahuje parametry požadavku, hesla a tokeny jako [FILTERED], a provedené změny.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/events/last" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 12,
    "eventable_type": "Effort",
    "eventable_id": 98,
    "event_type_id": 7,
    "originator": "mcp",
    "user_id": 6,
    "project_id": 2,
    "account_id": 1,
    "piece_id": 21,
    "created_at": "2026-10-29T12:27:14.540+01:00",
    "updated_at": "2026-10-29T12:27:14.540+01:00",
    "event_type": "Create",
    "event_type_code": "create",
    "user": "George Owner",
    "account": "acme",
    "project": "Sparks STORE",
    "piece": "Design for the Category page",
    "piece_relative_id": 13,
    "resource": {
      "name": "Drew the filter and the card grid."
    }
  }
]

Detail události

GET/api/{account}/events/{id}

Jedna událost ve stejném tvaru.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
{id}v cestě · povinnýid události.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/events/12" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "id": 12,
  "eventable_type": "Effort",
  "eventable_id": 98,
  "event_type_id": 7,
  "originator": "mcp",
  "user_id": 6,
  "project_id": 2,
  "account_id": 1,
  "piece_id": 21,
  "created_at": "2026-10-29T12:27:14.540+01:00",
  "updated_at": "2026-10-29T12:27:14.540+01:00",
  "event_type": "Create",
  "event_type_code": "create",
  "user": "George Owner",
  "account": "acme",
  "project": "Sparks STORE",
  "piece": "Design for the Category page",
  "piece_relative_id": 13,
  "resource": {
    "name": "Drew the filter and the card grid."
  }
}

Hlášení chyb

Vaše aplikace založí hlášení chyby jedním POSTem s klíčem projektu. Chyba přistane jako úkol v Epicu projektu pro chyby, s adresou stránky, prohlížečem, screenshotem a výpisem konzole v příloze. Jen Professional, Enterprise a zkušební verze; na tarifu Starter klíče nic nezaloží.

Nastavení ve 3 krocích

  1. Otevřete nastavení projektu a sjeďte ke kartě API pro hlášení chyb.
  2. Pojmenujte klíč (např. „Moje aplikace produkce“) a případně zvolte výchozího řešitele. Chyby se zakládají do Epicu projektu pro chyby — když ho projekt nemá, vytvoří se automaticky — a jejich autorem je ten, kdo klíč vytvořil.
  3. Klikněte na Vytvořit klíč a hned si ho zkopírujte: zobrazí se jen jednou (ukládáme pouze jeho otisk). Držte ho na svém serveru, např. v proměnné prostředí. Zrušit ho můžete kdykoli ve stejné kartě.

Klíč pro hlášení chyb nikdy nedávejte do kódu, který běží v prohlížeči návštěvníka — kdokoli by ho přečetl a mohl by váš projekt zahltit. Ať prohlížeč pošle hlášení vašemu vlastnímu backendu a ten teprve volá mcptask.online.

Multipart se screenshotem

screenshot a files[] berou soubor v multipart nebo base64 data URL (data:image/png;base64,…). Všechny přílohy dohromady mohou mít nejvýše 10 MB.

Založená chyba odpoví 201 Created s relativním ID a odkazem na nový úkol.

Požadavek
curl -X POST "https://mcptask.online/api/$ACCOUNT/bug_reports" \
  -H "Authorization: Bearer $BUG_REPORT_KEY" \
  -F "title=Save button does nothing" \
  -F "description=Clicking Save on the invoice form has no effect." \
  -F "screenshot=@screenshot.png" \
  -F "files[]=@invoice.pdf"
Odpověď
{
  "relative_id": 1234,
  "url": "https://mcptask.online/acme/tasks/1234"
}

Chyby

Chyby odpovídají JSONem s polem errors; každá položka nese name a message (validační chyby i attribute).

StavNázevVýznam
401invalid_bug_report_keyKlíč chybí, je neznámý, zrušený nebo patří k jinému kódu účtu.
402trial_expiredZkušební verze skončila a účet potřebuje platební metodu.
403plan_upgrade_requiredÚčet je na tarifu Starter — přejděte na Professional nebo Enterprise.
413upload_too_largePřílohy překročily společný limit 10 MB.
422validation_errorPovinné pole je prázdné, příloha není soubor ani data URL, řešitel není členem účtu nebo kód priority neexistuje.
429Too Many RequestsVíce než 30 hlášení za 10 minut s jedním klíčem; počkejte počet sekund z hlavičky Retry-After.

Nahlásit chybu

POST/api/{account}/bug_reportsKlíč projektu

Přihlašuje se klíčem projektu v hlavičce Authorization: Bearer. Nejvýš 30 hlášení za 10 minut na klíč a 10 MB příloh dohromady. Pošlete JSON, nebo multipart/form-data, když nahráváte soubory.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
titlev těle · povinnýNázev chyby — stane se názvem úkolu.
descriptionv těle · povinnýCo se stalo. Pole níže se do popisu úkolu přidají jako sekce.
expected_behaviorv těle · volitelnýCo se mělo stát.
urlv těle · volitelnýAdresa stránky.
user_agentv těle · volitelnýProhlížeč.
viewportv těle · volitelnýVelikost okna.
reporter_namev těle · volitelnýKdo chybu ve vaší aplikaci nahlásil.
reporter_emailv těle · volitelnýE-mail hlásícího.
console_logv těle · volitelnýVýpis konzole prohlížeče; přiloží se jako console.log a jeho konec jde i do popisu.
html_snapshotv těle · volitelnýHTML stránky; přiloží se jako snapshot.html.
screenshotv těle · volitelnýSoubor v multipart nebo base64 data URL (data:image/png;base64,…).
files[]v těle · volitelnýDalší přílohy — soubory v multipart nebo base64 data URL. Všechny přílohy dohromady mohou mít nejvýše 10 MB.
assigned_user_idv těle · volitelnýPřebije výchozího řešitele klíče; ID uživatele, který je členem vašeho účtu.
priority_codev těle · volitelnýPřebije výchozí prioritu high: low, medium, high nebo urgent.
Požadavek
curl -X POST "https://mcptask.online/api/$ACCOUNT/bug_reports" \
  -H "Authorization: Bearer $BUG_REPORT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Save button does nothing","description":"Clicking Save on the invoice form has no effect.","url":"https://app.example.com/invoices/1","priority_code":"urgent"}'
Odpověď
{
  "relative_id": 1234,
  "url": "https://mcptask.online/acme/tasks/1234"
}

Runnery

Připojené runnery

GET/api/{account}/runner_sessions

Kolik runnerů je připojených a kolik pracuje, aktuální úkol a seznam kroků každého z nich a posledních 20 změn stavu. Odpoví 403, pokud nemáte panel runnerů zapnutý na nástěnce nebo ho vaše role v účtu nedovolují.

ParametrVýznam
{account}v cestě · povinnýKód účtu z vaší adresy v mcptask.online.
Položka odpovědiVýznam
generated_atKdy byla odpověď sestavena.
counts.connectedKolik runnerů je právě připojených.
counts.workingKolik z nich právě pracuje na úkolu.
counts.deployed_todayU kolika úkolů účtu byl dnes sloučen pull request. Nasazeno znamená sloučeno.
snapshotsSnímky runnerů, které ukazuje panel na nástěnce, nejdřív ten naposledy aktivní.
snapshots[].idid snímku.
snapshots[].session_idRelace runneru, ke které snímek patří.
snapshots[].machine_idStroj, na kterém runner běží.
snapshots[].modelAI model, se kterým runner pracuje.
snapshots[].harnessProgram, který runner ovládá, například claude. null u runneru, který je na to příliš starý.
snapshots[].project_nameNázev projektu, ve kterém runner pracuje.
snapshots[].task.relative_idrelative_id úkolu, na kterém runner je, null, dokud žádný nemá.
snapshots[].task.nameNázev toho úkolu.
snapshots[].status_codeStav runneru. frozen, stalled a error znamenají, že se runner zasekl; waiting a pending, že nic nedělá; finished a closed, že běh skončil.Hodnoty: starting, triage, processing, waiting, pending, finished, stalled, frozen, error, closed
snapshots[].thinkingNad čím runner právě přemýšlí, nebo null.
snapshots[].messagePoslední zpráva runneru, nebo null.
snapshots[].error_messageChyba, která runner zastavila, nebo null.
snapshots[].heartbeat_atKdy se runner naposledy ozval.
snapshots[].closed_atKdy byl snímek uzavřen, null, dokud je otevřený.
snapshots[].parkedtrue, když je runner na nástěnce zaparkovaný a nebere nové úkoly.
snapshots[].actionsPoslední volání nástrojů. Prázdné, když žádná nejsou.
snapshots[].actions[].nameNástroj, například Bash nebo Edit.
snapshots[].actions[].summaryShrnutí volání na jeden řádek, nebo null.
snapshots[].actions[].descriptionK čemu volání sloužilo, nebo null.
snapshots[].actions[].elapsed_secondsJak dlouho volání běží, v sekundách, nebo null.
snapshots[].actions[].elapsed_labelTentýž čas slovy, například 12s, nebo null.
snapshots[].todosSeznam kroků runneru k úkolu.
snapshots[].todos[].contentText kroku.
snapshots[].todos[].active_formText, zatímco se na kroku pracuje, nebo null.
snapshots[].todos[].status_codeStav kroku.Hodnoty: pending, in_progress, completed
snapshots[].todo_counts.pendingKolik kroků zbývá.
snapshots[].todo_counts.in_progressNa kolika krocích se pracuje.
snapshots[].todo_counts.completedKolik kroků je hotových.
snapshots[].todo_counts.totalKolik kroků seznam má.
snapshots[].stage_trackKde je úkol runneru na cestě od zadání k nasazení. null, když snímek nemá úkol nebo úkol nelze najít.
snapshots[].stage_track.current_stageFáze, ve které úkol právě je – první, jejíž stav je now nebo fail; po sloučení deployed.Hodnoty: task, branch, pull_request, ci, deployed
snapshots[].stage_track.phaseCo runner dělá ve svém současném běhu, podle nejvyššího postupu zapsaného od začátku běhu: analysis (triáž nebo pod 20 %), dev (20–44 %), tests (45–79 %), ci (80 % a víc); po sloučení pull requestu deployed.Hodnoty: analysis, dev, tests, ci, deployed
snapshots[].stage_track.stages[].stagePět fází, vždy všech pět a vždy v tomto pořadí.Hodnoty: task, branch, pull_request, ci, deployed
snapshots[].stage_track.stages[].stateJak fáze stojí: done hotovo, now probíhá, fail skončila špatně (úkol odložen, pull request zavřen, CI červené), pending zatím nezačala.Hodnoty: done, now, fail, pending
snapshots[].stage_track.progress_percentNaposledy zapsaný postup úkolu, 0 až 100, nebo null, když se nic nezapsalo.
snapshots[].stage_track.pull_request_numbersČísla pull requestů úkolu, nejstarší první. O dalších fázích rozhoduje ten poslední.
snapshots[].stage_track.ci_outcomeVýsledek CI posledního pull requestu, null, dokud žádný není.Hodnoty: passed, failing
snapshots[].stage_track.ci_attemptsKolik běhů CI bylo potřeba k úspěchu, nebo kolik jich zatím selhalo, když ještě neprošlo.
snapshots[].stage_track.ci_not_requiredtrue, když byl pull request sloučen bez zeleného CI: projekt CI nevyžaduje, takže červená nebo chybějící kontrola není selhání.
snapshots[].stage_track.deployed_atKdy byl poslední pull request sloučen, předtím null.
snapshots[].stage_track.set_asidetrue, když runner úkol odložil a od té doby se na něm nic nestalo.
snapshots[].stage_track.set_aside_categoryProč byl úkol odložen, null, když odložen nebyl. deferred se nevejde do jednoho běhu; waiting_on_blocker čeká na nedokončený úkol, který ho blokuje; already_taken už na něm pracuje někdo jiný; needs_person další krok může udělat jen člověk; run_failed běh selhal; unknown jiný důvod.Hodnoty: deferred, waiting_on_blocker, already_taken, needs_person, run_failed, unknown
snapshots[].stage_track.runsKolikrát runnery na úkolu začaly pracovat, přes všechny relace. 0 u běhů z doby, kdy se to nepočítalo.
snapshots[].stage_track.restartedtrue, když práce na úkolu začala víc než jednou.
timelinePosledních 20 změn stavu runnerů účtu, nejnovější první.
timeline[].idid události.
timeline[].occurred_atKdy se to stalo.
timeline[].kind_codeconnected runner se připojil, update změnil se jeho stav, closed běh skončil.Hodnoty: connected, update, closed
timeline[].event_type_codeKód typu události, stejně jako v GET /api/{account}/events.
timeline[].session_idRelace runneru, nebo null, když snímek už neexistuje.
timeline[].machine_idStroj, nebo null, když snímek už neexistuje.
timeline[].taskÚkol, na kterém runner byl, null, když žádný neměl.
timeline[].task.relative_idrelative_id úkolu.
timeline[].task.nameNázev úkolu.
timeline[].previous_status_codeStav před změnou, jedna z hodnot status_code, nebo null.
timeline[].status_codeStav po změně, jedna z hodnot status_code, nebo null.
timeline[].error_messageChyba, kterou změna přinesla, nebo null.
timeline[].changesCo se změnilo.
timeline[].changes[].fieldPoložka, která se změnila.Hodnoty: status, task_id, task_name, message, model, error_message
timeline[].changes[].fromHodnota předtím.
timeline[].changes[].toHodnota potom.
Požadavek
curl "https://mcptask.online/api/$ACCOUNT/runner_sessions" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
{
  "generated_at": "2026-10-29T12:27:14+01:00",
  "counts": {
    "connected": 2,
    "working": 1,
    "deployed_today": 3
  },
  "snapshots": [
    {
      "id": 41,
      "session_id": "3f2c9a1e-7b44-4d0e-9a51-1c2d3e4f5a6b",
      "machine_id": "workstation-1",
      "model": "claude-opus-5-5",
      "harness": "claude",
      "project_name": "Sparks STORE",
      "task": {
        "relative_id": 13,
        "name": "Design for the Category page"
      },
      "status_code": "processing",
      "thinking": null,
      "message": null,
      "error_message": null,
      "heartbeat_at": "2026-10-29T12:27:10+01:00",
      "closed_at": null,
      "parked": false,
      "actions": [
        {
          "name": "Bash",
          "summary": "bin/rails test test/models/category_test.rb",
          "description": "Run the category model tests",
          "elapsed_seconds": 12,
          "elapsed_label": "12s"
        }
      ],
      "todos": [
        {
          "content": "Add regression test",
          "active_form": "Adding regression test",
          "status_code": "in_progress"
        }
      ],
      "todo_counts": {
        "pending": 0,
        "in_progress": 1,
        "completed": 2,
        "total": 3
      },
      "stage_track": {
        "current_stage": "ci",
        "phase": "ci",
        "stages": [
          {
            "stage": "task",
            "state": "done"
          },
          {
            "stage": "branch",
            "state": "done"
          },
          {
            "stage": "pull_request",
            "state": "done"
          },
          {
            "stage": "ci",
            "state": "now"
          },
          {
            "stage": "deployed",
            "state": "pending"
          }
        ],
        "progress_percent": 75,
        "pull_request_numbers": [
          2731
        ],
        "ci_outcome": null,
        "ci_attempts": 0,
        "ci_not_required": false,
        "deployed_at": null,
        "set_aside": false,
        "set_aside_category": null,
        "runs": 1,
        "restarted": false
      }
    }
  ],
  "timeline": []
}

Číselníky

Kódy, které posíláte v ostatních voláních. Tyto adresy nejsou pod účtem, ale token potřebují jako každé jiné volání.

Stavy úkolů

GET/api/task/states

Hodnoty task_state_code.

Požadavek
curl "https://mcptask.online/api/task/states" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 1,
    "code": "new",
    "name": "New"
  },
  {
    "id": 2,
    "code": "inprogress",
    "name": "In progress"
  }
]

Typy úkolů

GET/api/task/types

Hodnoty task_type_code.

Požadavek
curl "https://mcptask.online/api/task/types" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": 1,
    "code": "task",
    "name": "Task"
  },
  {
    "id": 2,
    "code": "bug",
    "name": "Bug"
  }
]

Druhy úkolů

GET/api/piece/classes

Hodnoty piece_type. id je MD5 otisk code.

Požadavek
curl "https://mcptask.online/api/piece/classes" \
  -H "Authorization: Bearer $MCPTASK_TOKEN"
Odpověď
[
  {
    "id": "e3f530e977d74053c6d70eb84886e756",
    "code": "Epic",
    "name": "Epic"
  },
  {
    "id": "dfba89a600b608b2b724efe1f06f599a",
    "code": "Story",
    "name": "Story"
  },
  {
    "id": "eaeb30f9f18e0c50b178676f3eaef45f",
    "code": "Task",
    "name": "Task"
  }
]