Freelo API

Freelo API skill

Praktický průvodce Freelo v1 API. Když pomáháš s integrací, automatizací nebo dotazem na endpointy, vždy nejprve načti relevantní referenci v references/ místo dohadování.

Zdrojová dokumentace

• Swagger UI: https://api.freelo.io/docs/v1/freelo-api
• OpenAPI specs (autoritativní zdroj pravdy):
  • references/freelo-api.yaml — REST API (cca 6300 řádků, plné popisy včetně non-obvious chování)
  • references/freelo-webhooks.yaml — webhook spec (1000 řádků)
• Pomocné texty: Webhooky CZ, Webhooky EN

Když potřebuješ detail endpointu, který v této SKILL.md není, nejprve sáhni do references/freelo-api.yaml (přesný popis polí, validace, chybové hlášky a non-obvious chování — vše je tam zdokumentováno) a teprve pak vymýšlej.

Základy

Minimální curl příklad

curl -u lukas@viridium.cz:$FREELO_API_KEY \
     -H 'User-Agent: ViridiumIntegration (lukas@viridium.cz)' \
     -H 'Content-Type: application/json' \
     https://api.freelo.io/v1/users/me

Heslo / API key

Pokud uživatel API key nemá v prostředí, požádej ho o něj v chatu (Apple Keychain GUI popup je třeba se vyhnout). Pravděpodobné jméno proměnné: FREELO_API_KEY.

5 kritických gotchas (čti vždy)

1. Timestampy nejsou RFC3339. API posílá naive ISO8601 bez timezone (např. 2026-04-24T11:12:38) v Europe/Prague (CET/CEST, DST!). Strict parser jako time.Parse(time.RFC3339, ...) v Go selže. Webhook payloady mají offset (2026-04-24T15:30:00+02:00) — jiný formát než REST! Detail v references/gotchas.md.
2. Měna jako string × 100. "100025" = 1000.25. Žádné tečky, čárky, ani floaty. Měny: CZK, EUR, USD.
3. Stránkování přes ?p= od 0, ne 1.
4. Edit používá POST, ne PUT/PATCH (historický důvod — týká se task editu, comment editu, work report editu, note editu...).
5. Mnoho endpointů má skryté side-effecty / non-obvious chování (např. první komentář na tasku se stane description; GET /public-link/task/{id} link vytvoří pokud neexistuje; worker_id je tichý alias pro worker; smart-taskcheck tiše degraduje na simple). Vždy zkontroluj references/gotchas.md před voláním nestandardního endpointu.

Když uživatel chce konkrétní operaci

Sumář endpointů (32 resource skupin, ~95 endpointů)

Projects: /projects, /all-projects, /invited-projects, /archived-projects, /template-projects, /user/{id}/all-projects, /project/{id} (GET/DELETE), /project/{id}/workers, /project/{id}/archive, /project/{id}/activate, /project/{id}/remove-workers/by-{ids,emails}, /project/create-from-template/{id}

Project Labels: /project-labels/find-available, /project-labels/{id} (POST/DELETE), /project-labels/{add-to,remove-from}-project/{id}

Pinned Items: /project/{id}/pinned-items (GET/POST), /pinned-item/{id} (DELETE)

Tasklists: /project/{id}/tasklists (POST), /all-tasklists, /project/{pid}/tasklist/{tid}/assignable-workers, /tasklist/{id} (GET), /tasklist/create-from-template/{id}

Tasks: /project/{pid}/tasklist/{tid}/tasks (GET/POST), /all-tasks, /tasklist/{id}/finished-tasks, /tasks/relations (POST bulk), /task/{id} (GET/POST=edit/DELETE), /task/{id}/{activate,finish}, /task/{id}/move/{tasklist_id}, /task/{id}/projects (multi-project), /task/{id}/relations, /task/{id}/projects/{pid}, /task/{id}/description (GET/POST), /task/{id}/reminder (POST/DELETE), /public-link/task/{id} (GET/DELETE), /task/create-from-template/{id}, /task/{id}/total-time-estimate (POST/DELETE), /task/{id}/users-time-estimates/{uid} (POST/DELETE)

Subtasks: /task/{id}/subtasks (GET/POST)

Task Labels: /task-labels (POST bulk-create), /task-labels/{add-to,remove-from}-task/{id}

Comments: /task/{id}/comments (POST), /comment/{id} (POST=edit), /all-comments

Time Tracking: /timetracking/{start,stop,edit,status} — pouze 1 běžící session per user

Work Reports: /work-reports, /task/{id}/work-reports (POST), /work-reports/{id} (POST=edit/DELETE)

Invoicing: /issued-invoices, /issued-invoice/{id}, /issued-invoice/{id}/{reports,reports-json,mark-as-invoiced}

Users: /users/me, /users, /users/project-manager-of, /users/manage-workers (POST=invite), /user/{id}/out-of-office (GET/POST/DELETE)

Notifications: /all-notifications, /notification/{id}/mark-as-{read,unread}

Events (audit log): /events

Files: /file/{uuid} (GET=download), /file/upload (POST multipart, max 100 MB), /all-docs-and-files

States: /states (lookup tabulka)

Custom Fields: /custom-field/get-types, /custom-field/create/{pid}, /custom-field/{rename,delete,restore}/{uuid}, /custom-field/add-or-edit-{value,enum-value}, /custom-field/delete-value/{uuid}, /custom-field-enum/get-for-custom-field/{uuid}, /custom-field-enum/{create,change,delete,force-delete}/{uuid}, /custom-field/find-by-project/{pid}

Notes/Documents: /project/{id}/note (POST), /note/{id} (GET/POST/DELETE)

Search: /search (POST, Elasticsearch-backed, povinný search_query)

Webhooks (management): /webhooks (POST=register), /webhook/{uuid} (DELETE)

Webhook subscription names (11)

task_created, task_edited, task_finished, task_deleted, task_undeleted, task_activated, task_moved, tasklist (all lifecycle), comment (all lifecycle), note (= document_*), workreport (all lifecycle).

Bezpečnost: Freelo nepodepisuje payloady (žádný HMAC). Použij unguessable URL path s náhodným tokenem jako capability. Detail v references/webhooks.md.

Když nevíš

1. Sáhni do references/freelo-api.yaml přes Read na konkrétní řádek (každý endpoint má summary + description + ## Behavior notes (non-obvious) sekci).
2. Hledej v souboru grep -n na operationId nebo path.
3. Pokud uživatel chce příklad konkrétní operace, kombinuj references/recipes.md se schématy z references/schemas.md.
4. Pro webhooky vždy načti references/webhooks.md — payload formát + retry policy + dedup pattern jsou kritické.