WorkThroughLine za programere - REST API, GitHub, GitLab i MCP

Kako da počneš

API je REST preko HTTPS-a i vraća JSON. Svaki zahtev je vezan za jednu organizaciju preko API ključa.

1. Napravi API ključ

U aplikaciji otvori Podešavanja → API ključevi i napravi ključ. Kopiraj ga odmah - prikazuje se samo pri kreiranju. Ključevi izgledaju kao pos_sk_….

2. Bazni URL i autentikacija

Šalji ključ u x-api-key zaglavlju na svakom zahtevu. Bazni URL je:

https://app.workthroughline.com/api/v1

3. Prvi zahtev

Izlistaj svoje work item-e:

curl https://app.workthroughline.com/api/v1/work-items \
  -H "x-api-key: pos_sk_your_key_here"

GitHub i GitLab integracija

WorkThroughLine povezuje razvojni rad sa delivery kontekstom bez čuvanja pristupnog tokena za Git provider. Svaki repozitorijum dobija jedinstveni webhook URL i tajnu.

U Settings → GitHub / GitLab poveži repozitorijum i izaberi opcione status automatizacije.
U provideru dodaj generisani webhook URL i tajnu. Za GitHub izaberi application/json, Push i Pull request događaje; za GitLab Push i Merge request događaje.
Stavi ključ work item-a u naziv grane, commit poruku ili PR/MR. WTL automatski prikazuje granu, commit i review na kartici.

Primer konvencije za povezivanje

feature/WI-42-checkout-fix
git commit -m "WI-42 handle declined cards"
Pull request: "WI-42 Checkout reliability"

Rezultat: developer i PM na work item-u vide šta je otvoreno, merge-ovano i u kojoj grani, uz direktan link ka GitHub-u ili GitLab-u.

GitHub HMAC potpis i GitLab secret token proveravaju se pre obrade. Repozitorijum i svaki artefakt vezani su za jednu organizaciju; pogrešan potpis se odbija pre tenant obrade.

MCP za Codex i Claude Code

Svaki ADMIN, PM ili DEV pravi jedan lični API ključ. Klijent ga šalje pri svakom MCP zahtevu, a WTL primenjuje istu rolu, maker pravila i tenant izolaciju kao u aplikaciji.

Codex - postavi PRODUCT_OS_API_KEY u environment, zatim registruj hostovani server:

codex mcp add workthroughline --url https://mcp.workthroughline.com/mcp --bearer-token-env-var PRODUCT_OS_API_KEY

Claude Code - koristi isti environment ključ bez upisivanja tajne u konfiguraciju:

claude mcp add-json --scope user workthroughline '{"type":"http","url":"https://mcp.workthroughline.com/mcp","headers":{"x-api-key":"${PRODUCT_OS_API_KEY}"}}'

Šta AI može da koristi

Ciljeve i njihova objašnjenja, OKR-ove i key results, intervjue, transkripte, sažetke, analize i insight-e, opportunities, solutions, eksperimente, sve work item-e, sprintove, veze, komentare i GitHub/GitLab artefakte. get_discovery_context vraća objedinjeni evidence-first paket sa paginacijom.

Primer discovery zahteva

Analiziraj sve intervjue i analize, pogledaj aktivne produktne ciljeve i OKR-ove, proveri postojeće opportunities, solutions i eksperimente, pa predloži nedostajuća rešenja sa dokazima. Nemoj ništa kreirati dok ne odobrim.

Ključ se prikazuje samo jednom. Stakeholder i guest nalozi ne mogu da naprave ključ niti da menjaju podatke preko MCP-a.

Konvencije

Autentikacija

Prosledi x-api-key na svakom zahtevu. Ključ deluje sa ulogom za koju je napravljen i vezan je za svoju organizaciju.

Ograničenje brzine

100 zahteva u minuti po klijentu. Prekoračenje vraća HTTP 429.

Greške

Odgovori van 2xx vraćaju JSON { "error", "message" }, a kod validacije i details objekat.

Paginacija

Velike liste koriste cursor paginaciju: prosledi ?cursor=… &limit=… i prati nextCursor dok ne bude null.

Webhook-ovi

Pretplati HTTPS endpoint na događaje i mi šaljemo potpisani JSON (POST) kada se dese. Isporuka se ponavlja uz eksponencijalni backoff.

Tipovi događaja

work_item.createdA work item was created.

work_item.updatedA work item was edited.

work_item.status_changedA work item moved to a new status (payload adds `previousStatus`).

ckr.createdAn OKR was created.

ckr.updatedAn OKR was edited.

opportunity.createdA discovery opportunity was created.

experiment.concludedAn experiment was concluded (SUCCEEDED / FAILED / INCONCLUSIVE).

intake.createdA stakeholder submitted intake (no submitter contact is ever sent).

changelog.publishedA changelog entry was published.

Payload

Svaka isporuka je verzionisani omotač. id je isti za sve endpoint-e jednog događaja - koristi ga kao idempotency ključ.

{
  "id": "b3f1c2e4-0000-0000-0000-000000000000",
  "event": "work_item.status_changed",
  "apiVersion": "2026-07-13",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "organizationId": "a1b2c3d4-0000-0000-0000-000000000000",
  "data": {
    "id": "…",
    "key": "WI-42",
    "title": "Checkout crash",
    "status": "DONE",
    "previousStatus": "IN_REVIEW"
  }
}

Proveri potpis

Svaki zahtev nosi X-WTL-Signature: sha256=<hmac>. Ponovo izračunaj HMAC-SHA256 sirovog tela sa svojim webhook ključem i uporedi u konstantnom vremenu.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, signature, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(signature ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}

// Express - note express.raw so you verify the EXACT bytes we signed:
app.post('/hooks/wtl', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('X-WTL-Signature'), process.env.WTL_WEBHOOK_SECRET))
    return res.sendStatus(401);
  const event = JSON.parse(req.body.toString());
  // handle event.event / event.data … then ack quickly
  res.sendStatus(200);
});

Nikada ne šaljemo lične podatke preko potrebnog (npr. kontakt podnosioca intake-a je izostavljen). Zovemo samo javne HTTPS/HTTP endpoint-e - privatne, loopback i metadata adrese su blokirane.

Endpointi

Primer - registruj webhook:

curl -X POST https://app.workthroughline.com/api/v1/webhooks \
  -H "x-api-key: pos_sk_your_key_here" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com/hooks/wtl","events":["work_item.status_changed"]}'

API, Git i AI integracije